Skip to main content
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

.outerlayer/ holds only OuterLayer’s own files. See The .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. It writes AGENTS.md if you have no AGENTS.md or CLAUDE.md. It writes the starter skills to .agents/skills/. It links .claude/skills to ../.agents/skills. It writes no file with the generated-by header.
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.
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.

​
Move a repository to this layout

An earlier layout kept the sources in .outerlayer/AGENTS.md, .outerlayer/skills/ and .outerlayer/mcp.json. outerlayer context emit then wrote copies into CLAUDE.md, AGENTS.md, .claude/skills/ and .mcp.json, and you committed both. A repository in that layout keeps working until you move it. Move it with one command:
Run outerlayer init --update --dry-run first to see the plan. The command works in this order, in every scope. A scope is the repository root, or a folder below it that has its own .outerlayer/ directory.
  1. It removes each generated file. These are the root CLAUDE.md and AGENTS.md, and the files under .claude/skills/ and .agents/skills/. A file counts as generated when it has the header and exactly the bytes emit writes from its source.
  2. It moves .outerlayer/AGENTS.md to AGENTS.md. It moves .outerlayer/skills/ to .agents/skills/.
  3. It moves the servers in .outerlayer/mcp.json into .mcp.json.
  4. It links .claude/skills to ../.agents/skills.
  5. It sets "layout": 2 in .outerlayer/config.json.
The command never deletes a file you edited. A generated file with other bytes is kept, and the command lists its path. A source stays where it is when its new place holds a file of yours. The command lists it, and does not set the layout. Resolve the clash and run the command again. A committed source also stays when git ignores its new place. After the move, the next commit would delete it from the repository. Add an exception to .gitignore, such as !/.agents/, and run the command again. If .claude/skills/ still holds a file that is not generated, the command leaves the folder as it is. It makes no link, because a link would hide the file. It lists the file. To move without the link, run outerlayer init --update --no-skills-link. Two things stay where they are, because they have no new home:
  • Command sources in .outerlayer/commands/, and the commands compiled from them. Run outerlayer context emit after you change a command.
  • An .outerlayer/mcp.json in a repository with a cursor target. Cursor needs it to write .cursor/mcp.json.
After the move, outerlayer context emit --check exits 0. The update also changes the paths in starter files you have not edited. A file you edited may still name .outerlayer/skills/. The command lists such files so you can change the path.

​
A control plane repository

A control plane repository holds the skills that govern other repositories. A CLI or runner older than 0.21.0 does not read .agents/skills/. It delivers none of those skills. Move a control plane with outerlayer init --update --control-plane. The command prints this warning and makes no link. Keep .claude/skills/ as an identical copy of .agents/skills/ until those CLIs and runners upgrade. Make every edit in both folders. See Share instructions across repositories.

​
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. A repository that has not moved keeps its sources in .outerlayer/ and compiles them. Create .outerlayer/config.json naming the tools you run:
Valid targets are claude-code, cursor, codex, copilot and factory. Put the shared instructions in .outerlayer/AGENTS.md and skills in .outerlayer/skills/<name>/SKILL.md. Then compile:
This writes each target’s native files. What each target gets lists every file. For the claude-code and codex targets, emit prints a notice that names outerlayer init --update. The notice stops once the repository has moved. In CI, check that the committed outputs match their sources:
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. A plain outerlayer context emit deletes it. 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 nine skills, in two classes. The four templates go into .agents/skills/. A repository that has not moved gets them in .outerlayer/skills/. The five maintained skills go into your home folder, in ~/.agents/skills/, and not into the repository. It also writes .outerlayer/policy.yaml, which requires review, and two checks: .outerlayer/validators/code-review.yaml, the code review check, and .outerlayer/validators/acceptance-criteria.yaml, the criteria judge check. It writes each only when it is missing. See Policy and validators.
A plain outerlayer init installs the same skills and policy, then adds two MCP servers: outerlayer, and outerlayer-docs at https://docs.outerlayer.ai/mcp, which lets your agent look up how OuterLayer works. It writes AGENTS.md if there is none, writes .outerlayer/config.json if there is none, and links .claude/skills to the skills, so they work in Claude Code. The outerlayer server needs outerlayer login on the machine. It changes nothing you wrote and commits nothing. With --local, --template default only writes the files. See outerlayer init for when the step is skipped and where the MCP entries go. 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. To get a later CLI’s version of the templates, the policy and the two checks, run outerlayer init --update. It replaces only files you have not edited. See Update the files init wrote.
  • spec turns an idea into an approved issue, then offers to start the build.
  • writing-specs holds the discipline a spec follows.
  • writing-tests holds the standard a test meets: strong assertions, the right seam, a criterion id in a comment above the test, and an optional mutation check. Add your own test commands and rules to it.
  • build holds only your repository’s changes to the build process. It tells the agent to read outerlayer-build first, then lists your changes by phase. Edit it freely: the CLI never rewrites it.
The build process lives in outerlayer-build, a maintained skill, so a better process reaches you when you upgrade the CLI. Only build starts it. outerlayer-build holds the build process. It takes a work item through the phases Intake, Criteria, Implement, Review, Pull request and Evidence. At each phase start it reports the step with outerlayer emit step, then applies your changes for that phase. At intake it records the item’s criteria with outerlayer emit criteria. The agent reads the criteria in any form the issue writes them, and keeps each one’s text as written. It keeps the issue’s ids when every criterion has one that fits the id grammar, and otherwise numbers them AC-<item number>-NN. When the issue has no criteria, it drafts them from the issue’s description and records them marked as drafted. 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. Your build lists changes under ## Changes for this repository, each under a ### heading with the name of the phase it applies to. A change can do three things:
  • Add a step to a phase.
  • Set a value the core names as a setting. The settings are the gate command, the planning model, the implementing model, the reviewing model, the branch prefix and the agent budget, which is the most agents one run may spawn. outerlayer-build gives each setting’s default.
  • Turn off a step the core marks optional.
A change never relaxes a state rule, such as one redo per piece of work, reporting only observed status, and filing no issues. When a change conflicts with the core, the core wins and the final report names the conflict. A change the run could not apply is recorded as a finding. The final report lists the changes applied, by phase. outerlayer doctor warns in these cases:
  • Your build does not name outerlayer-build.
  • A heading under your changes matches no phase.
  • An agent’s skills folder holds a build that names ../outerlayer-build/SKILL.md, with no outerlayer-build beside it.
  • ~/.agents/skills/ lacks this CLI version’s maintained skills. Run outerlayer init --local.
  • A repository still commits a maintained skill folder. Run outerlayer init --update.
Every spec declares two verdicts, each with a one-line reason. The docs verdict says whether the change needs a page in your README, docs/ or docs site. The structural verdict says whether it adds a package or app, introduces a seam between components, or moves data across a boundary. /spec decides both before you approve the issue. writing-specs/references/agents-snippet.md holds optional writing rules: write for a reader who was not in the session, and keep session history out of code comments. init does not add them anywhere. To hold every agent to them, paste the file into your root AGENTS.md. A repository that has not moved pastes it into .outerlayer/AGENTS.md and runs outerlayer context emit. Maintained skills follow the installed CLI. Their names start with outerlayer-, so none can land on a skill of your own. The CLI keeps the maintained skills once per machine, in ~/.agents/skills/. Claude Code reads only ~/.claude/skills/, so each skill has a link there to its folder. Where a link cannot be made, the folder holds a copy. outerlayer init installs them, and each later outerlayer command keeps them at its own version. A repository carries none of them. So two teammates on different CLI versions each get skills that match their own CLI. Do not edit a maintained skill. The next command overwrites your edit. To stop using one, delete its folder in ~/.agents/skills/. The copies come back only when you run outerlayer init, outerlayer init --local or outerlayer claude, because only those commands create them. The hooks, the status line and outerlayer daemon never write them. If a write fails, the command still does its work, and outerlayer doctor reports the gap. A repository that has not moved keeps compiled copies, and outerlayer context emit rewrites them. A session that gets its instructions from a control plane has all five, whatever the control plane holds. A cloud session on a machine with no CLI has none of them.
  • outerlayer-evidence says when and how to attach proof to a change.
  • outerlayer-amend answers the review threads waiting on an agent and resolves merge conflicts on a pull request.
  • outerlayer-findings says when and how to record a problem an agent hit in the factory.
  • outerlayer-build holds the build process, which build tells the agent to follow. build reads it at ~/.agents/skills/outerlayer-build/SKILL.md.
  • outerlayer-cli says what a work item is, that OUTERLAYER_WORK carries its number, and how an issue becomes a pull request.
CLIs before this naming called them emitting-evidence, amend, reporting-findings and outerlayer. See Upgrade OuterLayer for moving a repository to the new names. The first line after a skill’s frontmatter names its class. A maintained skill also names the CLI version that wrote it. In a repository that has not moved, outerlayer context emit --check reports drift for a maintained skill that differs from the installed CLI, 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.

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

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