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/ordocs/design/, if known. - Existing content: the page to rewrite.
Wording-only rewrites
Use this path when the request changes prose alone, including a page in docs/dev/.
For new content or factual corrections, use the process below.
- Save the original text or record its commit and path. Read the voice guide and terminology.
- Apply the sentence rules in Layers 4 and 5. Preserve the original assertions and protected text as required by Preserve meaning. Keep the existing structure. Report suspected factual errors separately; a wording edit does not authorize correcting or deleting them.
- Compare every changed paragraph with the original. Run Step 8, check local links, and compare code blocks and anchors with the baseline.
- Run Step 9 with the original and draft. Finish when every assertion is preserved, each style finding is fixed or justified, and the independent reviewer returns "Ship it". Report any unresolved question that prevents a safe rewrite as incomplete work.
This path checks wording and preservation of meaning. It does not replace a factual audit.
Process
Step 1: Place and classify
- Read
voice-guide.mdanddocs/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/ordocs/design/. - Classify the content type. A page in
docs/design/is an explanation. - Stop if the page belongs to another owner:
decisions.md(thekdskill),terminology.md, ortenets.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.mdand 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.mdcall 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.
- Apply the voice guide's sentence rules in Layer 4 while drafting.
- 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: Edit
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. Apply the voice guide's self-check to every paragraph. Finish this step when every style finding is fixed or justified.
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".
For a rewrite, give the reviewer the original commit and path or saved text, the draft, and the
requested scope. It must compare meaning as well as style.
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.mdentry that the code contradicts. Report it, and don't edit it: thekdskill owns that file.
In rewrite mode, also report:
- Each claim in the original that current
maincontradicts, 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.mdneeds new wording for the new outline. - The original used for comparison, the reviewer verdict, and any unresolved questions. For a wording-only rewrite, report suspected factual errors without claiming a factual audit.
What this skill doesn't do
- Commit, push, or open a pull request. Follow the commit flow in
AGENTS.mdwhen the user asks. - Write an entry in
decisions.md. That's thekdskill. - 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-featuresis 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.