edkuksa/skills
1
0
Fork 0
mirror of https://github.com/mattpocock/skills.git synced 2026-09-13 02:48:06 +07:00
Code Issues Packages Projects Releases Wiki Activity

docs: make Common questions and It's working if part of the page standard

Browse Source 
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>
This commit is contained in:
Matt Pocock
2026-08-05 12:01:41 +01:00
co-authored by Claude Opus 5
parent f86d3e0e0d
commit b442590419
3 changed files with 35 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+1 -1
View File
@@ -14,7 +14,7 @@ Each skill entry in the top-level `README.md` must link the skill name to its `S
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). Skills in the non-promoted buckets (`misc/`, `in-progress/`, `deprecated/`) get **no** docs page.
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).