بِسْمِ ٱللَّهِ ٱلرَّحْمَـٰنِ ٱلرَّحِيمِ
First run
Make a vault, put one skill in it, change the skill once, watch three projects follow, and undo the sync.
This page takes you from nothing to a first sync. It should inshallah take about five minutes, and nothing on it is risky: no command writes before you say yes, and the last step undoes the sync.
The examples use three projects that each carry their own copy of a skill called coding. ~/projects holds the projects and ~/skills is the new vault. Both folders are the example's choice. Use any two folders you like.
Make the vault
skillmirror vault init ~/skills --root ~/projectsCreated the vault ~/skills
a git repository with a config.yaml (staged, not committed)
scan root ~/projects
default this is now your default vault
Next: `skillmirror new NAME` makes a skill, `skillmirror adopt NAME --from PROJECT` takes one a project already has.The vault is a git repository. --root is the folder skillmirror scans for projects: every folder below it that has .agents/skills is a project. Because you had no default vault yet, this one is now the default (a one-line pointer file, ~/.config/skillmirror/vault).
Put a skill in it
adopt copies a skill folder that a project already has into the vault:
skillmirror adopt coding --from ~/projects/atlas-apiCreated coding in the vault (copied from the project): ~/skills/coding
SKILL.md
Staged in git, not committed. Commit it in the vault when it is ready; sync and add copy what git tracks.skillmirror stages what it writes into the vault and never commits. Staged is enough for sync, which copies what git tracks. Commit when the skill is ready, so the vault keeps its history:
git -C ~/skills commit -m "adopt coding"
skillmirror status3 projects: 3 in syncAll three projects were already equal to the new vault copy, so nothing differs yet. To start a skill from nothing, use skillmirror new NAME instead. It makes a SKILL.md from a template.
Improve the skill in the vault
Edit ~/skills/coding/SKILL.md: change the line Keep files under 300 lines of code. to 250, then commit.
git -C ~/skills commit -am "coding: 250 lines"
skillmirror status● ~/projects/atlas-api
~ coding outdated (1 file changed)
● ~/projects/docs-site
~ coding outdated (1 file changed)
● ~/projects/infra
~ coding outdated (1 file changed)
3 projects: 0 in sync, 3 differ (3 skill folders outdated, 0 mandatory missing)status writes nothing and exits with 1 when something differs. skillmirror diff shows the lines:
● ~/projects/atlas-api coding
--- a/SKILL.md
+++ b/SKILL.md
@@ -5,7 +5,7 @@
# coding
- One file, one purpose.
-- Keep files under 300 lines of code.
+- 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.The same diff follows for the other two projects. - is what the project would lose and + is what the vault brings.
Sync
skillmirror syncsync shows its plan and asks:
● ~/projects/atlas-api
~ coding update (1 changed)
● ~/projects/docs-site
~ coding update (1 changed)
● ~/projects/infra
~ coding update (1 changed)
Write 3 skill folder(s) in 3 project(s)? [y/N] y
● ~/projects/atlas-api
~ coding updated (1 changed)
● ~/projects/docs-site
~ coding updated (1 changed)
● ~/projects/infra
~ coding updated (1 changed)
3 skills in 3 projects: 3 updated
Backup: run 20261103-212804-051-131217-0 (undo with: skillmirror undo)--dry-run stops after the plan and --yes skips the question. Run skillmirror status again and it reports 3 projects: 3 in sync.
Undo it
Before the sync replaced a folder, it kept the old copy in a backup run. history lists the runs:
skillmirror history2026-11-03 21:28:04 UTC sync 3 folders in 3 projects 20261103-212804-051-131217-0
Newest first. `skillmirror undo <RUN>` brings a run back; the newest is the default.undo shows what it would restore, asks, and brings the newest run back:
skillmirror undo ↺ coding would restore in ~/projects/atlas-api
↺ coding would restore in ~/projects/docs-site
↺ coding would restore in ~/projects/infra
3 folders to restore (dry run)
Undo the sync of 2026-11-03 21:28:04 UTC: 3 folder(s) in 3 project(s)? [y/N] y
↺ coding restored in ~/projects/atlas-api
↺ coding restored in ~/projects/docs-site
↺ coding restored in ~/projects/infra
3 folders restored
Saved what was replaced as run 20261103-212804-367-131317-0 (undo again to redo this undo).The projects are outdated again. An undo is a run too, so a second skillmirror undo redoes the sync and leaves the three projects in sync.
What you have now
- A vault that holds the master copy of
coding, in git. - Three projects that follow it, with one command to check them (
status), one to see what would change (diff) and one to bring them up (sync). - A way back for every run that replaced or removed a folder.
Next
- Vault and projects: what the vault, a skill, a group and a project are.
- Keep projects in step: the daily loop, and how to sync only some skills or projects.
- Start a project: put skills into a new or an existing project.