Skip to main content
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 lists every file.

​
Set up

Create .outerlayer/config.json naming the tools you run:
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

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

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

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.