Look before you sync

Most of what skillmirror does is look. These commands write nothing, to a project or to the vault, so you can run them as often as you like.

Keep projects in step shows status and diff in the daily loop. This page covers the rest.

Ask for the planCopy Anchor Link

sync --dry-run and sync --check print the plan a sync would carry out. They differ in the exit code, which is what a script wants to know:

skillmirror sync --dry-run

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

● ~/projects/infra
  ~ coding                         update (1 changed)

13 skills in 4 projects: 2 to update, 11 up to date (dry run)

skillmirror sync --check; echo exit=$?

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

● ~/projects/infra
  ~ coding                         update (1 changed)

13 skills in 4 projects: 2 to update, 11 up to date
exit=1

--check exits 0 when every project equals the vault and 1 when something differs. --json prints the same plan as one JSON document (Scripts and CI).

Read one skillCopy Anchor Link

info shows a skill from the vault's side and from every project's side: the group, the description, the files that are copied, the files git does not track and so are not, the profiles that name it, and what it is in each project.

skillmirror info coding

coding  mandatory
  group        top level of the vault
  description  Coding conventions
  profiles     websites
  files        2 copied
    SKILL.md
    references/naming.md

Installed in 4 of 5 projects
  ✓ ~/projects/atlas-api up to date
  ~ ~/projects/docs-site outdated (1 file added, 1 file changed)
  ~ ~/projects/infra outdated (1 file changed)
  ✓ ~/projects/lumen-app up to date
  + ~/projects/orbit mandatory, not installed

A folder that only a project has is described from the project's side, with the reminder that sync leaves it alone:

skillmirror info custom

custom
  not in the vault (sync leaves the installed folders alone)

Installed in 1 of 5 projects
  ? ~/projects/docs-site not in the vault

list names every installed skill folder with its project, and marks the ones the vault does not have. skills shows the vault as a tree of groups:

skillmirror skills

coding  (mandatory)
doc-start  (mandatory)
file-tree-optimization  (mandatory)
Web_Skills/
  astro
  seo/
    schema

5 skills in 2 groups

--group PATH limits it to one group, and --json is there for a script.

Check the setupCopy Anchor Link

doctor checks the machine, the configuration, the vault and every SKILL.md header. It writes nothing, and it never hides a problem it finds. One line per check:

skillmirror doctor

✓ git
✓ pointer
✓ legacy
✓ backups
✓ config
✓ vault
✓ agents-text
✓ vault-git
✓ skill-files
✓ skill-edits
✓ mandatory
✓ profiles
✓ scan
✓ leftovers
! bridges ~/projects/docs-site/.claude/skills: the claude bridge is missing
    hint: `skillmirror bridge` makes it
! bridges ~/projects/infra/.claude/skills: the claude bridge is missing
    hint: `skillmirror bridge` makes it
! bridges ~/projects/lumen-app/.claude/skills: the claude bridge is missing
    hint: `skillmirror bridge` makes it
! bridges ~/projects/orbit/.claude/skills: the claude bridge is missing
    hint: `skillmirror bridge` makes it
✓ filesystem

0 errors, 4 warnings

The exit code is 0 for a clean run or notes only, 1 for warnings and 3 for errors. Troubleshooting walks through the findings you are most likely to meet.

The reportCopy Anchor Link

report writes the state of everything into one HTML file: the skills against the projects, the vault tree, the diffs, a filter, and a dark theme that follows your system.

skillmirror report -o ~/report.html

Wrote the report to ~/report.html (5 skills, 4 projects).

The file is self-contained. It loads nothing from the network, and it carries a content security policy that allows no connection at all, so you can send it to a colleague or keep it as a record of a day. --open opens it in your browser afterwards, and -o - prints it instead of writing a file. An existing file is replaced only when it is a report that skillmirror wrote.

The web viewCopy Anchor Link

The same views, live, on your own computer. The web view is off unless you switch it on, and two switches keep it off:

• The build. A plain just install leaves the server out. Build it in with just install-web, or with cargo install --path Crates/Cli --locked --features web.
• The config. web: false in config.yaml, which is what you get without the key, makes skillmirror web refuse to start. skillmirror config web on sets web: true, and skillmirror config web off sets it back.

When one of them is missing, skillmirror web stops with a usage error and nothing is listening. With the switch off in the config:

skillmirror web

error: the web view is switched off in the config
hint: turn it on with `skillmirror config web on` (sets `web: true` in ~/skills/config.yaml)

With the switch on and a build that lacks the server, config web on still sets the key, and it warns you:

skillmirror config web on

Set web: true in ~/skills/config.yaml
warning: this build of skillmirror has no web view yet: build it in with `just install-web`

A build with the server prints a link and waits:

skillmirror web

skillmirror web is running (read-only)
Open: http://127.0.0.1:39219/?token=22335af2265202d0c741048698c7824e48294fb58cbb5fc9dd81b21f529c3af7
The link works once and only on this computer. Ctrl-C stops the server.

The server listens on 127.0.0.1 only, on a free port or the one you give with --port. It stops with Ctrl-C, or when nobody has asked for anything for two hours (--idle-timeout MINUTES, and 0 never stops it). --open opens the link in your browser for you.

What it showsCopy Anchor Link

The sidebar has eight pages:

Settings only shows. You change a setting with skillmirror config and skillmirror mandatory, or by editing config.yaml. The web view does not show AGENTS.md yet.

Looking and changingCopy Anchor Link

Without --allow-write the web view only looks, and no page can change a file. A chip in the sidebar says Read-only or Changes allowed:

skillmirror web --allow-write

skillmirror web is running (changes allowed)
Open: http://127.0.0.1:33745/?token=f24b589b7d80141b3d3955d9ce79d08e1740a86595c4d679323e337baeab157c
The link works once and only on this computer. Ctrl-C stops the server.

With it, Sync, Push and History can write, and a change is a plan first. You press Plan, read what would change in each file, and press Apply this plan, which runs exactly that plan. A folder edited in between is left alone, a replaced folder is saved first and History brings it back, and one change runs at a time.

Why it is safe to leave openCopy Anchor Link

The server is built for a computer on which other web pages run in the same browser. The link works once and is traded for a cookie that scripts cannot read. A request that does not come from the page itself is refused. Nothing the pages show can turn into markup, so a skill or a project with an odd name cannot run anything in the page. The link in the examples above belongs to a server that was stopped as soon as it was recorded.