feat!: rename writing-great-skills to writing-for-agents and restructure

The reference now covers any document an agent consumes — skills,
AGENTS.md/CLAUDE.md, docs reached by a pointer. GLOSSARY.md merged into
SKILL.md as a dedup (Avoid-lists and the standalone Predictability
definition pruned); skill-only mechanics disclosed to SKILL-MECHANICS.md;
the skill is now model-invoked. Clean rename, no alias.

Spec: mattpocock/personal-wiki#187 · ships via mattpocock/personal-wiki#193

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/productivity/writing-for-agents.md

@@ -0,0 +1,42 @@
+Quickstart:
+
+```bash
+npx skills add mattpocock/skills --skill=writing-for-agents
+```
+
+```bash
+npx skills update writing-for-agents
+```
+
+[Source](https://github.com/mattpocock/skills/tree/main/skills/productivity/writing-for-agents)
+
+## What it does
+
+`writing-for-agents` is the reference you write agent-facing documents against — skills, `AGENTS.md` / `CLAUDE.md`, and any doc an agent reaches by a pointer. The packaging differs; the writing does not: the same levers make each one predictable, so the agent takes the same *process* every run rather than producing the same output.
+
+Formerly `writing-great-skills`. The rename tracks what the reference always was underneath: almost none of it is skill-specific. The universal core — context pointers, the two loads, the information hierarchy, completion criteria, leading words, pruning — applies to any document an agent consumes; the genuinely skill-only mechanics (frontmatter, the model- vs user-invoked choice, router skills) are disclosed to a linked `SKILL-MECHANICS.md` you read only when the document you're writing is a skill.
+
+## When to reach for it
+
+The agent reaches for it on its own whenever you're creating or editing a skill, or modifying `AGENTS.md` or `CLAUDE.md` — and you can still type `/writing-for-agents` to pull it up directly.
+
+## The two loads
+
+The concept the whole reference turns on is a pair of budgets every document and pointer spends:
+
+- **Context load** — the cost of always-loaded material on the agent's window: an `AGENTS.md` line, a skill description, anything sitting in context every turn whether or not it fires.
+- **Cognitive load** — the cost on the human: which documents exist and when to reach for each. You are the index. Not a cost to minimise — it's the price of human agency.
+
+Once you're thinking in these two loads, most authoring decisions — split or don't, inline or disclose, point or push — become the same trade made in different places.
+
+## The other levers
+
+- **Context pointers** — the reference held in context that names out-of-context material and encodes when to reach it. A skill description and an `AGENTS.md` line pointing at a doc are the same object; the pointer's *wording*, not its target, decides when and how reliably the agent reaches through it.
+- **Information hierarchy** — the ladder from in-file step, to in-file reference, to disclosed reference behind a pointer. **Progressive disclosure** is the move down that ladder so the top stays legible; **co-location** decides what sits beside each piece once placed.
+- **Completion criteria** — the clarity and demand of each step's done-condition, and the **legwork** it drives; the defence against **premature completion**.
+- **Leading words** — a compact concept already in the model's pretraining (*tight*, *red*, *tracer bullet*) that the agent thinks with while running the document; hunt restatements a single word can retire.
+- **Pruning** — single source of truth, relevance, and the no-op test applied sentence by sentence, against **sediment** and **sprawl**.
+
+## Where it fits
+
+This is a reach-for-it-anytime standalone reference — the meta-skill you consult while building the rest of the set, not a step in a chain. When you're unsure which skill or flow fits a task, [ask-matt](https://aihero.dev/skills-ask-matt) routes you over the whole set.

docs/productivity/writing-great-skills.md

@@ -1,45 +0,0 @@
-Quickstart:
-
-```bash
-npx skills add mattpocock/skills --skill=writing-great-skills
-```
-
-```bash
-npx skills update writing-great-skills
-```
-
-[Source](https://github.com/mattpocock/skills/tree/main/skills/productivity/writing-great-skills)
-
-## What it does
-
-`writing-great-skills` is the reference you write and edit skills against — the shared vocabulary and principles that make a skill predictable.
-
-A skill's job is to wrangle determinism out of a stochastic system, so the goal is not the same *output* every run but the same *process*. **Predictability** is the root virtue, and every design choice is judged against it — not against how clever, complete, or exhaustive the skill reads.
-
-## When to reach for it
-
-You invoke this by typing `/writing-great-skills` — the agent won't reach for it on its own.
-
-Reach for it whenever you're authoring a new skill or editing an existing one and want it to behave the same way every time: deciding invocation mode, writing a description, choosing what lives in `SKILL.md` versus a linked file, or diagnosing why a skill misfires.
-
-## Cognitive load
-
-The concept the whole reference turns on is **cognitive load** — and its counterpart, **context load**. Every skill spends one or the other:
-
-- A **model-invoked** skill keeps a description in the window every turn, so it costs **context load** but fires on its own.
-- A **user-invoked** skill strips that description; it costs zero context load, but now *you* are the index that has to remember it exists — that's **cognitive load**.
-
-Most of these skills are user-invoked, which is why cognitive load is the pressure the whole system is built to manage: when user-invoked skills multiply past what you can hold in your head, the cure is a **router skill** that names the others and when to reach for each. Once you're thinking in these two loads, most authoring decisions — split or don't, inline or disclose, model- or user-invoked — become the same trade made in different places.
-
-## The other levers
-
-The rest of the reference is the toolkit for spending those loads well:
-
-- **Leading words** — a compact concept already in the model's pretraining (_tight_, _red_, _tracer bullet_) that the agent thinks with while running the skill. It anchors execution *and* invocation in the fewest tokens; hunt restatements that a single word can retire.
-- **Information hierarchy** — the ladder from in-skill step, to in-skill reference, to external reference behind a **context pointer**. **Progressive disclosure** is the move down that ladder so the top stays legible.
-- **Pruning** — single source of truth, relevance, and the no-op test applied sentence by sentence, against **sediment** and **sprawl**.
-- **Failure modes** — **premature completion**, **duplication**, **sediment**, **sprawl**, **no-op** — to diagnose a skill that isn't behaving.
-
-## Where it fits
-
-This is a reach-for-it-anytime standalone reference — the meta-skill you consult while building the rest of the set, not a step in a chain. Its natural neighbour is any router you maintain, because a router is the direct cure for the cognitive load that user-invoked skills pile up; when you're unsure which skill or flow fits a task, [ask-matt](https://aihero.dev/skills-ask-matt) routes you over the whole set.