diff --git a/.agents/writing-docs.md b/.agents/writing-docs.md index 2ea84fa..02f95bb 100644 --- a/.agents/writing-docs.md +++ b/.agents/writing-docs.md @@ -1,10 +1,10 @@ # Writing docs pages -Every skill in `engineering/` and `productivity/` has a human-facing **docs page** at `docs//.md` — the docs tree mirrors those two bucket folders under `skills/`. It is published at `https://aihero.dev/skills-`; the URL is always `skills-` 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//.md` — the docs tree mirrors those two bucket folders under `skills/`. It is published at `https://aihero.dev/skills-`; the URL is always `skills-` 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//.md` → `docs//.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//.md` → `docs//.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-`; 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. diff --git a/CLAUDE.md b/CLAUDE.md index 0f97a16..2c49a90 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,18 +2,18 @@ Skills are organized into bucket folders under `skills/`: - `engineering/` — daily code work - `productivity/` — daily non-code workflow tools -- `misc/` — kept around but rarely used +- `misc/` — kept around but rarely used, not promoted - `personal/` — tied to my own setup, not promoted - `in-progress/` — drafts not yet ready to ship - `deprecated/` — 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. +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`. Skills in `misc/`, `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.md`s and the top-level `README.md` group entries into **User-invoked** and **Model-invoked**. +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/`, `personal/`) use a flat list. -Skills in `engineering/` and `productivity/` also have a human-facing docs page at `docs//.md` (the docs tree mirrors those two bucket folders under `skills/`). The published URL is `https://aihero.dev/skills-` 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). `misc/` skills are promoted (README + `plugin.json`) but get **no** docs page. +Skills in `engineering/` and `productivity/` also have a human-facing docs page at `docs//.md` (the docs tree mirrors those two bucket folders under `skills/`). The published URL is `https://aihero.dev/skills-` 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/`, `personal/`, `in-progress/`, `deprecated/`) get **no** docs page. 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](./.agents/invocation.md). diff --git a/README.md b/README.md index ecdc99c..dff5ec2 100644 --- a/README.md +++ b/README.md @@ -179,12 +179,3 @@ General workflow tools, not code-specific. **Model-invoked** - **[grilling](./skills/productivity/grilling/SKILL.md)** — Interview the user relentlessly about a plan or design until every branch of the decision tree is resolved. The reusable loop behind `grill-me` and `grill-with-docs`. - -### Misc - -Tools I keep around but rarely use. - -- **[git-guardrails-claude-code](./skills/misc/git-guardrails-claude-code/SKILL.md)** — Set up Claude Code hooks to block dangerous git commands (push, reset --hard, clean, etc.) before they execute. -- **[migrate-to-shoehorn](./skills/misc/migrate-to-shoehorn/SKILL.md)** — Migrate test files from `as` type assertions to @total-typescript/shoehorn. -- **[scaffold-exercises](./skills/misc/scaffold-exercises/SKILL.md)** — Create exercise directory structures with sections, problems, solutions, and explainers. -- **[setup-pre-commit](./skills/misc/setup-pre-commit/SKILL.md)** — Set up Husky pre-commit hooks with lint-staged, Prettier, type checking, and tests. diff --git a/skills/misc/README.md b/skills/misc/README.md index 89e4cf3..d407187 100644 --- a/skills/misc/README.md +++ b/skills/misc/README.md @@ -1,6 +1,6 @@ # Misc -Tools I keep around but rarely use. +Tools I keep around but rarely use — not promoted in the plugin. - **[git-guardrails-claude-code](./git-guardrails-claude-code/SKILL.md)** — Set up Claude Code hooks to block dangerous git commands (push, reset --hard, clean, etc.) before they execute. - **[migrate-to-shoehorn](./migrate-to-shoehorn/SKILL.md)** — Migrate test files from `as` type assertions to @total-typescript/shoehorn.