# Docs Writer

> Draft or rewrite a Box page in docs/user/, docs/design/, or a crate README. Also use for wording-only rewrites in docs/dev/. Use for new documentation, wording cleanup, or corrections after a docs audit. Use kd for decision entries, spec for local specs, and explore for research notes.

- Skill: `strands-agents/docs-writer-2` (Agent Skill)
- Install (CLI): `npx get-skill add strands-agents/docs-writer-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/strands-agents/docs-writer-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: strands-agents (https://skillmd.com/u/strands-agents)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/strands-agents/docs-writer-2

---


# Documentation writer

Draft or rewrite one Box documentation page in the voice of
[`voice-guide.md`](../../references/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.

## 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.

1. Save the original text or record its commit and path. Read the voice guide and
   [terminology](../../../docs/design/terminology.md).
2. Apply the sentence rules in Layers 4 and 5. Preserve the original assertions and protected
   text as required by [Preserve meaning](../../references/voice-guide.md#preserve-meaning).
   Keep the existing structure. Report suspected factual errors separately; a wording edit does
   not authorize correcting or deleting them.
3. Compare every changed paragraph with the original. Run Step 8, check local links, and compare
   code blocks and anchors with the baseline.
4. 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

1. Read [`voice-guide.md`](../../references/voice-guide.md) and
   [`docs/design/terminology.md`](../../../docs/design/terminology.md).
2. 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/`.
3. Classify the content type. A page in `docs/design/` is an explanation.
4. Stop if the page belongs to another owner: `decisions.md` (the `kd` skill), `terminology.md`, or
   `tenets.md` (only when the user asks).
5. 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`](../../references/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`](../../references/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`](../../references/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](../../references/voice-guide.md#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:

```sh
.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

1. The page, written to the target file.
2. A short note on the content type and each editorial choice.
3. Each claim you left out because you couldn't verify it, with the symbol and the tier that failed.
4. 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.
5. 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:

6. 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.
7. Whether the row for the page in its guide's `README.md` needs new wording for the new outline.
8. 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.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.

