Improve a skill where you use it

You often notice a missing rule while you work in a project, with the agent beside you. Fix the skill right there, then make it the master copy. skillmirror has two commands for that: changes reads, promote writes.

See what you changedCopy Anchor Link

Run changes inside the project. It compares every skill folder of that project with the vault and writes nothing.

cd ~/projects/infra
skillmirror changes

● ~/projects/infra (this folder)
  ~ coding                         edited here (SKILL.md modified) vault: coding
  + runbooks                       not in the vault (`skillmirror adopt runbooks --from ~/projects/infra` adds it)

1 edited, 0 behind, 1 new, 2 same
`skillmirror promote --all` puts the edited ones into the vault; add --sync to update the other projects too.

Each skill is in one of five states. --all lists the same ones too.

cd ~/projects/docs-site
skillmirror changes

● ~/projects/docs-site (this folder)
  ↓ coding                         an older version of the vault's, 1 change since (`skillmirror sync` updates it)
  + custom                         not in the vault (`skillmirror adopt custom --from ~/projects/docs-site` adds it)

0 edited, 1 behind, 1 new, 2 same

The exit code is 1 when some skill is edited, so a script can ask the question too (Scripts and CI).

Which projectCopy Anchor Link

Without --project DIR, changes and promote start in the current folder and go up, and stop after the top of the git repository they are in. A project further up is another project. When nothing is found that way they look below the folder with the scan rules of the vault. One project there is taken. Several are a usage error that lists them:

cd ~ && skillmirror changes

error: 4 projects are below ~: ~/projects/atlas-api, ~/projects/docs-site, ~/projects/infra, ~/projects/lumen-app
hint: pass --project DIR to pick one, or start in it

The output says which of these happened: (this folder) above means it was found where you stood.

Put it into the vaultCopy Anchor Link

promote replaces the vault's copy of a skill with the project's. It shows what differs and asks first.

skillmirror promote coding --dry-run

Would replace in the vault, with the copies from ~/projects/infra:
  coding (2 files) SKILL.md modified

skillmirror promote coding --yes

Replaced coding in the vault: ~/skills/coding (2 files)
Staged in git, not committed. Commit it in the vault when it is ready; sync and add copy what git tracks.
Backup: run 20261103-224317-581-26053-0 (undo with: skillmirror undo)

The old vault folder goes to the backup, so skillmirror undo puts it back and stages it again. The new one is staged with git add and never committed. Read it with git -C ~/skills diff --cached, then commit when you are happy.

promote refuses in three cases, each with a hint:

• The skill is not edited. error: "coding" is not promoted: it equals the vault's copy.
• The vault copy has changes that are not staged. A promote would replace them: commit or discard them first.
• The project folder holds a link or a special file, or has no SKILL.md.

promote --all takes every edited skill of the project at once.

Spread itCopy Anchor Link

The other projects are still outdated. sync brings them up, and --sync on the promote does both steps:

skillmirror promote coding --sync --yes

Replaced coding in the vault: ~/skills/coding (2 files)
Staged in git, not committed. Commit it in the vault when it is ready; sync and add copy what git tracks.
Backup: run 20261103-224317-581-26053-0 (undo with: skillmirror undo)

● ~/projects/atlas-api
  ~ coding                         updated (1 changed)

● ~/projects/docs-site
  ~ coding                         updated (2 changed)

● ~/projects/lumen-app
  ~ coding                         updated (1 changed)

4 skills in 4 projects: 3 updated, 1 unchanged
Backup: run 20261103-224317-587-26053-1 (undo with: skillmirror undo)

The sync asks its usual question unless you pass --yes. Two backup runs were made, one for the promote and one for the sync, and undo takes them back one at a time. Afterwards status shows no outdated skill.

A skill the vault does not have yetCopy Anchor Link

A folder marked new was made by hand in a project. adopt copies it into the vault:

skillmirror adopt runbooks --from ~/projects/infra

adopt stages the copy and never commits. The project's folder is then equal to the vault copy. Use --group PATH to put it in a group.

The interface does the sameCopy Anchor Link

skillmirror with no arguments opens an interface whose Override entry shows these states for the project around the folder you started in. Tick the edited skills, press s to update the other projects too, and confirm (The interface).