mirror of
https://github.com/mattpocock/skills.git
synced 2026-09-12 10:28:06 +07:00
Matt PocockandClaude Opus 5
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>
24 lines
3.5 KiB
Markdown
24 lines
3.5 KiB
Markdown
Skills are organized into bucket folders under `skills/`:
|
|
|
|
- `engineering/` — daily code work
|
|
- `productivity/` — daily non-code workflow tools
|
|
- `misc/` — kept around but rarely used, not promoted
|
|
- `in-progress/` — beta: public on purpose, feedback wanted, not shipped in the plugin
|
|
- `deprecated/` — 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](./.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](./.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.md`s and the top-level `README.md` group entries into **User-invoked** and **Model-invoked**; non-promoted bucket `README.md`s (`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](./.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](./.agents/invocation.md).
|
|
|
|
[`ask-matt`](./skills/engineering/ask-matt/SKILL.md) 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.
|