Vault and projects

skillmirror knows two folders. The vault is one git folder where you write and keep your skills. The root is the folder that holds all your projects. A sync copies from the first into the second.

vault/
  coding/        a skill: a folder with a SKILL.md, your master copy
  doc-start/
  Web_Skills/    a group: a folder without SKILL.md that holds skills, only in the vault
    astro/
    seo/         groups nest as deep as you like
      schema/

projects/
  project-A/
    .agents/skills/
      coding/    exists, so it is updated from the vault
                 doc-start is not here, so it is not touched
  project-B/
    .agents/skills/
      astro/     exists, so it is updated from the vault

The vaultCopy Anchor Link

The vault is a git repository. Two facts follow from that. The files git tracks in a skill folder are what is copied, and the vault keeps the history of every skill for free. Make one with vault init or point skillmirror at one you have.

skillmirror finds the vault from --vault, then the variable SKILLMIRROR_VAULT, then the pointer file ~/.config/skillmirror/vault. The first of these that is set wins.

Next to your skills the vault holds two more things: config.yaml, which belongs to the vault and travels with it (Configuration), and the folder project-files/, whose AGENTS.md is the text that goes into every project (AGENTS.md for every project). project-files/ has no SKILL.md, so it is neither a skill nor a group.

A skillCopy Anchor Link

A skill is a folder with a SKILL.md. Agents read the header of that file to decide when to use the skill:

---
name: coding
description: "Coding conventions"
---

# coding

Say what the agent should do, step by step. Keep this file short; put long reference
material in separate files next to it.

skillmirror new NAME writes this template, skillmirror adopt NAME --from PROJECT copies a skill a project already has. A skill name is lowercase letters, digits, - and _, at most 64 characters, and unique across the whole vault. doctor checks every header: it must be valid YAML, name must equal the folder name and description must be there. Quote a description that contains a colon.

GroupsCopy Anchor Link

Any folder that holds skills but has no SKILL.md of its own is a group. Groups sort a big vault into Default_Skills/, Web_Skills/ and so on, and they nest without a limit. A folder with no skill below it is ignored, and doctor lists it.

skillmirror skills

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

5 skills in 1 group

Groups exist only in the vault. In a project every skill sits flat in .agents/skills/<name>/. Moving a skill from one group to another therefore changes no project. add --group Web_Skills/seo installs everything below a folder, at any level.

Projects and the rootCopy Anchor Link

A project is any folder below the root that has a .agents/skills folder. The root is set in config.yaml (root:), or by --root, or by SKILLMIRROR_ROOT. skillmirror walks everything below it and finds every .agents/skills/<name>/ folder.

• Projects inside projects are found as projects of their own.
• Links are never followed: a linked project folder or a linked skill folder is invisible.
• These folders are skipped with everything below them: .git, node_modules, vendor, dist, build, out, target, .next, .nuxt, .venv, __pycache__, .tox, .pytest_cache, .cache, .turbo and .parcel-cache.
• You can skip more with exclude_paths and exclude_dirs (Configuration). Test fixtures that look like projects are the usual reason.

A project chooses its skills by what it has. If .agents/skills/coding/ exists, coding is updated from the vault on every sync. If .agents/skills/astro/ does not exist, astro is never added by a sync.

A folder a project has that the vault has no skill for is marked and left alone:

skillmirror list

coding                         ~/projects/atlas-api
doc-start                      ~/projects/atlas-api
file-tree-optimization         ~/projects/atlas-api
astro                          ~/projects/docs-site
coding                         ~/projects/docs-site
custom                         ~/projects/docs-site  (not in vault)
doc-start                      ~/projects/docs-site
coding                         ~/projects/infra
doc-start                      ~/projects/infra
file-tree-optimization         ~/projects/infra
runbooks                       ~/projects/infra  (not in vault)
astro                          ~/projects/lumen-app
coding                         ~/projects/lumen-app
doc-start                      ~/projects/lumen-app
file-tree-optimization         ~/projects/lumen-app

15 skills installed in 4 projects

Three ways a skill gets into a projectCopy Anchor Link

The mandatory list is the mandatory: key of config.yaml: the skills you want everywhere. A profile is a named selection of groups and skills for add and init, for example everything a website needs. Both are covered in Start a project.