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

# Agent context

> Keep one source of agent instructions in .outerlayer/ and compile it into each tool's native files.

Coding agents read instructions from different places. Claude Code reads `CLAUDE.md` and `.claude/`. Cursor reads `AGENTS.md`, `.agents/` and `.cursor/`. Codex reads `AGENTS.md` and `.agents/`. OuterLayer keeps one source in `.outerlayer/` and compiles it into each of those. [What each target gets](/reference/outerlayer-directory#what-each-target-gets) lists every file.

## Set up

Create `.outerlayer/config.json` naming the tools you run:

```json theme={"system"}
{
  "targets": ["claude-code"]
}
```

Valid targets are `claude-code`, `cursor`, `codex`, `copilot` and `factory`.

Write the shared instructions in `.outerlayer/AGENTS.md`. Put skills under `.outerlayer/skills/<name>/SKILL.md`.

## Compile

```bash theme={"system"}
outerlayer context emit
```

This writes each target's native files. It always overwrites a root `AGENTS.md`, and with the `claude-code` target a root `CLAUDE.md`. Move their content into `.outerlayer/AGENTS.md` first.

In CI, check that the committed outputs match their sources:

```bash theme={"system"}
outerlayer context emit --check
```

It writes nothing, and exits 1 when an output differs from its source or is missing. It also exits 1 for an orphaned output: a generated file whose source is gone. It cannot spot an orphaned `.mcp.json` or `.cursor/mcp.json`, because JSON has no room for the generated-file header.

## Starter skill pack

`outerlayer init --template default` installs seven skills into `.outerlayer/skills/`, in two classes. It also writes `.outerlayer/policy.yaml`, which requires review, and `.outerlayer/validators/code-review.yaml`, the code review check. It writes each only when it is missing. See [Policy and validators](/policy-and-validators#the-code-review-check).

```bash theme={"system"}
outerlayer init
outerlayer init --template default
```

A plain `outerlayer init` installs the same skills and policy, then adds the OuterLayer MCP server. It writes `.outerlayer/config.json` if there is none and runs `outerlayer context emit`, so the skills work in Claude Code. The MCP server needs `outerlayer login` on the machine. It changes nothing you wrote and commits nothing. With `--local`, `--template default` only writes the files into `.outerlayer/`. See [`outerlayer init`](/reference/cli-capture#outerlayer-init) for when the step is skipped and where the MCP entry goes.

Templates are copied once, never overwritten, and belong to your team. Edit them freely. If a template's directory already exists, `init` leaves it as it is.

* `spec` turns an idea into an approved issue, then offers to start the build.
* `writing-specs` holds the discipline a spec follows.
* `build` takes a work item through implementation, review and release. At intake it records the item's criteria with `outerlayer emit criteria`. It reads them from an `## Acceptance criteria` section with ids, or from a bullet list under an `Acceptance:` line, which it gives ids of the form `AC-<item number>-NN`. When the item already has a recorded list, that list stands. The build cannot read it, so it holds the work to its own reading of the issue's criteria.

Maintained skills follow the installed CLI. They are rewritten on every `outerlayer context emit`, so do not edit them: your edit is lost.

* `emitting-evidence` says when and how to attach proof to a change.
* `amend` answers the review threads waiting on an agent.
* `reporting-findings` says when and how to record a problem an agent hit in the factory.
* `outerlayer` says what a work item is, that `OUTERLAYER_WORK` carries its number, and how an issue becomes a pull request.

The first line after a skill's frontmatter names its class. A maintained skill also names the CLI version that wrote it.

`outerlayer context emit --check` reports a maintained skill that differs from the installed CLI as drift, and exits 1. It never reports a template. A teammate on an older CLI version sees drift too, so keep one CLI version across the team.

## Install the maintained skills

```bash theme={"system"}
outerlayer import capture
```

This installs or rewrites `emitting-evidence`, `amend`, `reporting-findings` and `outerlayer`, and names each file it rewrote. When `.outerlayer/AGENTS.md` exists, it appends a short evidence snippet to it. Run `outerlayer context emit` afterwards.

## Port an existing Ruler tree

```bash theme={"system"}
outerlayer import ruler
```

This copies a `.ruler/` tree into `.outerlayer/` and leaves `.ruler/` in place. `ruler.toml` is not imported. It never overwrites an existing `.outerlayer/`.

## Instructions that come from another repository

A factory can name one repository as the context source for others. Those repositories commit no instructions. The CLI writes them into the working tree at the start of every session, and `outerlayer context materialize` adds the four maintained skills at the installed CLI's version. See [Share instructions across repositories](/share-instructions-across-repositories).


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