> ## Documentation Index
> Fetch the complete documentation index at: https://docs.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.

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

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


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