b442590419
An audit of all 25 docs pages found the two sections that carry the most weight are the two the standard treated as optional. Only grill-me has a Common questions section. Twelve pages have no It's working if, and several that do use it for compliance checks on the skill's internals rather than for signals the reader can see. writing-docs.md now names the four-section spine, gates Common questions on evidence -- the personal wiki where it exists on the machine, this repo's issues, and CHANGELOG.md -- and raises the It's working if bar to "checkable without opening SKILL.md". CLAUDE.md names the four sections in the pointer. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
3.5 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. A finished page carries four sections — What it does, When to reach for it, Common questions, It's working if — and writing-docs.md holds the template, the section order, and where to hunt for the questions. 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.