From e7c34b7be51335d26ca58e22dd07bdc2146e0d49 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Wed, 5 Aug 2026 13:35:20 +0100 Subject: [PATCH] docs: point writing-docs at the local dictionary clone Mirrors how the personal wiki is referenced: read ~/repos/ai/ai-coding-dictionary/dictionary/ where it exists, and fall back to GitHub where it doesn't. Co-Authored-By: Claude Opus 5 (1M context) --- .agents/writing-docs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/writing-docs.md b/.agents/writing-docs.md index 33c651e..adf0676 100644 --- a/.agents/writing-docs.md +++ b/.agents/writing-docs.md @@ -73,7 +73,7 @@ Always present. Situate the skill in the system in a sentence or two: - 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. - 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/` (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. Source of truth: [mattpocock/dictionary-of-ai-coding](https://github.com/mattpocock/dictionary-of-ai-coding). +- **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/` (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. - Keep the page itself low-load. It is documentation *about* low-cognitive-load skills; furniture (spare headings, restated links) is the thing it is arguing against.