بِسْمِ ٱللَّهِ ٱلرَّحْمَـٰنِ ٱلرَّحِيمِ
Commands
Every skillmirror command with its options, what it reads, what it writes, and when it exits with something other than 0.
Every command accepts --vault DIR and --root DIR, which beat the variables SKILLMIRROR_VAULT and SKILLMIRROR_ROOT and the files (Configuration). Every command accepts -h and --help. These three are left out of the tables below, and so are the exit codes that every command shares (Exit codes).
Commands that write ask first, unless you pass --yes, and show their plan with --dry-run. Commands that print results take --json for scripts (Scripts and CI).
skillmirror with no command opens the interface when stdin and stdout are terminals. Otherwise it prints the help and exits 2. skillmirror --version prints the version.
Look
These commands write nothing.
status
How every project stands against the vault: outdated skills, mandatory skills that are missing, bridges that are not made, folders the vault does not have. Exits 1 when something differs.
skillmirror status [SKILL]...| Option | What it does |
|---|---|
SKILL | only these skills (default: all of them) |
--group PATH | only the skills below this vault folder, such as web or web/seo |
--profile NAME | only the skills of a profile |
--project DIR | only this project (default: every project under the root) |
--all | also list the projects that are fully up to date, with their skills |
--json | one JSON document |
diff
The lines a sync would bring in and take away, as unified diffs. The old side is the project, the new side is the vault. Exits 1 when something differs.
skillmirror diff [SKILL]| Option | What it does |
|---|---|
SKILL | only this skill |
--project DIR | only this project |
--stat | only the lines added and removed per file, not the lines themselves |
--json | one JSON document |
changes
Which skills of one project differ from the vault: edited there, behind, new, unusable or same. Exits 1 when some skill is edited. The project is the one around the current folder, up to the top of its git repository, else the only one below it (Improve a skill).
skillmirror changes| Option | What it does |
|---|---|
--project DIR | the project, a folder with .agents/skills; without it, the one around the current folder |
--all | also list the skills that equal the vault's |
--json | one JSON document |
list
Every installed skill folder with its project. The ones the vault lacks are marked (not in vault).
skillmirror list| Option | What it does |
|---|---|
--json | one JSON document |
skills
The skills of the vault, grouped by folder. The mandatory ones are marked.
skillmirror skills| Option | What it does |
|---|---|
--group PATH | only the skills below this vault folder |
--json | one JSON document |
info
One skill from every side: its place and files in the vault, the files git does not track, the profiles that name it, and what it is in each project.
skillmirror info SKILL| Option | What it does |
|---|---|
SKILL | the skill folder name |
--json | one JSON document |
doctor
Checks the vault, the configuration and the machine. Exits 1 for warnings and 3 for errors (Look before you sync).
skillmirror doctor| Option | What it does |
|---|---|
--json | one JSON document |
history
The backup runs that can be undone, newest first.
skillmirror history| Option | What it does |
|---|---|
--json | one JSON document |
report
One self-contained HTML file: skills against projects, the vault tree, diffs, a filter, a dark theme.
skillmirror report| Option | What it does |
|---|---|
-o, --output FILE | where to write the report (default skillmirror-report.html); - prints it. An existing file is replaced only when it is a report this tool wrote |
--open | open the report in the browser afterwards (xdg-open) |
web
The report, live, on this computer only. It starts only in a build with the web view and with web: true in the config (The web view).
skillmirror web| Option | What it does |
|---|---|
--allow-write | let the pages run sync, push and undo; each shows its plan first and asks |
--port PORT | the port on 127.0.0.1 (default: any free one) |
--open | open the link in the browser (xdg-open) |
--idle-timeout MINUTES | stop after this many minutes without a request; 0 never stops (default 120) |
Bring projects in step
sync
Updates the skills each project already has from the vault. It never adds a skill. The copy is a mirror: files are added, changed and removed, and a mode change counts as a change.
skillmirror sync [SKILL]...| Option | What it does |
|---|---|
SKILL | only these skills (default: all of them) |
--group PATH | only the skills below this vault folder |
--profile NAME | only the skills of a profile |
--project DIR | only this project |
--dry-run | show what would change and write nothing |
--check | write nothing; exit 1 when any target differs from the vault |
-y, --yes | apply without asking |
--json | one JSON document; needs --yes, --dry-run or --check |
--all | also list the targets that are already up to date |
push
Installs the mandatory skills into every project that has a skills folder.
skillmirror push [SKILL]...A name that is not on the mandatory list is refused.
| Option | What it does |
|---|---|
SKILL | only these skills (default: all of them) |
--group PATH | only the skills below this vault folder |
--profile NAME | only the skills of a profile |
--project DIR | only this project |
--dry-run | show what would change and write nothing |
--check | write nothing; exit 1 when any target differs from the vault |
-y, --yes | apply without asking |
--json | one JSON document; needs --yes, --dry-run or --check |
--all | also list the targets that are already up to date |
add
Installs skills, groups or profiles into one existing project, and makes its .agents/skills folder if there is none.
skillmirror add [SKILL]...| Option | What it does |
|---|---|
SKILL | skill names |
--group PATH | a vault folder such as web or web/seo; installs every skill below it |
--profile NAME | a profile |
--project DIR | the project to install into (default: the current directory) |
--dry-run | show what would be installed and write nothing |
-y, --yes | install without asking |
--json | one JSON document |
init
Makes a new project folder with the mandatory skills plus a selection, a git repository on main, an AGENTS.md and the scaffold of the doc-start skill (Start a project).
skillmirror init DIR [SKILL]...| Option | What it does |
|---|---|
DIR | the new project directory; it must not exist or must be empty |
SKILL | skill names |
--group PATH | a vault folder; installs every skill below it |
--profile NAME | a profile |
--no-git | do not make a git repository (one is made on the branch main, unless the folder is inside one already) |
--no-scaffold | do not run the doc-start skill's script |
--no-mandatory | do not install the mandatory skills |
--no-agents-md | do not make an AGENTS.md |
--dry-run | show what would be installed and write nothing |
-y, --yes | install without asking |
--json | one JSON document |
delete
Removes one skill folder from projects. The removed folders go to the backup.
skillmirror delete NAME| Option | What it does |
|---|---|
NAME | the skill folder name |
--project DIR | remove it from this one project instead of scanning the root |
--dry-run | show what would be removed and remove nothing |
-y, --yes | remove without asking |
--json | one JSON document |
bridge
Links the agent folders named in targets: of the vault config to .agents/skills in every project (Other agent folders).
skillmirror bridge| Option | What it does |
|---|---|
--dry-run | show what would be linked and write nothing; exits 1 when a link is missing |
-y, --yes | link without asking |
--all | also list the bridges that are already in place |
--json | one JSON document |
undo
Brings back what a run replaced or removed. Undoing is a run too, so a second undo redoes it (Safety and undo).
skillmirror undo [RUN]| Option | What it does |
|---|---|
RUN | the run to undo (default: the newest one); history lists them |
--project DIR | only undo what the run did in this project |
--skill NAME | only undo what the run did to this skill |
--dry-run | show what would be brought back and change nothing |
-y, --yes | undo without asking |
--json | one JSON document |
Grow the vault
new, adopt and promote write into the vault. They stage what they write with git add and never commit.
new
Creates a skill in the vault from a template: a SKILL.md with a header and a line of guidance.
skillmirror new NAME| Option | What it does |
|---|---|
NAME | lowercase letters, digits, - and _ |
--group PATH | the vault folder to put it in, such as web or web/seo (made when it does not exist) |
--description TEXT | the line agents read to decide when to use the skill |
--dry-run | show what would be created and create nothing |
--json | one JSON document |
adopt
Copies a skill folder that a project has into the vault. The project's folder is then equal to the vault's.
skillmirror adopt NAME --from DIR| Option | What it does |
|---|---|
NAME | the skill folder name in the project |
--from DIR | the project that has it |
--group PATH | the vault folder to put it in (made when it does not exist) |
--dry-run | show what would be copied and copy nothing |
--json | one JSON document |
promote
Replaces the vault's copy of skills you changed in a project with the project's. The old copy goes to the backup (Improve a skill).
skillmirror promote [SKILL]...| Option | What it does |
|---|---|
SKILL | the skill folders of the project to put into the vault |
--all | every skill the project changed |
--project DIR | the project; without it, the one around the current folder |
--sync | afterwards update every other project that has these skills (a sync; it asks again) |
--dry-run | show what would be replaced and replace nothing |
-y, --yes | replace without asking |
--json | one JSON document |
vault init
Makes a new vault: a git repository with a config.yaml. The folder must not exist or must be empty. When you have no default vault yet, it becomes the default.
skillmirror vault init DIR| Option | What it does |
|---|---|
DIR | the new vault folder |
--root DIR | the folder that holds your projects, written to config.yaml as root: |
--use | make it the default vault even when another one is set |
--dry-run | show what would be created and create nothing |
--json | one JSON document |
mandatory list
Lists the skills that push installs everywhere, from the mandatory: key of config.yaml.
| Option | What it does |
|---|---|
--json | one JSON document |
mandatory add
Adds skills of the vault to the list. Comments and the other keys of config.yaml stay. A name the vault does not have is an error.
skillmirror mandatory add SKILL...| Option | What it does |
|---|---|
SKILL | skill names |
--dry-run | show the new list and change nothing |
--json | one JSON document |
mandatory remove
Takes skills off the list. A name that is not on it is an error.
skillmirror mandatory remove SKILL...| Option | What it does |
|---|---|
SKILL | skill names |
--dry-run | show the new list and change nothing |
--json | one JSON document |
AGENTS.md
The commands of AGENTS.md for every project.
agents status
How the AGENTS.md of each project stands against the text. Exits 1 when any is not current.
| Option | What it does |
|---|---|
--project DIR | only this project (default: every project under the root) |
--all | also list the projects whose block is current |
--json | one JSON document |
agents sync
Rewrites the autogenerated block where it is out of date. The rest of each file is never touched.
| Option | What it does |
|---|---|
--project DIR | only this project |
--force | also replace a block that was edited by hand (the old file is kept for undo) |
--dry-run | show what would change and write nothing |
-y, --yes | write without asking |
--diff | show the lines that change in each file |
--all | also list the projects where nothing changes |
--json | one JSON document |
agents add
Makes AGENTS.md in a project that has none, or puts the block into one that has no block.
| Option | What it does |
|---|---|
--project DIR | the project (default: the current directory) |
--dry-run | show what would change and write nothing |
-y, --yes | write without asking |
--diff | show the lines that change in each file |
--all | also list the projects where nothing changes |
--json | one JSON document |
agents seed
Writes the built-in text into the vault as project-files/AGENTS.md so that you can edit it there. It stops when the file is there.
| Option | What it does |
|---|---|
--dry-run | show where the file would be made and write nothing |
--json | one JSON document |
Configuration
config show
The vault, the scan root and the settings in config.yaml, and where each came from.
| Option | What it does |
|---|---|
--json | one JSON document |
config path
Prints the path of config.yaml, for $EDITOR $(skillmirror config path).
config root
Sets root: in config.yaml to a folder that holds your projects.
skillmirror config root DIR| Option | What it does |
|---|---|
DIR | the folder to scan for projects; it must exist |
--dry-run | show the change and make none |
config web
Turns the web view on or off with web: in config.yaml.
skillmirror config web on
skillmirror config web off| Option | What it does |
|---|---|
--dry-run | show the change and make none |
Housekeeping
migrate
Copies the vault pointer of the old skill_Manag tool to this tool.
| Option | What it does |
|---|---|
--retire | remove the old pointer file afterwards, so the old tool stops finding the vault |
completions
Prints a shell completion script for bash, elvish, fish, powershell or zsh. Add one line to the startup file of your shell (Install).
skillmirror completions SHELLtui
Opens the interface by name. In a terminal it is what skillmirror alone does.
Scripts and CI
Run skillmirror without a person at the keyboard: how writes are confirmed, the JSON output, the exit codes to branch on, and recipes for cron and git hooks.
Configuration
The pointer file and the config.yaml of the vault, every key with its rules, which setting wins, and how to keep folders out of the scan.