Kind: leaf
Effort: S · Risk: low
Source: paulirish/dotfiles (run 2026-08-23)
Decision: adopt
Problem
There is no listing of what skills exist; finding out means ls plus opening files.
Current state (this repo)
home/.agents/skills/ holds 8 real directories and 18 symlinks into the mattpocock-skills submodule — 26 entries, no index anywhere in the repo. scripts/check-skill-frontmatter.py already parses every frontmatter block and then discards the data.
Their approach
agents/README.md is a per-skill index kept beside the skills: name, one-line description lifted from frontmatter, and the exact install command for each.
Difference that matters
Discoverability for both readers of this repo — the human and the agent that has to decide which skill applies. The parser already exists here; only the emit step is missing, and the vendored-versus-local distinction (which entries are editable, which are submodule symlinks) is information currently recorded only in CLAUDE.md prose.
Translation into this repo
Emit home/.agents/skills/README.md from the frontmatter name/description already parsed by scripts/check-skill-frontmatter.py, flagging symlinked entries as vendored. Add make check-skill-index that regenerates and fails when stale under $CI, matching the self-heal-locally / fail-in-CI pattern check-copilot-instructions already establishes. Land together with frontmatter-required-keys -- both are edits to scripts/check-skill-frontmatter.py, and splitting them means touching the same file twice.
Kind: leaf
Effort: S · Risk: low
Source: paulirish/dotfiles (run 2026-08-23)
Decision: adopt
Problem
There is no listing of what skills exist; finding out means
lsplus opening files.Current state (this repo)
home/.agents/skills/holds 8 real directories and 18 symlinks into themattpocock-skillssubmodule — 26 entries, no index anywhere in the repo.scripts/check-skill-frontmatter.pyalready parses every frontmatter block and then discards the data.Their approach
agents/README.mdis a per-skill index kept beside the skills: name, one-line description lifted from frontmatter, and the exact install command for each.Difference that matters
Discoverability for both readers of this repo — the human and the agent that has to decide which skill applies. The parser already exists here; only the emit step is missing, and the vendored-versus-local distinction (which entries are editable, which are submodule symlinks) is information currently recorded only in
CLAUDE.mdprose.Translation into this repo
Emit
home/.agents/skills/README.mdfrom the frontmattername/descriptionalready parsed byscripts/check-skill-frontmatter.py, flagging symlinked entries as vendored. Addmake check-skill-indexthat regenerates and fails when stale under$CI, matching the self-heal-locally / fail-in-CI patterncheck-copilot-instructionsalready establishes. Land together with frontmatter-required-keys -- both are edits to scripts/check-skill-frontmatter.py, and splitting them means touching the same file twice.