Handbook Page Skill
The handbook page is the highest-leverage document in team life: written once, it answers a question forever — but only if it's written answer-shaped. Most wiki pages are essay-shaped (history, context, philosophy, and eventually, maybe, the steps), while their readers arrive task-shaped ("how do I request access?"). The working page leads with the task, keeps context below the fold, carries the doc-versioning-discipline header (owner, status, last-reviewed), includes one worked example — and then gets used: every repeat question gets answered with the link, because a handbook nobody points to is a diary.
What This Skill Produces
- The page — task-first structure: the answer/steps up top, the context and edge cases below
- The header block — owner, status, last-reviewed — the trust signals
- The worked example — one realistic walkthrough, because examples teach what steps can't
- The pointer habit — the answer-with-the-link move that makes the page pay for itself
Required Inputs
Ask for these if not provided:
- The repeated question — the actual thing people keep asking (verbatim asks beat topic descriptions — the faq-builder mining logic); pages written for imagined questions join the unread
- The answer, from the explainer — the current oral version, including the caveats and the "oh but if it's a contractor it's different" branches that live only in the explainer's head
- The audience floor — who arrives at this page and what they already know; the page assumes the floor and links the rest
- Where the handbook lives — and the naming/finding conventions there, so the page is discoverable by the words askers use
Framework: The Page Rules
- Answer-shaped, not essay-shaped: the reader's task is satisfied in the first screen — the steps, the link, the form, the decision table. History and rationale live below under "Background," read by the curious minority. The test: the modal reader leaves within ninety seconds, satisfied.
- Steps at do-this grain with branches explicit: the oral version's "oh, unless…" branches become visible forks (runbook-writer grain for anything procedural) — the page must beat asking-a-human, and humans handle branches; pages that don't send readers back to the human.
- The worked example is half the teaching: one realistic case walked end-to-end ("requesting prod access for a new analyst: …") — readers pattern-match from examples faster than they parse instructions, and the example disambiguates everything the steps left abstract.
- The header makes it trustworthy: owner (who answers when the page is wrong), status, last-reviewed — without these, readers who've been burned by stale wikis re-ask the human anyway, and the page's ROI dies. The owner's review is 5 minutes on the heartbeat cadence.
- The pointer habit is the payoff loop: from publication day, every repeat ask gets "here you go: [link] — tell me if anything's unclear" — which (a) delivers the answer, (b) trains the link-first reflex, and (c) field-tests the page (every "the page didn't cover my case" is an edit, same day). Explaining orally after the page exists is paying twice for the same knowledge.
Output Format
[Page title = the question, in the asker's words]
Owner: [name] · Status: active · Last reviewed: [date]
The Answer
[Steps/decision table/link — first screen, task-complete]
Worked Example
[One realistic end-to-end case]
Edge Cases & Branches
[The "unless…" forks, explicit]
Background (for the curious)
[Why it works this way · history · related pages]
Quality Checks
Anti-Patterns
1---2name: handbook-page3description: Write the handbook page that ends the repeated explanation — the answer-shaped structure (task-first, context second), the ownership and freshness header, and the write-once-point-forever discipline that turns tribal knowledge into infrastructure. Use when asked document how we do X, write the wiki page for this process, I explain this every month, or make this knowledge survive me. Produces the page with task-first structure, the header block, the worked example, and the pointer habit.4---5
6# Handbook Page Skill
7
8The handbook page is the highest-leverage document in team life: written once, it answers a question *forever* — but only if it's written answer-shaped. Most wiki pages are essay-shaped (history, context, philosophy, and eventually, maybe, the steps), while their readers arrive task-shaped ("how do I request access?"). The working page leads with the task, keeps context below the fold, carries the [doc-versioning-discipline](../doc-versioning-discipline/SKILL.md) header (owner, status, last-reviewed), includes one worked example — and then gets *used*: every repeat question gets answered with the link, because a handbook nobody points to is a diary.
9
10## What This Skill Produces
11
12- **The page** — task-first structure: the answer/steps up top, the context and edge cases below
13- **The header block** — owner, status, last-reviewed — the trust signals
14- **The worked example** — one realistic walkthrough, because examples teach what steps can't
15- **The pointer habit** — the answer-with-the-link move that makes the page pay for itself
16
17## Required Inputs
18
19Ask for these if not provided:
20- **The repeated question** — the actual thing people keep asking (verbatim asks beat topic descriptions — the [faq-builder](../faq-builder/SKILL.md) mining logic); pages written for imagined questions join the unread
21- **The answer, from the explainer** — the current oral version, including the caveats and the "oh but if it's a contractor it's different" branches that live only in the explainer's head
22- **The audience floor** — who arrives at this page and what they already know; the page assumes the floor and links the rest
23- **Where the handbook lives** — and the naming/finding conventions there, so the page is discoverable by the words askers use
24
25## Framework: The Page Rules
26
271. **Answer-shaped, not essay-shaped:** the reader's task is satisfied in the first screen — the steps, the link, the form, the decision table. History and rationale live below under "Background," read by the curious minority. The test: the modal reader leaves within ninety seconds, satisfied.
282. **Steps at do-this grain with branches explicit:** the oral version's "oh, unless…" branches become visible forks ([runbook-writer](../runbook-writer/SKILL.md) grain for anything procedural) — the page must beat asking-a-human, and humans handle branches; pages that don't send readers back to the human.
293. **The worked example is half the teaching:** one realistic case walked end-to-end ("requesting prod access for a new analyst: …") — readers pattern-match from examples faster than they parse instructions, and the example disambiguates everything the steps left abstract.
304. **The header makes it trustworthy:** owner (who answers when the page is wrong), status, last-reviewed — without these, readers who've been burned by stale wikis re-ask the human anyway, and the page's ROI dies. The owner's review is 5 minutes on the heartbeat cadence.
315. **The pointer habit is the payoff loop:** from publication day, every repeat ask gets "here you go: [link] — tell me if anything's unclear" — which (a) delivers the answer, (b) trains the link-first reflex, and (c) field-tests the page (every "the page didn't cover my case" is an edit, same day). Explaining orally *after* the page exists is paying twice for the same knowledge.
32
33## Output Format
34
35# [Page title = the question, in the asker's words]
36
37*Owner: [name] · Status: active · Last reviewed: [date]*
38
39## The Answer
40[Steps/decision table/link — first screen, task-complete]
41
42## Worked Example
43[One realistic end-to-end case]
44
45## Edge Cases & Branches
46[The "unless…" forks, explicit]
47
48## Background (for the curious)
49[Why it works this way · history · related pages]
50
51## Quality Checks
52
53- [ ] The first screen completes the modal reader's task
54- [ ] Branches from the oral version are visible forks, not omissions
55- [ ] The worked example is realistic and end-to-end
56- [ ] The header carries owner, status, and a real review date
57- [ ] The pointer habit started on publication day — the next ask got the link
58
59## Anti-Patterns
60
61- [ ] Do not open with history — the reader is mid-task; context is the appendix
62- [ ] Do not write the ideal process — document the real one, or the page and reality diverge and both lose trust
63- [ ] Do not skip the example to save time — it's the half of the page that actually teaches
64- [ ] Do not publish ownerless — orphan pages rot into the stale wiki that taught readers to re-ask humans
65- [ ] Do not keep explaining orally — every post-page explanation is a vote against your own infrastructure
Mohit Aggarwal