mirror of
https://github.com/mattpocock/skills.git
synced 2026-09-12 18:38:06 +07:00
docs: write the pages in neutral third person
The docs pages carried 36 attributed opinions — "Matt's own answer", "his position is", quoted replies from the author. A page is a technical document about a skill, so the substance of each finding stays and the attribution goes: "the fix is a direct instruction: …", "the split comes down to session count". Quotes from *users* stay, anonymous as they already were — those are evidence about the skill in the wild rather than the author's view. Records the rule in .agents/writing-docs.md so new pages don't reintroduce it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5
parent
0986ebaf5d
commit
86b07d15da
@@ -72,6 +72,7 @@ Always present. Situate the skill in the system in a sentence or two:
|
||||
## Conventions
|
||||
|
||||
- Explain the **why**, not the process. The page orients and situates the skill; it never reproduces the `SKILL.md` steps or template dumps — a human choosing a tool does not need the runbook.
|
||||
- **Never name the author.** The page is a technical document, not a record of who said what. "Matt says", "Matt's own answer", "his position is", a quoted reply — all of it goes. A finding from the question hunt is worth keeping; its attribution is not. State the substance as a plain claim about the skill ("the fix is a direct instruction: …", "the split comes down to session count") and drop the frame. The reader is deciding whether to use a tool; an opinion carries the same weight either way, and an attributed one dates as soon as the position moves. Quoting a *user* stays fine — "one user reported …" is evidence about the skill in the wild, and stays anonymous.
|
||||
- Use the skill's **leading words** (_seam_, _deep module_, _tracer bullet_) so the page and the skill speak one language.
|
||||
- **Use the [AI Coding Dictionary](https://www.aihero.dev/ai-coding-dictionary)'s term where one exists, and link its first use on the page.** The dictionary is the house vocabulary for AI coding — _context window_, _subagent_, _harness_, _primary source_, _agent mode_. Prefer its word over a synonym you invent. Link the first occurrence of each term to `https://www.aihero.dev/ai-coding-dictionary/<slug>` (the slug is the term lowercased with non-alphanumerics as hyphens: _context window_ → `context-window`), and leave every later occurrence unlinked. Link only where the word carries the dictionary's sense — a domain *model*, background *context* or an auth *token* is a different word that happens to match. Never link inside a heading, a code span, or an existing link, and never link a word that names a skill in this repo rather than the concept. For the full term list, read `~/repos/ai/ai-coding-dictionary/dictionary/` if it exists on this machine — one file per term, the filename *is* the term — and otherwise [mattpocock/dictionary-of-ai-coding](https://github.com/mattpocock/dictionary-of-ai-coding), which is the source of truth either way.
|
||||
- **Branches go in a table or a list, never in a paragraph.** Where the page presents a choice — two artifacts the skill can produce, four situations that trigger it, five options at a boundary — the reader is scanning for the one row that matches their situation. A paragraph makes them read all of it to find out. A short markdown table (condition in the left column, what to do in the right) or a bulleted list gives it back in one glance. This applies wherever the branch appears, most often in `## When to reach for it` and the free-form middle.
|
||||
@@ -82,6 +83,7 @@ Always present. Situate the skill in the system in a sentence or two:
|
||||
- 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.
|
||||
- `## What it does` states the defining constraint, as plain prose rather than a labelled aside.
|
||||
- The page names no author and quotes no author — every claim stands on its own.
|
||||
- `## When to reach for it` states invocation mode and the trigger boundary.
|
||||
- `## Where it fits` names the role and links to `ask-matt`.
|
||||
- A prerequisite (workspace, prior setup, tooling) is stated where one exists, and the section is absent where none does.
|
||||
|
||||
Reference in New Issue
Block a user