Files and folders

skillmirror touches three places: the vault, the projects, and a small folder of its own on your machine. This page lists what is in each, which command may write there, and what it never does.

The vaultCopy Anchor Link

The vault is a git repository. Its layout is yours, apart from three names that mean something:

~/skills/                       the vault: a git repository
  config.yaml                   the vault's configuration (optional)
  project-files/
    AGENTS.md                   the text of the AGENTS.md block (optional)
  coding/                       a skill: a folder with a SKILL.md
    SKILL.md
    references/naming.md
  Web_Skills/                   a group: holds skills, has no SKILL.md
    astro/SKILL.md
    seo/schema/SKILL.md         groups nest without a limit

• A folder with a SKILL.md is a skill, and the search for skills stops there. Any other folder that holds skills is a group. Folders with no skill below them are ignored, and doctor lists them.
• Skill names are unique across the whole vault, and a group may not be named like a skill.
• config.yaml holds the configuration (Configuration).
• project-files/ holds files that go into every project. It has no SKILL.md, so sync and push never take it for a skill. A file called AGENTS.md at the root of the vault is the vault's own and is never read (AGENTS.md for every project).

What travels with a skillCopy Anchor Link

The files that git tracks in a skill folder are what is copied, with their permission bits. That includes a file you changed and staged or did not stage, as long as git knows it: a half finished edit of a tracked file travels, a file git has never seen does not.

skillmirror info coding

coding  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)

doctor points at the same files with a hint to git add them. A tracked symlink or submodule inside a skill, or a skill whose SKILL.md is not tracked, makes that skill fail with a hint instead of copying something wrong:

  ✗ astro                          skill "astro" has no git-tracked files in the vault
      hint: run `git add` for astro in the vault and commit

A projectCopy Anchor Link

A project is a folder with a .agents/skills folder. These are the paths skillmirror reads and writes in it:

my-project/
  .agents/skills/<name>/        one folder per skill, a mirror of the vault's
  .claude/skills                a link to ../.agents/skills, when `targets:` asks for it
  AGENTS.md                     the block and your notes

• The installed layout is flat: .agents/skills/<name>/, whatever group the skill has in the vault. Moving a skill between groups changes no project.
• A skill folder is a mirror. A sync adds the files the vault has, changes the ones that differ, and removes the ones the vault does not have, so notes you keep in a skill folder do not survive a sync. Put them next to the folder, or in the vault.
• Skillmirror never follows a link and never writes through one. A linked project folder, a linked .agents or a linked .agents/skills is invisible.
• A folder in .agents/skills that the vault has no skill for is left alone, and status marks it ?.

On your machineCopy Anchor Link

~/.config/skillmirror/vault                       the pointer to your vault: one line
~/.local/state/skillmirror/backups/               the backup store that `undo` reads
  <run>/<n>/entry.json                            which project and skill, and what the run did
  <run>/<n>/tree/                                 the old copy of the folder

The folders follow XDG_CONFIG_HOME and XDG_STATE_HOME. The newest 30 runs are kept (Safety and undo).

The only other file skillmirror writes is the one you name: skillmirror report -o FILE writes a report, and replaces an existing file only when it is a report that skillmirror wrote.

Who writes whereCopy Anchor Link

status, diff, changes, list, skills, info, doctor, history and web without --allow-write write nothing at all. None of the commands that write into the vault commits: that is yours to do, after you read what was staged with git diff --cached.

What an interrupted run leavesCopy Anchor Link

A skill folder is replaced by building the new copy beside the old one and swapping the two in one step, so a crash never leaves a half written skill. A run that was killed at the wrong moment can still leave its temporary folder behind: a .stage- or .trash- folder in .agents/ of a project (or in the vault's group folder for promote), or a .AGENTS.md.stage- file next to an AGENTS.md.

Every scan reports them, doctor lists them under leftovers, and status prints a warning. skillmirror never deletes one for you, because it cannot know that no other run still needs it:

skillmirror doctor | grep -v '^✓'

! leftovers ~/projects/infra/.agents/.stage-4294967000-abc-0: left over from an interrupted run; delete it by hand
! bridges ~/projects/atlas-api/.claude/skills: the claude bridge is missing
    hint: `skillmirror bridge` makes it

0 errors, 2 warnings

Delete the folder by hand once you have looked at it, and the warning is gone.