بِسْمِ ٱللَّهِ ٱلرَّحْمَـٰنِ ٱلرَّحِيمِ
The interface
The full-screen interface that opens when you run skillmirror without arguments, with a tour of its screens and the keys that work on all of them.
Run skillmirror with no arguments in a terminal and a full-screen interface opens. It does everything the commands do, with a plan before every write, and it works with the keyboard and the mouse.
In a script, where stdin or stdout is not a terminal, the same call prints the help and exits 2, so a pipeline never waits for a key. skillmirror tui opens the interface by name.
The menu
skillmirror · javedab.com
Sync agent skills across all your projects from a single vault.
│ Sync Refresh the skills each project already has; never adds one
Override Put the skills you changed in this project into the vault
List Every installed skill; filter, then sync or delete in place
Skills Browse the vault: what each skill is and where it is installed
Delete Nothing pre-selected; you pick, then confirm
Push Install the mandatory skills into every opted-in project
Agents Write the autogenerated block of AGENTS.md into projects
Add Install chosen vault skills into one project
Init Make a new project folder with your skills in it
History Undo a sync, push or delete from the backups
Setup Choose the vault, the scan root and the mandatory skills
────────────────────────────────────────────────────────────────────────────────────────────────
Walks every project under your root and updates skills they already have installed, pulling the
latest from your vault. The opt-in rule: if a project doesn't have a skill, it will inshallah
never be added. Only what's already there gets refreshed.
↑/k up • ↓/j down • enter open • ? help • q quitThe line under the rule explains the entry under the cursor. Every entry is one of the commands you know:
| Entry | The command behind it | What it does |
|---|---|---|
| Sync, Push | sync, push | pick skills, see what would be written, confirm, run |
| Override | changes, promote | shows the skills of the project around the folder you started in against the vault, and replaces the vault's copy of the ones you edited |
| List | list | every installed skill; / filters, space selects, s syncs and d deletes the selection in place |
| Skills | skills, info | the vault, with a card for the skill under the cursor; read-only |
| Delete | delete | nothing is pre-selected; you pick, then confirm; the pane names every project the skill would leave |
| Agents | agents | every project with the state of its AGENTS.md; the ones whose block is out of date are ticked |
| Add | add | pick the project folder, then the vault skills to install into it |
| Init | init | pick a parent folder, name the new project, tick skills (the mandatory ones are ticked) |
| History | history, undo | the backup runs, newest first; pick one to undo it |
| Setup | vault init, config, mandatory | pick the vault and the root, tick the mandatory skills, save |
Keys that work everywhere
| Key | What it does |
|---|---|
? | opens the help of the screen you are on: its keys, in topics (move, choose, find, run, general), with what each is good for |
q or alt+← | goes back; from the menu it quits |
ctrl+c | quits; while something is being written it asks twice |
↑ ↓ or k j | one row up or down; the mouse wheel works too, and a click puts the cursor on a row |
space | ticks or unticks the row under the cursor; only ticked rows are acted on |
a | ticks every row that is shown, or unticks them all when all are ticked |
/ | filters the rows while you type; enter keeps the filter and esc clears it |
enter | runs what the screen is for, and asks first |
Every screen that works out a plan shows it before anything is written, and the question that follows can show the changes with v. If the scan could not read something, the heading says so, and i lists it.
Sync and Push
Both screens list the skills with their state. A skill that would change is ticked for you. A pane beside the list follows the cursor and names the projects of the skill under it.
← skillmirror · javedab.com · sync
Select skills to sync 1 / 4 selected │ coding
/ to filter │ 4 projects, 2 to update
skill projects │ [Affected 2] Others 2 All 4
[ ] astro 2 projects up to date │ ↔ [short] long f filter
> [✓] coding 4 projects 2 to update │ docs-site outdated (2 files)
[ ] doc-start 4 projects up to date │ infra outdated (1 file)
[ ] file-tree-optimization 3 projects up to date │
│
rows 1–4 of 4 │
space toggle • a all • / filter • tab pane • enter sync • v diff • ? help • q/alt+← backOn a terminal narrower than 100 columns the pane sits under the list. In the pane, tab switches between the projects that would change (Affected), the others (Others) and all of them (All). p, or a click on ↔, writes the projects short (parent/project) or long (the path below your scan root). f filters them, and ctrl+d and ctrl+u scroll the pane.
enter shows the plan and asks. Nothing is written before you answer y, and every replaced folder goes to the backup first (Safety and undo).
The changes page
v on a skill opens what a run would change in it, before anything is ticked. v on the question of any run opens the changes of the plan that is about to run, and esc returns to the same question, so y still runs exactly what you saw.
← skillmirror · javedab.com · sync
Changes 3 files in 2 projects, +5 −2 ◀ prev next ▶ [split] inline [folded] whole
coding 3 changes
− in the project + after the sync
▌ coding in projects/docs-site
SKILL.md changed +1 −1
⋯ 7 lines unchanged (click to show)
8 - Keep files under 250 lines of code. │ 8 - Keep files under 250 lines of code.
9 - No fallbacks: fail with a clear error. │ 9 - No fallbacks: fail with a clear error.
10 - Comment the why, never the what. │ 10 - Comment the why, never the what. █
11 - - Name things for the reader. │ 11 + - Name things for the reader. █
╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱│ `references/naming.md` has the rules.
references/naming.md new file +4 −0 █
╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱│ 1 + # Naming █
╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱│ 2 + █
╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱│ 3 + - Verbs for functions, nouns for values. █
╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱│ 4 + - No abbreviation a new reader has to look █
╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱╱│ up.
▌ coding in projects/infra
SKILL.md changed +0 −1
⋯ 8 lines unchanged (click to show)
9 - No fallbacks: fail with a clear error. │ 9 - No fallbacks: fail with a clear error.
10 - Comment the why, never the what. │ 10 - Comment the why, never the what.
11 - Name things for the reader. │ 11 - Name things for the reader.
`references/naming.md` has the rules. │ `references/naming.md` has the rules. █
↑/↓ scroll • n/p change • [/] file • s split/inline • c folds • esc backThe old text is on the left (the project now, or the AGENTS.md now) and the new text on the right (after the sync). The page has line numbers, red and green lines, the changed words marked more strongly, and hatching where one side has no line. Long lines wrap so that both sides stay in step. A change that many projects get in exactly the same way is shown once, with the names of the projects. A binary file, an oversized one and an unreadable one are named without lines, and a project that cannot be compared is listed with the reason.
| Key | What it does |
|---|---|
n p | next and previous change; the buttons in the header do the same |
] [ or tab | next and previous file |
} { | next and previous skill |
g G, ctrl+d ctrl+u | top and bottom, half a page; the arrows, page keys and the wheel scroll too |
s | side by side or one column; a terminal narrower than 70 columns always shows one column |
c | folds the unchanged lines far from a change, or shows whole files; a click on a fold opens that one |
The strip at the right edge of the page is the whole page squeezed into its height, with the changes marked. Click or drag on it to go there. skillmirror diff shows the same changes as unified text for scripts.
Override
Override is the interface of changes and promote. It opens on the project around the folder you started in, or lists the projects below it to pick from, and nothing is read before the entry is opened.
← skillmirror · javedab.com · override
Override the project in this folder
~/projects/infra
skill state what differs
> [ ] coding edited SKILL.md modified
doc-start same
file-tree-optimization same
runbooks new not in the vault
[ ] s then update the other projects that have the replaced skills
1 skill can be replaced
space toggle • a all • s update the others too • enter replace in the vault • ? help • q/alt+← backspace ticks an edited skill and a ticks all of them. s also updates the other projects that have them, which is promote --sync. enter asks, then replaces the vault's copy. The old copy is kept for History, and the new one is staged in the vault's git and never committed.
Agents
The list shows every project with the state of its AGENTS.md. The ones whose block is out of date are ticked.
← skillmirror · javedab.com · agents
Select projects to write the AGENTS.md block into 1 / 5 selected
/ to filter
project state
> [ ] projects/atlas-api current up to date
[ ] projects/docs-site missing no AGENTS.md yet
[ ] projects/infra edited edited by hand; needs agents sync --force
[✓] projects/lumen-app outdated the vault text changed
[ ] projects/orbit no block no autogenerated block yet
rows 1–5 of 5
space toggle • a all • / filter • enter write AGENTS.md • ? help • q/alt+← backYou pick, read the changes with v, and confirm. Only the block between the markers is written (AGENTS.md for every project).
Skills
The vault with a card for the skill under the cursor: its description, its files, the profiles that name it, and what it is in each project. The screen only reads.
← skillmirror · javedab.com · skills
Vault — 5 skills │ coding (mandatory)
/ to filter │ top level of the vault
skill group │ Coding conventions
> coding mandatory, 3 to cha │ profiles: websites
doc-start mandatory, 1 to cha │ files (2): SKILL.md, references/
file-tree-optimization mandatory, 2 to cha │ naming.md
astro …_Skills in 2 projects │
schema …/seo not installed │ Projects
│ projects/atlas-api up to date
│ projects/docs-site outdated (2 files)
│ projects/infra outdated (1 file)
│ projects/lumen-app up to date
│ projects/orbit mandatory, not
│ installed
│
│
rows 1–5 of 5 │
↑/k up • ↓/j down • / filter • ? help • q/alt+← backAdd, Init and Setup
- Add asks for the project folder first, then for the vault skills to install into it.
- Init asks for a parent folder and a name, then for the skills; the mandatory ones are already ticked.
gleaves the git repository out,mtheAGENTS.md, anddthe scaffold, like--no-git,--no-agents-mdand--no-scaffold(Start a project). - Setup is the first-run screen. It asks for the vault and for the scan root, lets you tick the mandatory skills, and writes the configuration.
Look before you sync
Every way to read the state of your skills without writing a file, from status and diff to a report you can open in a browser.
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.