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-page-23description: 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---56# Handbook Page Skill78The 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.910## What This Skill Produces1112- **The page** — task-first structure: the answer/steps up top, the context and edge cases below13- **The header block** — owner, status, last-reviewed — the trust signals14- **The worked example** — one realistic walkthrough, because examples teach what steps can't15- **The pointer habit** — the answer-with-the-link move that makes the page pay for itself1617## Required Inputs1819Ask 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 unread21- **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 head22- **The audience floor** — who arrives at this page and what they already know; the page assumes the floor and links the rest23- **Where the handbook lives** — and the naming/finding conventions there, so the page is discoverable by the words askers use2425## Framework: The Page Rules26271. **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.3233## Output Format3435# [Page title = the question, in the asker's words]3637*Owner: [name] · Status: active · Last reviewed: [date]*3839## The Answer40[Steps/decision table/link — first screen, task-complete]4142## Worked Example43[One realistic end-to-end case]4445## Edge Cases & Branches46[The "unless…" forks, explicit]4748## Background (for the curious)49[Why it works this way · history · related pages]5051## Quality Checks5253- [ ] The first screen completes the modal reader's task54- [ ] Branches from the oral version are visible forks, not omissions55- [ ] The worked example is realistic and end-to-end56- [ ] The header carries owner, status, and a real review date57- [ ] The pointer habit started on publication day — the next ask got the link5859## Anti-Patterns6061- [ ] Do not open with history — the reader is mid-task; context is the appendix62- [ ] Do not write the ideal process — document the real one, or the page and reality diverge and both lose trust63- [ ] Do not skip the example to save time — it's the half of the page that actually teaches64- [ ] Do not publish ownerless — orphan pages rot into the stale wiki that taught readers to re-ask humans65- [ ] Do not keep explaining orally — every post-page explanation is a vote against your own infrastructure
Mohit Aggarwal