> ## Documentation Index
> Fetch the complete documentation index at: https://docs-stg.outerlayer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# The .outerlayer directory

> What lives in a repository's .outerlayer/ and which branch each file is read from.

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](/agent-context#the-layout).

```
.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

```json theme={"system"}
{
  "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](/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](/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](/share-instructions-across-repositories).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.