skillmirror
Guides

بِسْمِ ٱللَّهِ ٱلرَّحْمَـٰنِ ٱلرَّحِيمِ

Start a project

Make a new project with its skills and AGENTS.md, add skills to a project that exists, and let the mandatory list and profiles choose them.

Putting skills into a project is always a deliberate act, and there are three commands for it. init makes a new project. add puts chosen skills into one that exists. push installs the mandatory skills everywhere.

A new project

skillmirror init ~/projects/lumen-app astro --dry-run
● ~/projects/lumen-app
  + astro                          new (1 file)
  + coding                         new (1 file)
  + doc-start                      new (4 files)
  + file-tree-optimization         new (1 file)

● AGENTS.md
  + ~/projects/lumen-app/AGENTS.md create (from the built-in text)

● Project setup
  + git: a new repository on the branch main (no remote)
  + scaffold: the doc-start skill's Code/bootstrap.sh makes Project_Manag/Docs, Scratch/, Repos/, .gitignore and `just scratch-clean`

4 skills in 1 project: 4 to add (dry run)

init DIR makes the folder and then, in this order:

  1. A git repository on the branch main, with no remote. When DIR is inside a repository already, none is made, so there is never a repository inside a repository, and the plan says which one it is in.
  2. The skills: the mandatory ones plus the names, --group and --profile you give.
  3. The AGENTS.md of the project, from your vault text or the built-in one (AGENTS.md for every project).
  4. The scaffold, made by the project's own copy of the doc-start skill: skillmirror runs its Code/bootstrap.sh. What a new project looks like is therefore written in that skill and nowhere else. Change the skill and every new project follows.

DIR must not exist or must be empty. Without --dry-run the command asks, then writes:

skillmirror init ~/projects/lumen-app astro --yes
● ~/projects/lumen-app
  + astro                          added (1 file)
  + coding                         added (1 file)
  + doc-start                      added (4 files)
  + file-tree-optimization         added (1 file)

● AGENTS.md
  + ~/projects/lumen-app/AGENTS.md created (from the built-in text)

● Project setup
  + git: a new repository on the branch main (no remote)
  + scaffold: the doc-start skill's Code/bootstrap.sh makes Project_Manag/Docs, Scratch/, Repos/, .gitignore and `just scratch-clean`
    created: Project_Manag/Docs/doc_Start.md, Scratch/, Repos/, .gitignore

4 skills in 1 project: 4 added
Backup: run 20261103-224136-119-14984-0 (undo with: skillmirror undo)

The lines under scaffold are the output of the skill's script, so yours depend on your doc-start skill. skillmirror makes no commit: the repository is empty, and the first commit is yours.

cd ~/projects/lumen-app && git log --oneline; git status --short | head
fatal: your current branch 'main' does not have any commits yet
?? .agents/
?? .gitignore
?? AGENTS.md
?? Project_Manag/
FlagLeaves out
--no-gitthe repository
--no-scaffoldthe doc-start script
--no-agents-mdthe AGENTS.md
--no-mandatorythe mandatory skills (then name at least one skill, or --group, or --profile)

undo takes back the skills and the AGENTS.md of the run. The folder, the repository and the scaffold stay.

These stop init before it makes anything, each with a hint:

error: ~/projects/lumen-app is not empty
hint: `skillmirror add` installs skills into an existing project
error: the project scaffold is made by the script of the doc-start skill, and doc-start is not among the skills this install gives the project
hint: install doc-start too (make it mandatory with `skillmirror mandatory add doc-start`), or pass --no-scaffold
error: nothing selected
hint: name skills, or pass --group or --profile

Add skills to a project that exists

skillmirror add astro --project ~/projects/docs-site --dry-run
● ~/projects/docs-site
  + astro                          new (1 file)

1 skill in 1 project: 1 to add (dry run)

add takes skill names, --group PATH for everything below a vault folder, and --profile NAME for a profile. It works out the plan, asks, installs, and makes the .agents/skills folder if the project has none. Without --dry-run it asks [y/N]; --yes answers for you:

skillmirror add astro --project ~/projects/docs-site --yes
● ~/projects/docs-site
  + astro                          added (1 file)

1 skill in 1 project: 1 added
Backup: run 20261103-225315-800-56209-0 (undo with: skillmirror undo)

A skill the project has already is only checked, and --group Web_Skills would install every skill below that vault folder in one go:

skillmirror add astro --project ~/projects/infra --yes
● ~/projects/infra
  = astro                          up to date

1 skill in 1 project: 1 up to date

When the vault copy of a skill the project has differs, add updates it, like sync would. A name the vault does not have stops the command before it writes anything:

error: skill "nosuchskill" is not in the vault
hint: `skillmirror skills` lists the vault

Without --project, add installs into the current folder

cd ~ && skillmirror add astro plans an install into your home folder. Check the folder, or name the project. A project directory that does not exist is an error with a hint to use init.

The mandatory list and push

Some skills belong everywhere. List them in the vault, and push installs them into every project that has a skills folder, even an empty one. A new vault has no mandatory skills:

skillmirror mandatory list
No mandatory skills.
skillmirror mandatory add doc-start --dry-run
doc-start
(dry run: ~/skills/config.yaml is not changed)

mandatory add and mandatory remove edit the mandatory: key of config.yaml and keep its comments and other keys. A name the vault does not have is an error, and so is removing a name that is not on the list. Now push shows what it would install:

skillmirror push --dry-run
● ~/projects/atlas-api
  + doc-start                      new (4 files)

● ~/projects/docs-site
  + doc-start                      new (4 files)

● ~/projects/infra
  + doc-start                      new (4 files)

3 skills in 3 projects: 3 to add (dry run)

push --yes installs them and makes a backup run, like every command that writes. push NAME installs only that mandatory skill, and a name that is not mandatory is refused:

error: skill "astro" is not a mandatory skill
hint: `push` installs the mandatory skills; `add` installs any other skill into one project

init installs the mandatory skills into every new project, and status lists a project that lacks one.

Profiles

A profile is a named selection for add and init, for example everything a website needs. Profiles live in config.yaml:

~/skills/config.yaml
profiles:
  websites:
    description: Everything for a website
    groups: [Web_Skills]
    skills: [coding]
  site:
    extends: [websites]
    exclude: [astro]
skillmirror add --profile websites --project ~/projects/atlas-api --dry-run
● ~/projects/atlas-api
  + astro                          new (1 file)
  = coding                         up to date

2 skills in 1 project: 1 to add, 1 up to date (dry run)

The skills of a profile are what its parents select, plus its own groups and skills, minus its own exclude. An exclude only removes what its own profile selects, so the order of extends never changes the result. A skill named in exclude must exist in the vault. sync and status take --profile as well, to limit themselves to the skills of one profile. An unknown profile is an error:

error: profile "nosuch" is not defined in the vault config
hint: define it under `profiles:` in <vault>/config.yaml

Improve a skill where you use it

Edit a skill inside a project, see what you changed with changes, put it into the vault with promote, and spread it to the other projects.

AGENTS.md for every project

One block of rules that skillmirror keeps the same in every project, with your own notes below it that it never touches.

On this page

A new projectAdd skills to a project that existsThe mandatory list and pushProfiles