Skip to main content
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.
The policy file and the two checks are described in Policy and validators. What a plain outerlayer init adds beside the skills is in Agent context.

​
Templates

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

​
The build skill

The build process lives in outerlayer-build, a maintained skill, so a better process reaches you when you upgrade the CLI. Your build skill starts it. It takes a work item through the phases Intake, Criteria, Implement, Review, Pull request and Evidence. At the start of each phase it reports the step on the item’s Activity tab, then applies your changes for that phase. In the Criteria phase, the build records the item’s criteria with outerlayer emit criteria. Record the criteria says how it reads, numbers and drafts them. 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.

​
Maintained skills

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/. Each has a link in ~/.claude/skills/, where Claude Code reads it. 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/. It comes back only when you run outerlayer init, outerlayer init --local or outerlayer claude. 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.
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.