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

misc: demote to a non-promoted bucket

Browse source 
misc/ skills are no longer installable via the plugin or listed in the
top-level README — they join personal/ as kept-but-unshipped. Only
engineering/ and productivity/ are promoted now.

- Drop the Misc section from the top-level README.
- Reclassify misc/ as non-promoted in CLAUDE.md (README/plugin rule,
  bucket-README grouping rule, docs-page rule) and the writing-docs guide.
- Note the non-promoted status in the misc bucket README.

plugin.json already omitted misc, so no manifest change was needed.
No SKILL.md context pointer referenced a misc skill, so nothing else
had to move.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Matt Pocock 2026-07-01 11:36:37 +01:00
parent 8fa032a8fd
commit 7efc3d2a38
4 changed files with 7 additions and 16 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 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.
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`. Only these two buckets are promoted; the rest (`misc/`, `personal/`, `in-progress/`, `deprecated/`) ship no docs 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 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.
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 `misc/`, `personal/`, `in-progress/`, and `deprecated/` get no page — none of those buckets is promoted. A skill moving *out* of one of them into `engineering/` or `productivity/` gains a page; one moving the other way loses it.
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.