بِسْمِ ٱللَّهِ ٱلرَّحْمَـٰنِ ٱلرَّحِيمِ
How a sync works
What sync reads, how it decides what to write, why a project copy ends up equal to the vault copy, and what is copied.
sync makes the copy of a skill in each project equal to the copy in the vault. It never installs a skill a project does not have, and it shows every change before it writes one.
The flow
- Read the vault. Every folder with a
SKILL.mdis a skill, and the folders above it are its group. - Ask git for the tracked files of each skill.
- Walk the root, skipping noise folders and your exclusions, and never following links.
- For every
.agents/skills/<name>/found: if<name>is in the vault, plan it. If it is not, leave it alone. - Show the plan.
--dry-runstops here. Otherwise ask, then write target by target.
A mirror, not an overlay
A project copy ends up equal to the vault copy. A file the vault added is created, a file it changed is replaced, and a file an older version had and the vault no longer has is removed. No stale file of an older version survives.
skillmirror status --project ~/projects/infra● ~/projects/infra
~ coding outdated (1 file added, 1 file removed)skillmirror diff coding --project ~/projects/infra● ~/projects/infra coding
--- a/notes.md
+++ /dev/null
@@ -1 +0,0 @@
-old note
--- /dev/null
+++ b/references/naming.md
@@ -0,0 +1,2 @@
+# Naming
+- verbs for functionsThe plan names the files that would be removed, and diff shows every line. A mode change (an executable bit) counts as a difference too.
A sync replaces edits made in a project
If you changed a skill inside a project, the project copy differs from the vault, and a sync replaces it. skillmirror changes shows which skills of a project were edited there, and skillmirror promote puts them into the vault first. See Improve a skill where you use it. If it already happened, skillmirror undo brings the edit back.
What is copied
The files git tracks in the skill folder are copied, with their permission bits.
- Staged and committed files are copied. Commit when a skill is ready, so the vault keeps its history, but a staged file already travels.
- An uncommitted edit of a tracked file is copied too, because the working tree version of a tracked file is what is read.
doctornotes it so it does not surprise you. - Untracked files are never copied. A half finished draft next to a skill does not leak into your projects.
infolists them apart. - A tracked symlink or submodule, a tracked file missing from the disk, or a skill whose
SKILL.mdis not tracked makes that skill fail with a hint instead of copying something wrong.
skillmirror info codingcoding mandatory
group top level of the vault
description Coding conventions
profiles websites
files 2 copied
SKILL.md
references/naming.md
not copied 1 file (git does not track it)
draft.md
Installed in 4 of 4 projects
~ ~/projects/atlas-api outdated (1 file added)
~ ~/projects/docs-site outdated (1 file added)
✓ ~/projects/infra up to date
~ ~/projects/lumen-app outdated (1 file added)Narrowing a sync
sync, push and status take the same scope words. They combine.
| Scope | Meaning |
|---|---|
SKILL... | only these skills |
--group PATH | only the skills below this vault folder, such as web or web/seo |
--profile NAME | only the skills of this profile |
--project DIR | only this project |
An unknown skill, group or profile is an error with a hint, never a quiet "nothing to do". A scope still never adds a skill a project does not have.
When a target fails
One failed target never stops the others and never leaves a half written folder. The command finishes the rest, names each failure with a hint, and exits with 4. Two causes are worth knowing:
- The project folder changed between the plan and the write. That skill fails instead of being overwritten.
- The old copy cannot be stored in the backup. That skill fails and the old copy stays where it is.
Where each command writes
| Command | Writes | Never |
|---|---|---|
sync | the skill folders a project already has | adds a skill |
add, init, push | new skill folders, and updates of the ones present | touches a skill you did not name or that is not mandatory |
delete | removes one skill folder from projects | touches the vault |
new, adopt, promote | the vault, then git add | commits |
agents sync, agents add | only the autogenerated block of AGENTS.md | changes the rest of the file |
bridge | a .claude/skills link where nothing is | replaces a real folder |
Next: Safety and undo.