Documentation writer
Draft or rewrite one Box documentation page in the voice of
voice-guide.md.
Inputs
- Topic: what the page covers. Required.
- Content type: tutorial, how-to, reference, or explanation. Classify it in Step 1 if the user
doesn't give it.
- Target file: the path in
docs/user/ or docs/design/, if known.
- Existing content: the page to rewrite.
Process
Step 1: Place and classify
- Read
voice-guide.md and
docs/design/terminology.md.
- Ask the placement question: does the reader need this page to use Box, or to trust or change
Box? That picks
docs/user/ or docs/design/.
- Classify the content type. A page in
docs/design/ is an explanation.
- Stop if the page belongs to another owner:
decisions.md (the kd skill), terminology.md, or
tenets.md (only when the user asks).
- Read the README of the guide, and each page the new page links to or replaces.
Step 2: Gather the facts
Read the code on current main before you write about it.
- For each claim you expect to make, find the code that implements it and the test that pins it.
- For a design page, find each relevant entry in
docs/design/decisions.md and note its anchor.
- For a user page, find the parser that owns each key, verb, or action.
- Note every place where the terminology lock disagrees with what the code, the binaries, or
decisions.md call something.
Write down what you can't find: it goes to Tier 3 of
claim-verification.md, not onto the page.
Step 3: Sort the facts
You'll have far more than the page needs. Write a fact sheet to .agents/drafts/<page>-facts.md
that puts each fact in one of three piles:
- This page. It's at the page's altitude and the reader needs it here.
- Another page. It belongs to a sibling topic. It gets one clause and a link at most.
- Nowhere. An implementation detail that no reader of either page needs.
Expect most facts to land outside "this page".
Step 4: Outline
Start from the skeleton for the subject in
page-templates.md. A page about several parts gets one
section per part. Read the outline for scope creep and for detail that belongs to another page.
Show the outline to the user before you draft when the page is new, or when the outline changes the
structure of an existing page. Raise each terminology clash from Step 2 at the same time.
Step 5: Draft
- Each section opens with what the reader needs first (Layer 2).
- Use the register for the content type (Layer 3).
- Read each paragraph aloud as you go. Rewrite any sentence a person wouldn't say.
- User guide: describe what is, and explain why only when the reason changes the operator's action.
- Design guide: keep each claim within what its test pins, name no test, and link each decision by
anchor.
- Examples are complete, realistic, and one concept per block, with the output below the command.
- Diagrams show the main path only.
Step 6: Verify
Follow claim-verification.md for each claim and each
example. Don't skip this step. Remove each claim you can't verify, and report it.
Step 7: Cut
Cut by altitude, not by a percentage. Look first for detail that belongs to another page, then for
a list said twice, then for sentences that restate the one before. Keep what this page's reader
needs. Most of the quality comes from this step.
Step 8: Check
Run the mechanical check and clear or justify each hit:
.agents/skills/docs-reviewer/check-prose.sh <target-file>
Compile each Mermaid block with mmdc.
Step 9: Review
Run the docs-reviewer skill on the draft in a fresh context. Fix its findings, then run it again
until the verdict is "Ship it".
Step 10: Link the page
Add one row for a new page to the README.md of its guide. Remove the page from the "still to
come" list in docs/design/README.md if it's there.
Output
- The page, written to the target file.
- A short note on the content type and each editorial choice.
- Each claim you left out because you couldn't verify it, with the symbol and the tier that failed.
- Open questions for the user: terminology, scope, and accuracy. When no user is in the loop
(another agent ran this skill), this list replaces asking.
- Each
decisions.md entry that the code contradicts. Report it, and don't edit it: the kd
skill owns that file.
In rewrite mode, also report:
- Each claim in the original that current
main contradicts, as its own list, so the author can
fix the original even if they don't take the rewrite.
- Whether the row for the page in its guide's
README.md needs new wording for the new outline.
What this skill doesn't do
- Commit, push, or open a pull request. Follow the commit flow in
AGENTS.md when the user asks.
- Write an entry in
decisions.md. That's the kd skill.
- Add or change a term in the terminology lock without the user's approval.
- Change code to agree with a page.
Gotchas
- A design page isn't a decision entry. It explains how the parts fit together for a reader who
wasn't there. Summarize a decision and link its anchor. Don't copy the argument.
- A command and its binary can have different names. Check what ships before you name one.
--all-features is required when you run a test to verify a claim. Without it, some suites
are skipped and report success.- The first draft carries detail from other pages. Always.