The .outerlayer directory

A repository in the current layout keeps only OuterLayer’s own files in .outerlayer/. Its instructions are in AGENTS.md, its skills in .agents/skills/ and its MCP servers in .mcp.json. See Agent context.

.outerlayer/
  config.json                   layout, and the targets to compile for
  policy.yaml                   which checks run and how much each counts
  validators/*.yaml             custom checks

A repository that has not moved to that layout also keeps its sources in .outerlayer/, and outerlayer init --update moves them out:

.outerlayer/
  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`, `commands/`, and in a repository that has not moved, `AGENTS.md`, `skills/` and `mcp.json`	`outerlayer context emit` on your machine	The working tree
`config.json` `governs` list	Nothing. The key is ignored	Not read
`policy.yaml`, `validators/`	The evidence evaluator	The base branch of the pull request being evaluated, or the control plane 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"]
}

Key	Meaning
`targets`	Tools to compile for: `claude-code`, `cursor`, `codex`, `copilot`, `factory`. Required and non-empty for `context emit`.
`layout`	`2` when the repository keeps `AGENTS.md`, `.agents/skills/` and `.mcp.json` as real files. `outerlayer init --update` sets it. A control plane declares it for the same reason.
`governs`	Ignored. A control plane governs every repository its factory links, and a repository named here is not governed because of it. CLI versions before 0.17.0 still read it, so delete it once every machine and runner host runs 0.17.0 or later. `outerlayer doctor` warns when one is left. See Share instructions across repositories.

What each target gets

In a repository that has not moved, 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 that another linked repository of its factory governs may commit these files, and a repository that is governed commits its own CLAUDE.md, AGENTS.md and skills. The control plane’s files are not written into it. A laptop session gets them through outerlayer claude, from a copy under ~/.outerlayer/context/. outerlayer claude keeps one folder for each checkout that has skills in .agents/skills/ under ~/.outerlayer/context/own/. Its .claude/skills/ links to each of those skills, so Claude Code loads them under their own names. The CLI removes the folder of a checkout that no longer exists at the next launch. An earlier CLI committed .outerlayer-pin.json at the repository root. The launcher and the session hook do not read it, and a governed repository can delete it. 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