The .outerlayer directory

.outerlayer/
  config.json                   targets to compile for, repositories this one governs
  AGENTS.md                     shared agent instructions, compiled into each target
  skills/<name>/SKILL.md        skills, for Claude Code, Cursor and Codex
  skills/<name>/references/*.md reference files compiled with their skill
  commands/*.md                 slash commands, for Claude Code and Cursor
  agents/*.md                   subagents, accepted but compiled for no target
  policy.yaml                   which checks run and how much each counts
  validators/*.yaml             custom checks
  mcp.json                      MCP servers, for Claude Code and Cursor

A .outerlayer/ directory in a subfolder compiles the same way into that subfolder, such as packages/api/CLAUDE.md from packages/api/.outerlayer/AGENTS.md.

Who reads what

File	Read by	From
`config.json`, `AGENTS.md`, `skills/`, `commands/`, `mcp.json`	`outerlayer context emit` on your machine	The working tree
`config.json` `governs` list	The gateway, when this repository is a context source	The pinned commit
`policy.yaml`, `validators/`	The evidence evaluator	The base branch of the pull request being evaluated, or the context source when the factory has one
`policy.yaml` `build` key	The gateway, when it issues a repository token	The item repository’s default branch

A change to policy or validators takes effect when it merges to the base branch, not when it is pushed on a feature branch.

config.json

{
  "targets": ["claude-code", "cursor"],
  "governs": ["acme/app"]
}

Key	Meaning
`targets`	Tools to compile for: `claude-code`, `cursor`, `codex`, `copilot`, `factory`. Required and non-empty for `context emit`.
`governs`	Repositories whose agent instructions this repository supplies. See Share instructions across repositories.

What each target gets

outerlayer context emit writes these files for each target in targets:

Target	Instructions	Skills	MCP servers
`claude-code`	`CLAUDE.md`	`.claude/skills/<name>/`	`.mcp.json`
`cursor`	`AGENTS.md`	`.agents/skills/<name>/`	`.cursor/mcp.json`
`codex`	`AGENTS.md`	`.agents/skills/<name>/`	Nothing, with a warning
`copilot`, `factory`	`AGENTS.md`	Nothing, with a warning	Nothing, with a warning

AGENTS.md is written whatever the targets are. For Cursor, each ${VAR} in mcp.json becomes ${env:VAR}, Cursor’s syntax for an environment variable.

commands/

Each Markdown file is a slash command. outerlayer context emit compiles it per target:

Target	Output	How you run it
`claude-code`	`.claude/commands/<name>.md`, keeping subfolders	`/<name>`, or `/<folder>:<name>` for `commands/<folder>/<name>.md`
`cursor`	`.cursor/commands/<name>.md`, keeping subfolders, body only	`/<name>`
`codex`	Nothing. `context emit` prints a warning, because Codex keeps commands in its TOML config.
`copilot`, `factory`	Nothing. `context emit` prints a warning.

Claude Code gets the file as written, frontmatter included. Cursor gets the frontmatter description as a comment and drops argument-hint.

policy.yaml and validators

See Policy and validators for every key.

Governed repositories

A repository named in another’s governs list commits none of these files. It gets them written into its working tree at session start instead. One that still commits them gets a warning row on every pull request until they are removed. It commits one file of its own: .outerlayer-pin.json at its root, which records the context source’s commit. See Share instructions across repositories.

Get started

Connect

Work items

Run builds

Your team

Configure a repository

Privacy

CLI

Files

Tools

Self-host

The .outerlayer directory

Who reads what

config.json

What each target gets

commands/

policy.yaml and validators

Governed repositories

​Who reads what

​config.json

​What each target gets

​commands/

​policy.yaml and validators

​Governed repositories

Who reads what

config.json

What each target gets

commands/

policy.yaml and validators

Governed repositories