edkuksa/skills
1
0
Fork 0
mirror of https://github.com/mattpocock/skills.git synced 2026-09-13 18:55:52 +07:00
Code Issues Packages Projects Releases Wiki Activity

docs: act on pilot feedback — branch tables, wayfinder, deader prose

Browse Source 
Encode a new rule in writing-docs.md: a multi-way branch goes in a table
or a list, never a paragraph the reader has to read in full.

- to-spec: trigger becomes a table; stop implying the tracker must be
  remote, since local markdown is supported out of the box.
- prototype: wayfinder is the largest consumer (prototype is one of its
  four decision-ticket types); the ask-matt handoff round trip is
  demoted to one line.
- handoff: trigger becomes a table; dead prose throughout.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Matt Pocock
2026-08-05 12:34:54 +01:00
co-authored by Claude Opus 5
parent 8ffcd52e4e
commit 14780a1f8d
4 changed files with 35 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/writing-docs.md
+2
View File
@@ -73,6 +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.
- **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.
## Done when
@@ -84,6 +85,7 @@ Always present. Situate the skill in the system in a sentence or two:
- `## 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.
- The middle surfaces the leading word.
- Every multi-way branch is a table or a list, not a paragraph the reader has to read in full.
- The hunt for real questions ran — the wiki, the issues, the changelog — and `## Common questions` is sized to what it found, not padded to match a richer skill's page.
- Every `## It's working if` bullet is checkable without opening `SKILL.md`.
- The sections appear in the template's order.