Skip to main content
A new CLI version reaches three places: the machines people work on, the repositories they work in, and the runners that run builds. Each needs one step.

​
On each machine

Install the new version the way you installed the first:
If you run the CLI with npx, name the version, as in npx -y @outerlayer/cli@latest. Without it, npx can run a copy from its cache. Then run outerlayer init --local on a machine where a person works. It installs the maintained skills in ~/.agents/skills/. Then run outerlayer doctor. It names anything else on the machine that still needs a step. The CLI names a newer version after a command in a terminal and at session start. That version is the newest release, or the version that the factory pins. The notice gives an exact-version install command, such as npm install -g @outerlayer/cli@0.26.1. It repeats until the machine runs that version. A machine with no login gets no notice. Set OUTERLAYER_NO_UPDATE_NOTICE to turn it off. At session start the CLI also tells you when the maintained skills in ~/.agents/skills/ come from another CLI version. Run outerlayer init --local to fix it. Keep one CLI version across a team. In a repository that still keeps its own .outerlayer/ directory, a teammate on an older version sees the maintained skills as changed, and their context emit --check fails.

​
In each repository

A repository on the AGENTS.md layout needs one command and a commit. The command also removes the copies of the maintained skills that the repository still commits:
A repository that still keeps its own .outerlayer/ directory needs two:
  • context emit rewrites the maintained skills to the installed version and recompiles every tool’s copy.
  • init --update brings the template skills, the policy and the two checks up to date where you have not edited them. In the AGENTS.md layout, it also rewrites the maintained skills. See Update the files init wrote.
Review the diff and commit it. Nothing is committed for you. A repository whose instructions come from a control plane needs neither command. Each session writes the maintained skills at the installed CLI’s version. Run them in the control plane repository instead.

​
On each build host

A runner started as a service updates itself and needs nothing. A runner with updates off is upgraded by hand. See Keep the runner up to date. Then check the commands in its config file with outerlayer runner check. A command that names a skill by a name it no longer has is listed under note.

​
Changes that need you to act

​
Maintained skills start with outerlayer-

The maintained skills have new names, so they can no longer land on a skill of your own: What to do:
  1. In a repository with its own .outerlayer/, run outerlayer context emit and commit. It writes each skill under its new name, then deletes the old directory and every copy compiled from it, such as .claude/skills/amend/. Until you do, context emit --check reports the old files as retired. A skill of your own with one of the earlier names is left alone: only a directory the CLI wrote, whose SKILL.md says “maintained by OuterLayer”, is removed.
  2. In your template skills, replace the earlier names. outerlayer init --update does this for a template you have not edited. For one you edited, outerlayer doctor lists each file that still names a skill by an earlier name.
  3. On a build host, change /amend to /outerlayer-amend in runner.commands.amend. Until you do, the runner runs /outerlayer-amend in its place and says so in the build’s log and in runner check.
  4. When you start a skill by hand, type /outerlayer-amend instead of /amend.
A repository whose instructions come from a control plane shows each skill once, under its new name, even before the control plane is updated. Update the control plane with step 1, so its own copies match.

​
The build skill splits in two

The build process now lives in outerlayer-build, a maintained skill that follows the CLI. Your build skill holds only your repository’s changes, so later changes to the process reach you when you upgrade. What to do:
  1. If you never edited build, run outerlayer init --update and commit. It replaces build/SKILL.md with the short skill. It removes the files under build/ that the CLI no longer ships, such as references/ and scripts/. A file there that you edited is kept. The short skill reads outerlayer-build from ~/.agents/skills/.
  2. If you edited build, init --update keeps it as it is, with the references/ and scripts/ beside it. outerlayer doctor says it gets no updates from the core, and shows the short build. To move onto it:
    1. Replace the contents of build/SKILL.md with the short skill. It starts with Read ~/.agents/skills/outerlayer-build/SKILL.md and follow it from start to finish.
    2. Under ## Changes for this repository, add each of your edits under a ### heading with the name of the phase it applies to: Intake, Criteria, Implement, Review, Pull request or Evidence. Express an edit as an added step, a setting, or a step turned off.
    3. Run outerlayer context emit and commit.
  3. If your criteria check names a brief under build/references/, change brief: in .outerlayer/validators/acceptance-criteria.yaml to .agents/skills/outerlayer-build/references/criteria-judge.md. A repository that has not moved to the AGENTS.md layout keeps the skills in .outerlayer/skills/, so use that folder there. init --update does this for a check you have not edited. After init --update, the repository no longer holds that file. A runner host reads the brief from its own CLI, so the check still runs.
Run outerlayer doctor after. It names a heading that matches no phase, and an agent’s skills folder that holds build without outerlayer-build.

​
The maintained skills move to each machine

The CLI now keeps the five maintained skills once per machine, in ~/.agents/skills/. Each skill has a link in ~/.claude/skills/. A repository in the AGENTS.md layout carries none of them. outerlayer init installs them, and each later outerlayer command keeps them at its own version. A CLI from before this release does not read ~/.agents/skills/. Do these steps in this order:
  1. Upgrade the CLI on every machine and runner host. This covers every laptop and every host that runs builds.
  2. Run outerlayer init --local on each machine a person works on. It installs the skills and makes no network call. A build host installs them when a build starts its agent, so it needs no more.
  3. Run outerlayer init --update in each repository that carries copies of the maintained skills. It removes each maintained skill folder that carries the “maintained by OuterLayer” line. It keeps a folder without the line. It changes each path to a removed folder to ~/.agents/skills/, in AGENTS.md, CLAUDE.md and the repository’s skills. In an edited build, ../outerlayer-build/SKILL.md becomes ~/.agents/skills/outerlayer-build/SKILL.md, and the rest of the file stays as it was. Review the diff and commit it.
Start step 3 only when every machine that works in the repository has finished steps 1 and 2. For runner hosts, outerlayer init --update checks for you. With a login, it lists the factory’s runner hosts from the gateway. It names each host on a CLI older than 0.27.0, and it says not to commit until each one updates. It cannot check the machines people work on. A machine that has not finished them has no maintained skills after it pulls your commit. When a session starts on such a machine, the agent tells the person to run outerlayer init --local. Run outerlayer doctor after. It names the maintained skill folders a repository still commits. It also names missing per-machine copies, in a repository whose build reads ~/.agents/skills/outerlayer-build/SKILL.md. A repository that has not moved to the AGENTS.md layout keeps its compiled copies. outerlayer init --update moves it first, then removes the copies. A cloud session on a machine with no CLI gets no maintained skills once a repository stops carrying them.