77cc47773c
Reframe docs pages around cognitive-load relief: most skills are user-invoked, so the human is the index that must remember when to reach for each one. Each page's job is to make one skill memorable and situate it in the system. Template changes (.agents/writing-docs.md): - Quickstart block: install + `npx skills update`, install-first - New `## When to reach for it` (invocation mode + trigger boundary) - New optional `## Prerequisites` (workspace/state, prior setup, tooling) - Free-form middle with one firm rule: surface the leading word (also an observability signal in the agent's output) - `## Where it fits`: role-based, absorbs "Pairs well with", links ask-matt - No H1; every cross-link absolute Nest docs under bucket folders (docs/<bucket>/<name>.md); the published URL stays skills-<name> regardless. Re-sync to-prd as the worked exemplar. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
1.8 KiB
Skills are organized into bucket folders under skills/:
engineering/— daily code workproductivity/— daily non-code workflow toolsmisc/— kept around but rarely usedpersonal/— tied to my own setup, not promotedin-progress/— drafts not yet ready to shipdeprecated/— no longer used
Every skill in engineering/, productivity/, or misc/ must have a reference in the top-level README.md and an entry in .claude-plugin/plugin.json. Skills in personal/, in-progress/, and deprecated/ must not appear in either.
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. Bucket README.mds and the top-level README.md group entries into User-invoked and Model-invoked.
Every promoted skill also has a human-facing docs page at docs/<bucket>/<skill-name>.md (the docs tree mirrors the 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/, productivity/, or misc/, create or re-sync its docs page following .agents/writing-docs.md.
Every SKILL.md is either user-invoked (disable-model-invocation: true, reachable only by the human) or model-invoked (model- or user-reachable). See .agents/invocation.md.
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.