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

# Agent context

> Keep agent instructions in AGENTS.md and skills in .agents/skills/. Nothing generated is committed.

Coding agents read instructions from different places. Claude Code and Codex both read `AGENTS.md` at the repository root. Codex reads skills from `.agents/skills/`. Claude Code reads skills from `.claude/skills/`.

OuterLayer keeps one real copy of each file. Your instructions are in `AGENTS.md`. Your skills are in `.agents/skills/`. Your MCP servers are in `.mcp.json`. A link makes `.claude/skills` point at `.agents/skills`. Nothing is generated, so there is nothing to compile and nothing extra to commit.

## The layout

```text theme={"system"}
AGENTS.md                  shared agent instructions
.agents/skills/<name>/     skills, one folder each
.mcp.json                  MCP servers
.claude/skills             a link to ../.agents/skills
.outerlayer/
  config.json              declares "layout": 2
  policy.yaml              which checks run
  validators/*.yaml        custom checks
```

`.outerlayer/` holds only OuterLayer's own files. See [The .outerlayer directory](/reference/outerlayer-directory).

A folder below the root can have its own `AGENTS.md` and `.agents/skills/`. The CLI writes and moves these nested files. A nested scope works in Claude Code only if Claude Code reads a nested `AGENTS.md`, which this page does not guarantee.

## Set up

Run `outerlayer init` in a repository with no agent context:

```bash theme={"system"}
outerlayer init
```

It writes `AGENTS.md` if you have no `AGENTS.md` or `CLAUDE.md`, and `.outerlayer/config.json` if there is none. It writes the starter skills to `.agents/skills/`, with a policy file and two starter checks. It links `.claude/skills` to `../.agents/skills`, so the skills work in Claude Code. It writes no file with the generated-by header. It changes nothing you wrote and commits nothing.

`outerlayer init` installs the skills, then adds two MCP servers: `outerlayer`, and `outerlayer-docs` at `https://docs.outerlayer.ai/mcp`, which lets your agent look up how OuterLayer works. The `outerlayer` server needs `outerlayer login` on the machine. With `--local`, `--template default` only writes the files. See [`outerlayer init`](/reference/cli-capture#outerlayer-init) for when the step is skipped and where the MCP entries go.

The skills `init` installs, and the build skill your team edits, are described in [Starter skills and the build](/starter-skills).

To skip the link, run `outerlayer init --no-skills-link`. A session you start with `outerlayer claude` finds the skills without the link. A plain `claude` needs it.

<Note>
  On Windows, git commits a link only when `core.symlinks` is true. Without it, git writes a text file in place of the link, and Claude Code finds no skills. Run `git config core.symlinks true`, or start sessions with `outerlayer claude`.
</Note>

## Move a repository to this layout

A repository in the earlier layout, with its sources in `.outerlayer/`, moves with `outerlayer init --update`. The steps are in [Move a repository to the AGENTS.md layout](/upgrade#move-a-repository-to-the-agentsmd-layout).

## Compile for other tools

Claude Code and Codex need no compile step. Cursor, Copilot and Factory targets, and slash commands, still use [`outerlayer context emit`](/reference/cli-context#outerlayer-context-emit). It writes each target's native files from `.outerlayer/`. Valid targets are `claude-code`, `cursor`, `codex`, `copilot` and `factory`, named under `targets` in `.outerlayer/config.json`. [What each target gets](/reference/outerlayer-directory#what-each-target-gets) lists every file.

In CI, run `outerlayer context emit --check`. It writes nothing, and exits 1 when an output is missing, differs from its source, or is orphaned. See [`outerlayer context emit`](/reference/cli-context#outerlayer-context-emit). A repository that has not moved compiles every target this way: see [Compile a repository that has not moved](/upgrade#compile-a-repository-that-has-not-moved).

## Instructions that come from another repository

A factory can name one repository as the control plane for others. A laptop session in those repositories gets the shared instructions through `outerlayer claude`, from a copy kept outside the repository. The five maintained skills come at the installed CLI's version. A governed repository still commits its own instructions and skills. See [Share instructions across repositories](/share-instructions-across-repositories).

## Where a session finds skills

Claude Code looks for skills in `.claude/skills/`. Codex and other tools that follow the `SKILL.md` standard look in `.agents/skills/`. A repository in the layout above keeps one copy of each skill in `.agents/skills/`.

`outerlayer claude` also gives Claude Code the skills in the checkout's own `.agents/skills/`, under their own names. It does this from outside the checkout, with a folder under `~/.outerlayer/context/own/` that links to each skill's folder. Nothing is written into the checkout, and an edit to a skill shows at the next session. A runner starts a build's agent the same way.

A skill kept in both `.agents/skills/` and `.claude/skills/` loads once, from `.claude/skills/`. A checkout whose `.claude/skills` is a link to `../.agents/skills` needs nothing added.

Only the repository root's `.agents/skills/` is attached, not nested folders below it. A `claude` started without `outerlayer claude` does not see skills kept only in `.agents/skills/`. A control plane can keep its skills in `.agents/skills/` too. See [Share instructions across repositories](/share-instructions-across-repositories#keep-skills-in-agentsskills).


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