docs: drop the forced code-review neighbour from where-it-fits

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

.agents/writing-docs.md

@@ -12,12 +12,14 @@ There is no H1 — the published page takes its title from the slug.
 
 ## Page structure
 
-Fill the template below. The **fixed frame** (`## What it does`, `## When to reach for it`, `## Where it fits`) appears on every page. The **adaptable middle** — `## Prerequisites` and the free-form substance sections — carries only what this particular skill earns; delete the rest.
+Fill the template below. The **fixed frame** (source link, `## What it does`, `## When to reach for it`, `## Where it fits`) appears on every page. The **adaptable middle** — `## Prerequisites` and the free-form substance sections — carries only what this particular skill earns; delete the rest.
 
 **A page carries no install commands.** The ai-hero page template renders the install widget itself — a copy button, the single-skill command, the whole-set command, and the update line — above the body. A page that also writes them out shows the reader the same command twice, and the two copies drift: the hand-written pair on every page went stale against the widget beside it. Install wording is a property of the site, not of the page. If it needs changing, change it in ai-hero; the canonical wording lives in [the install block](./install-block.md).
 
 <page-template>
 
+[Source](https://github.com/mattpocock/skills/tree/main/skills/<bucket>/<name>)
+
 ## What it does
 
 One or two plain-language paragraphs. Lead with the skill's one-sentence job, then state the **defining constraint** — the single fact that makes this skill behave differently from the obvious default (for `to-spec`: it does not interview the user again, it synthesises what is already known). Write it as a plain declarative sentence — never a labelled aside like "The defining constraint:" or "The key thing:"; the formula reads as filler. This line is the most valuable on the page; never omit it.
@@ -62,7 +64,7 @@ Always present. Situate the skill in the system in a sentence or two:
 ## Done when
 
 - The page exists at `docs/<bucket>/<name>.md`, and no stale page survives a rename or bucket move.
-- The page carries no source link and writes no install command of its own.
+- The source link names the correct bucket and skill, and the page writes no install command of its own.
 - `## What it does` states the defining constraint, as plain prose rather than a labelled aside.
 - `## When to reach for it` states invocation mode and the trigger boundary.
 - `## Where it fits` names the role and links to `ask-matt`.

.changeset/docs-writing-for-agents-pass.md

@@ -0,0 +1,15 @@
+---
+"mattpocock-skills": patch
+---
+
+Rewrite the `writing-for-agents` docs page around what people actually get wrong.
+
+The old page was a table of contents for the skill: the two loads, then a bullet per lever. It answered none of the questions the rename and the AMA threads have been generating for months — where `writing-great-skills` went, whether the agent or the human is doing the writing, why you shouldn't just ask Claude to write the skill for you, and how you know when a document is done.
+
+The rewrite keeps the levers to one compact list and spends the page on the judgement calls instead:
+
+- **The defining constraint is now stated up front** — the default move is deletion, not explanation, because the reader has already read everything. This is also the answer to "why not let the model write it", so it leads.
+- **The scope is stated as a test**, not a list: does an agent read this document and act? Skills, `AGENTS.md`, specs, tickets and runtime prompts all pass it.
+- **A "Common questions" section** answers the nine highest-volume ones directly, including the rename, the "streamline" failure where an agent trims for length and cuts behaviour, whether to rewrite documents per model, the skill that only works on the one task it was built from, and the leading-word question from non-native English speakers.
+- **"It's working if"** added, led by the sharpest signal: the document gets shorter as it gets better, and duplication is the most reliable sign it was never tested.
+- **`Where it fits`** says plainly that it has no chain neighbour: it sits underneath the set rather than beside one skill, and the documents the other skills leave behind are the text it governs.

docs/engineering/ask-matt.md

@@ -1,3 +1,5 @@
+[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/ask-matt)
+
 ## What it does
 
 `ask-matt` is the router over the skills in this repo. You describe the situation you're in; it tells you which skill or flow fits and in what order to run them.
@@ -20,4 +22,4 @@ The other idea it hands you is the **phase boundary**. A **phase** is a chunk of
 
 ## Where it fits
 
-`ask-matt` is the **router** — the standalone map that sits over the whole set. It is the node every other docs page links back to as [ask-matt](https://aihero.dev/skills-ask-matt), so it never sits *in* a chain; it points *into* every chain. From here you'll most often land on [grill-with-docs](https://aihero.dev/skills-grill-with-docs), the head of the main flow, or [triage](https://aihero.dev/skills-triage), the on-ramp for work you didn't create. When even the router's own picture is stale, the skill itself is the map of record.
+`ask-matt` is the **router** — the standalone map that sits over the whole set. It is the node every other docs page links back to as [ask-matt](https://aihero.dev/skills-ask-matt), so it never sits *in* a chain; it points *into* every chain. From here you'll most often land on [grill-with-docs](https://aihero.dev/skills-grill-with-docs), the head of the main flow, or [triage](https://aihero.dev/skills-triage), the on-ramp for work you didn't create. When even the router's own picture is stale, its [Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/ask-matt) is the map of record.

docs/engineering/code-review.md

@@ -1,3 +1,5 @@
+[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/code-review)
+
 ## What it does
 
 `code-review` reviews the diff between `HEAD` and a fixed point you supply — a commit, branch, tag, or merge-base — along two separate axes: **Standards** (does the code follow this repo's documented conventions?) and **Spec** (does it implement what the originating issue or spec asked for?). It runs each axis as its own parallel sub-agent and reports them side by side. It never merges or re-ranks the two sets of findings — keeping them separate is the whole point, because a change can pass one axis and fail the other, and a single blended verdict lets one mask the other.

docs/engineering/codebase-design.md

@@ -1,3 +1,5 @@
+[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/codebase-design)
+
 ## What it does
 
 `codebase-design` gives you a shared, precise vocabulary for designing **deep modules** — a lot of behaviour hidden behind a small interface, placed at a clean seam, testable through that interface.

docs/engineering/diagnosing-bugs.md

@@ -1,3 +1,5 @@
+[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/diagnosing-bugs)
+
 ## What it does
 
 `diagnosing-bugs` runs a disciplined diagnosis loop for hard bugs and performance regressions — building a repro, minimising it, ranking hypotheses, instrumenting, then fixing with a regression test.

docs/engineering/domain-modeling.md

@@ -1,3 +1,5 @@
+[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/domain-modeling)
+
 ## What it does
 
 `domain-modeling` builds and sharpens a project's **ubiquitous language** as you design — challenging fuzzy terms, stress-testing relationships with concrete scenarios, and writing the glossary and decisions down the moment they crystallise.

docs/engineering/grill-with-docs.md

@@ -1,3 +1,5 @@
+[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/grill-with-docs)
+
 ## What it does
 
 `grill-with-docs` interviews you relentlessly about a plan or design, a round of questions at a time, until you and the agent reach a shared understanding — and it writes the vocabulary and decisions down as you go.

docs/engineering/implement.md

@@ -1,3 +1,5 @@
+[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/implement)
+
 ## What it does
 
 `implement` builds the work described in a spec or a set of tickets — driving it through test-driven development, typechecking, and the full test suite, then handing off to review and committing to the current branch.

docs/engineering/improve-codebase-architecture.md

@@ -1,3 +1,5 @@
+[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/improve-codebase-architecture)
+
 ## What it does
 
 `improve-codebase-architecture` scans a codebase for **deepening opportunities** — places where a shallow module (an interface nearly as complex as the thing it hides) could become a deep one — presents them as a self-contained visual HTML report, then grills through whichever one you pick.

docs/engineering/prototype.md

@@ -1,3 +1,5 @@
+[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/prototype)
+
 ## What it does
 
 `prototype` builds a small, disposable program whose only job is to answer one design question — does this state model feel right, or what should this UI look like.

docs/engineering/research.md

@@ -1,3 +1,5 @@
+[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/research)
+
 ## What it does
 
 `research` answers a question by reading the sources that own the answer and leaving a cited Markdown file behind. It works only from **primary sources** — official docs, source code, specs, first-party APIs — never a secondary write-up of them, so what it saves is traceable back to something authoritative rather than a summary of a summary.

docs/engineering/resolving-merge-conflicts.md

@@ -1,3 +1,5 @@
+[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/resolving-merge-conflicts)
+
 ## What it does
 
 `resolving-merge-conflicts` works through an in-progress git merge or rebase conflict, hunk by hunk, and finishes the operation — resolved, checked, and committed.

docs/engineering/setup-matt-pocock-skills.md

@@ -1,3 +1,5 @@
+[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/setup-matt-pocock-skills)
+
 ## What it does
 
 `setup-matt-pocock-skills` teaches one repo how the engineering skills should behave in it — where issues live, what the triage labels are called, and where the domain docs sit — and records those answers as **config** the other skills read.

docs/engineering/tdd.md

@@ -1,3 +1,5 @@
+[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/tdd)
+
 ## What it does
 
 `tdd` builds a feature or fixes a bug test-first, one behaviour at a time, driving the code out through a red-green loop.

docs/engineering/to-spec.md

@@ -1,3 +1,5 @@
+[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/to-spec)
+
 ## What it does
 
 `to-spec` turns the current conversation and your codebase understanding into a spec, then publishes it to your issue tracker.

docs/engineering/to-tickets.md

@@ -1,3 +1,5 @@
+[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/to-tickets)
+
 ## What it does
 
 `to-tickets` breaks a plan, spec, or the current conversation into a set of **tickets** — each a tracer-bullet vertical slice — and publishes them to your configured tracker, with every ticket declaring the tickets that block it.

docs/engineering/triage.md

@@ -1,3 +1,5 @@
+[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/triage)
+
 ## What it does
 
 `triage` moves issues on your project's tracker through a small **state machine** of triage roles — categorise them, verify the claim, grill them into shape if needed, and leave a ready-for-agent brief.

docs/engineering/wayfinder.md

@@ -1,3 +1,5 @@
+[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/wayfinder)
+
 ## What it does
 
 `wayfinder` takes an effort too big for one agent session — wrapped in fog, where the way from here to the goal isn't visible yet — and charts it as a **shared map** of **decision tickets** on your issue tracker, then resolves them one at a time until the way is clear. It **plans, it doesn't do**: every ticket resolves a decision — a question to settle, not a slice of a build to execute — and the map is done when nothing is left to decide before someone goes and builds the thing — so it produces decisions, not deliverables.

docs/engineering/wizard.md

@@ -1,3 +1,5 @@
+[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/wizard)
+
 ## What it does
 
 `wizard` generates an interactive bash script that walks a human, step by step, through a manual procedure that's tedious to do by hand and tedious to re-explain to an agent every time — wiring up third-party services, running a one-off migration, moving a project from state A to state B. It opens each URL, says what to click and copy, captures what comes back, and writes it where it belongs.

docs/productivity/grill-me.md

@@ -1,3 +1,5 @@
+[Source](https://github.com/mattpocock/skills/tree/main/skills/productivity/grill-me)
+
 ## What it does
 
 `grill-me` takes a **loose idea** and interviews you until it has real decisions in it. You do not need a worked-out plan to start — producing one is what the session is for. It asks in **rounds**: each round is the whole **frontier** — every question whose prerequisites you have already settled — so you are never asked something that hinges on an answer it hasn't heard yet.

docs/productivity/grilling.md

@@ -1,3 +1,5 @@
+[Source](https://github.com/mattpocock/skills/tree/main/skills/productivity/grilling)
+
 ## What it does
 
 `grilling` is the relentless interview that stress-tests a plan or design before you build it. It maps the plan as a **design tree** — every decision branches into the decisions that hang off it — and works that tree in **rounds** until you and the agent share the same understanding.

docs/productivity/handoff.md

@@ -1,3 +1,5 @@
+[Source](https://github.com/mattpocock/skills/tree/main/skills/productivity/handoff)
+
 ## What it does
 
 `handoff` compacts the current conversation into a **handoff document** — a single write-up a fresh agent can read to pick up the work where you left off.

docs/productivity/teach.md

@@ -1,3 +1,5 @@
+[Source](https://github.com/mattpocock/skills/tree/main/skills/productivity/teach)
+
 ## What it does
 
 `teach` turns the current directory into a standing teaching workspace and teaches you one topic across many sessions — devising short, beautiful, interactive lessons tied to *why* you want to learn.

docs/productivity/to-questionnaire.md

@@ -1,3 +1,5 @@
+[Source](https://github.com/mattpocock/skills/tree/main/skills/productivity/to-questionnaire)
+
 ## What it does
 
 `to-questionnaire` turns a decision you can't settle on your own into a **questionnaire** — a Markdown document you hand to the one person who holds what you're missing, to fill in async or work through together in a meeting.

docs/productivity/wait-what.md

@@ -1,3 +1,5 @@
+[Source](https://github.com/mattpocock/skills/tree/main/skills/productivity/wait-what)
+
 ## What it does
 
 `wait-what` is the fire extinguisher for a message that didn't land. You fire it the moment you lose the thread, and the agent re-pitches what it just said: a little of the context you were missing, plain English, and the vocabulary from your project's `CONTEXT.md`.

docs/productivity/writing-for-agents.md

@@ -1,30 +1,72 @@
+[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.
+`writing-for-agents` is the reference you write agent-facing documents against — a skill, an `AGENTS.md` / `CLAUDE.md`, a spec, a runtime prompt, a README, any doc an agent reads. 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.
+Its default move is deletion, not explanation. Ask an agent to write instructions for another agent and it spends most of its words explaining what the model already knows — every one of those lines is a **no-op**, paying context and changing no behaviour. This reference is the lens that finds them, which is why it earns its keep at least as often on a document you already have as on a blank file.
+
+It was called `writing-great-skills` until v1.1. The rename tracks what it always was underneath: almost none of it is skill-specific. The skill-only mechanics — frontmatter, the model- versus user-invoked choice, router skills — are disclosed to a linked `SKILL-MECHANICS.md` you read only when the document in front of you 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.
+Type `/writing-for-agents`, or the agent reaches for it on its own when you're creating or editing a skill, or modifying `AGENTS.md` or `CLAUDE.md`.
+
+Reach for it by hand for everything else an agent reads: your docs, specs and tickets, system and AFK prompts. The test is one question — does an agent read this? — and it does not matter how the document gets in front of it, whether a pointer names it, a human pastes it, or it simply sits in the repo. For working out what a codebase actually contains in the first place, use [grill-with-docs](https://aihero.dev/skills-grill-with-docs) — this reference governs how a document reads, not what it knows.
 
 ## The two loads
 
-The concept the whole reference turns on is a pair of budgets every document and pointer spends:
+The idea 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.
+- **Cognitive load** — the cost on you: which documents exist, and when to reach for each. You are the index. Not a cost to minimise — it is 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.
+Once you think 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
+## The 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.
+- **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 naming a doc are the same object; the pointer's *wording*, not its target, decides 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.
+- **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.
-- **Completion criteria** — the clarity and demand of each step's done-condition, and the **legwork** it drives; the defence against **premature completion**.
+- **Completion criteria** — the clarity and demand of each step's done-condition, and the **legwork** that demand 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.
+- **Leading words** — a compact concept already in the model's pretraining (*tight*, *red*, *tracer bullet*) that the agent thinks with while running the document. It anchors twice: execution in the body, invocation in the pointer.
-- **Pruning** — single source of truth, relevance, and the no-op test applied sentence by sentence, against **sediment** and **sprawl**. Single source of truth reaches past the document into the environment: a doc restating what's already in `package.json`, a config file, or `--help` output is a **cache** of a lookup that was never expensive, and it's the copy that goes stale. Cache what the agent can't find by looking — the unwritten convention, the reason behind a choice.
+- **Pruning** — single source of truth, relevance, and the no-op test applied sentence by sentence, against **duplication**, **sediment** and **sprawl**.
+
+## Common questions
+
+**Where did `/writing-great-skills` go?**
+It is this skill, renamed in v1.1. Practitioners were already pointing it at `AGENTS.md`, docs, specs, tickets and runtime prompts long before the name caught up; structure, leading words and pruning turn out to be the craft of any text an agent reads. There is no alias — reinstall under the new name.
+
+**"Writing for agents" — so the agent does the writing?**
+The other way round. You are the author; the agent is the reader. That is the whole difficulty of the genre: you are writing for a reader who has already read everything, so explanation is waste and precision is the entire job.
+
+**Can't I just ask the agent to write it for me?**
+You can, and it will produce something verbose. Left alone the model explains what it already knows, and it will not apply the no-op test or reach for a leading word on its own. Use the reference on the draft — a review pass is where most of its value lands.
+
+**I asked an agent to trim a document and it cut the functionality.**
+Agents told to "streamline" optimise for length, because length is the thing they can see. The no-op test is behavioural, not aesthetic: delete the line and ask whether the agent's behaviour changed. When a sentence fails, delete the whole sentence rather than trim words from it — and settle a disagreement about it by running the document, not by arguing.
+
+**How do I know when it's done?**
+When it works, and you can no longer find duplication, sediment or no-ops. There is no automated eval here; the check is a manual run plus the failure-mode vocabulary as a diagnostic. When a document misbehaves, that vocabulary is also the repair kit — name the failure mode first, then fix that.
+
+**Should this live in `CLAUDE.md` or somewhere else?**
+Ask which load you want to pay. `CLAUDE.md` loads into every session unconditionally; material behind a pointer costs only the pointer's own line until it fires. Anything that applies in one context out of ten is paying context load the nine other times.
+
+**Do I need to rewrite my documents for each new model?**
+Mostly no, and over-fitting to one model is its own trap. Updating for a new model is usually another no-op pass rather than a rewrite.
+
+**My skill only works on the exact task I built it from.**
+The common route — do the work once, then have the agent write it up as a skill — over-indexes on that one run, and the exemplars come out too specific. Keep the run as evidence, then abstract deliberately: strip what belonged to that repo and those files, and write for the class of task.
+
+**English isn't my first language. Do I lose the leading-word advantage?**
+No — finding the word that packs the most behaviour into the fewest tokens is work the reference does for you. It is one of the things it is for.
+
+## It's working if
+
+- The document gets shorter as it gets better, and you are surprised how little is left.
+- You can point at a leading word and watch it doing work in more than one place.
+- Nothing is stated twice, in any form. Duplication is the most reliable sign a document was never tested.
+- Reference that only one branch needs sits behind a pointer rather than in the main file.
 
 ## 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.
+This is a reach-for-it-anytime standalone reference. It has no neighbour in the chain because it sits underneath the whole set rather than beside any one skill: every skill here was written against it, and the documents the other skills leave behind — a `CONTEXT.md` and its ADRs, a spec, a ticket — are exactly the text it governs once an agent has to read them. 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.