arda/skills
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: exclude misc/ skills from the public docs

Browse source 
misc/ skills are niche — they stay promoted (README + plugin manifest,
so they're installable) but no longer get a public aihero.dev docs
page. Remove the four misc pages and decouple the docs rule from the
promotion rule in CLAUDE.md and the writing-docs guide.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Matt Pocock 2026-07-01 11:31:29 +01:00
parent ade35dc0d8
commit 8fa032a8fd
6 changed files with 3 additions and 164 deletions
Download patch file Download diff file Expand all files Collapse all files

4
.agents/writing-docs.md
View file

@ -1,10 +1,10 @@
# Writing docs pages
Every promoted skill (`engineering/`, `productivity/`, `misc/`) has a human-facing **docs page** at `docs/<bucket>/<skill-name>.md` — the docs tree mirrors the bucket folders under `skills/`. It is published at `https://aihero.dev/skills-<skill-name>`; the URL is always `skills-<skill-name>` regardless of bucket, so the docs path is repo organisation only. The page is not the skill and not a copy of `SKILL.md`.
Every skill in `engineering/` and `productivity/` has a human-facing **docs page** at `docs/<bucket>/<skill-name>.md` — the docs tree mirrors those two bucket folders under `skills/`. It is published at `https://aihero.dev/skills-<skill-name>`; the URL is always `skills-<skill-name>` regardless of bucket, so the docs path is repo organisation only. The page is not the skill and not a copy of `SKILL.md`. `misc/` skills are promoted (they appear in the README and plugin manifest, so they're installable) but deliberately get **no** public docs page — they're niche enough to earn an install entry but not an `aihero.dev` page.
Most of these skills are **user-invoked**: the agent will never fire them for you, so *you* are the index that has to remember they exist and when to reach for them. That memory is **cognitive load**. The job of a docs page is to relieve it — to orient one reader around one skill so they can hold it in their head, know when to reach for it, and see where it sits in the system. The pages are collectively a distributed router; each is a node.
Act whenever a promoted skill is added, renamed, or has its behaviour changed: create or re-sync its docs page. A rename moves the file too (`docs/<bucket>/<old>.md` → `docs/<bucket>/<new>.md`), because the published URL tracks the name; a skill that moves buckets moves its docs file to the matching folder. Skills in `personal/`, `in-progress/`, and `deprecated/` get no page, mirroring the README rule.
Act whenever a promoted skill is added, renamed, or has its behaviour changed: create or re-sync its docs page. A rename moves the file too (`docs/<bucket>/<old>.md` → `docs/<bucket>/<new>.md`), because the published URL tracks the name; a skill that moves between `engineering/` and `productivity/` moves its docs file to the matching folder. Skills in `personal/`, `in-progress/`, and `deprecated/` get no page because they aren't promoted at all; `misc/` skills get no page despite being promoted. A skill moving *into* `misc/` loses its docs page; one moving *out* of `misc/` into `engineering/` or `productivity/` gains one.
Because these pages are published on `aihero.dev`, **every link is absolute** — never a repo-relative path. A link to another skill points at `https://aihero.dev/skills-<name>`; a link into the repo points at its full `https://github.com/mattpocock/skills/...` URL. A relative link that works in the repo breaks once published.