بِسْمِ ٱللَّهِ ٱلرَّحْمَـٰنِ ٱلرَّحِيمِ
Keep projects in step
The daily loop: change a skill in the vault, see which projects differ, read the exact lines, and sync some of them or all.
The daily loop has four steps. Change the skill in the vault and commit, look at status, read diff, then sync.
git -C ~/skills commit -am "coding: early returns"
skillmirror status
skillmirror diff
skillmirror syncRead status
status writes nothing. It lists the projects that are not fully in step, with one line per skill that needs a look, and ends with a summary. --all lists the healthy projects and skills too.
skillmirror status● ~/projects/docs-site
~ coding outdated (1 file added, 1 file changed)
+ file-tree-optimization mandatory, not installed
+ claude bridge to .agents/skills not made (`skillmirror bridge`)
? custom not in the vault, sync leaves it alone
● ~/projects/infra
~ coding outdated (1 file changed)
+ claude bridge to .agents/skills not made (`skillmirror bridge`)
? runbooks not in the vault, sync leaves it alone
● ~/projects/lumen-app
+ claude bridge to .agents/skills not made (`skillmirror bridge`)
● ~/projects/orbit
+ coding mandatory, not installed
+ doc-start mandatory, not installed
+ file-tree-optimization mandatory, not installed
+ claude bridge to .agents/skills not made (`skillmirror bridge`)
5 projects: 1 in sync, 4 differ (2 skill folders outdated, 4 mandatory missing, 4 bridges missing)
AGENTS.md blocks: 1 out of date, 1 edited by hand. `skillmirror agents status` has the list, `skillmirror agents sync` brings them up to date.atlas-api is in step, so it is not listed.
| Mark | Meaning | What brings it in step |
|---|---|---|
✓ | the folder equals the vault copy | nothing to do |
~ | outdated: the folder differs, and the counts say how (files added, changed, removed) | sync |
+ with mandatory | a mandatory skill the project does not have | push, or add NAME |
+ with bridge | the .claude/skills link that targets: asks for is not made | bridge |
? | the project has a folder the vault has no skill for | adopt it, or leave it: sync does not touch it |
status cannot say who changed a file, only that it differs. If a project copy is outdated because someone edited it there, sync replaces the edit. Run changes first when you are not sure.
The exit code is 0 when nothing differs, 1 when something does, and 4 when a comparison failed. The last line about AGENTS.md appears only when blocks are behind (AGENTS.md for every project).
Read the lines
diff shows what a sync would bring in and take away, as unified diffs. The old side is the project, the new side is the vault, so - is what the project would lose.
skillmirror diff● ~/projects/docs-site coding
--- a/SKILL.md
+++ b/SKILL.md
@@ -8,4 +8,4 @@
- Keep files under 250 lines of code.
- No fallbacks: fail with a clear error.
- Comment the why, never the what.
-- Name things for the reader.
+- Name things for the reader. `references/naming.md` has the rules.
--- /dev/null
+++ b/references/naming.md
@@ -0,0 +1,4 @@
+# Naming
+
+- Verbs for functions, nouns for values.
+- No abbreviation a new reader has to look up.--stat shows the line counts per file instead of the lines:
● ~/projects/docs-site coding
SKILL.md | modified +1 -1
references/naming.md | added +4 -0
2 files changed, +5 -1
● ~/projects/infra coding
SKILL.md | modified +0 -1
1 file changed, +0 -1
2 skill folders differ, 3 files would changeA binary file, an unreadable file and a file above 1 MiB are listed without lines.
Sync
skillmirror syncsync shows the plan, asks [y/N] and writes. --dry-run shows the plan and stops. --yes skips the question. First run has a whole session with the question answered.
Name what you want to limit it to. The words combine:
skillmirror sync coding # only the skill coding, in every project
skillmirror sync --project ~/projects/infra # only this project
skillmirror sync --group Web_Skills/seo # only the skills below this vault folder
skillmirror sync --profile websites # only the skills of this profileskillmirror sync coding --project ~/projects/infra --yes● ~/projects/infra
~ coding updated (1 changed)
1 skill in 1 project: 1 updated
Backup: run 20261103-212315-684-124800-0 (undo with: skillmirror undo)An unknown skill, group or profile stops with an error and a hint. --project must name a project that the scan found, otherwise it is an error too, never a quiet "nothing to do".
Which vault, which root
Every command takes --vault DIR and --root DIR. They beat the variables SKILLMIRROR_VAULT and SKILLMIRROR_ROOT, which beat the pointer file and the root: key of config.yaml. skillmirror config show prints what is in force and where each value came from.
skillmirror config showvault ~/skills (pointer file)
root ~/projects (vault config)
config file ~/skills/config.yaml
mandatory doc-start, coding, file-tree-optimization
targets claude
web off
exclude_dirs testdata
exclude_paths none
profiles websitesWhen it goes wrong
- A sync stopped with exit 4: some targets failed and the rest were written. The output names each failure with a hint, see Troubleshooting.
- A sync did something you did not want:
skillmirror undo(Safety and undo). - You want to know why a project is not listed:
skillmirror listshows every folder the scan found, andskillmirror doctornames unreadable folders and exclusions that match nothing.