c66bdeeee0
Delete the four skills in deprecated/ — design-an-interface, qa, request-refactor-plan, ubiquitous-language — each already absorbed by a promoted skill. The bucket itself stays, now empty: a retired skill is deleted, and the changeset that removes it names its replacement. Delete edit-article and obsidian-vault along with the personal/ bucket. obsidian-vault hardcoded a path to Matt's own vault and was model-invocable, so any skills.sh user could have had it fire on them. None of the six was in the plugin, but skills.sh serves every SKILL.md in the repo, so all six were installable — hence the changeset. Reframe in-progress/ from scratchpad to beta channel: public on purpose, feedback wanted, not in the plugin, and installable one skill at a time through skills.sh. Nothing there is deleted or graduated. Drop qa from the two live docs that cited it as an issue-tracker skill. ADR 0002 is left untouched — it records reasoning that was true when decided. Resolves mattpocock/personal-wiki#256 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
3.3 KiB
Skills are organized into bucket folders under skills/:
engineering/— daily code workproductivity/— daily non-code workflow toolsmisc/— kept around but rarely used, not promotedin-progress/— beta: public on purpose, feedback wanted, not shipped in the plugindeprecated/— no longer used
Every skill in engineering/ or productivity/ (the promoted buckets) must have a reference in the top-level README.md and an entry in .claude-plugin/plugin.json's skills array (the Claude Code plugin ships exactly the promoted set). Skills in misc/, in-progress/, and deprecated/ must not appear in either.
Install commands are copied verbatim from .agents/install-block.md. .claude-plugin/marketplace.json makes the repo its own single-plugin marketplace — a fallback the install block explains, not the documented route. When bumping the release version, keep .claude-plugin/plugin.json's version in sync with package.json's — Claude uses the plugin version to decide when installed users see an update. Run claude plugin validate . --strict after touching either manifest. Why a Claude plugin but not (yet) a Codex one lives in .agents/adr/0002-ship-as-a-claude-code-plugin.md.
Each skill entry in the top-level README.md must link the skill name to its SKILL.md.
Each bucket folder has a README.md that lists every skill in the bucket with a one-line description, with the skill name linked to its SKILL.md. The promoted buckets' README.mds and the top-level README.md group entries into User-invoked and Model-invoked; non-promoted bucket README.mds (misc/, in-progress/) use a flat list.
Skills in engineering/ and productivity/ also have a human-facing docs page at docs/<bucket>/<skill-name>.md (the docs tree mirrors those two bucket folders under skills/). The published URL is https://aihero.dev/skills-<skill-name> regardless of bucket — the docs path is repo organisation only. When you add, rename, or change the behaviour of a skill in engineering/ or productivity/, create or re-sync its docs page following .agents/writing-docs.md. Skills in the non-promoted buckets (misc/, in-progress/, deprecated/) get no docs page.
Every SKILL.md is either user-invoked (disable-model-invocation: true plus policy.allow_implicit_invocation: false in agents/openai.yaml, reachable only by the human) or model-invoked (model- or user-reachable). See .agents/invocation.md.
ask-matt is the router that maps every user-reachable skill and how they relate. The same trigger that re-syncs a docs page applies to it: whenever you add, rename, remove, or change how a user-reachable skill fits the flows, re-read ask-matt's SKILL.md and update it so the map stays accurate — a new skill it never mentions, or a stale one it still routes to, is a router that lies.
To (re)link every skill into the local harness skill directories (~/.claude/skills, ~/.agents/skills), run scripts/link-skills.sh. Each entry is a symlink into this repo, so a git pull keeps installed skills current; re-run the script after adding, removing, or renaming a skill.