Interpret MUST, MUST NOT, SHOULD, SHOULD NOT, MAY, etc. per RFC 2119.
-
Name the audience.
Before writing, know who you're writing for.
Technical is not specific enough — pick one:
- Newcomer — has never used this product.
Needs just enough context to evaluate or get started.
Will re-read.
- Returning power-user — has used it before, coming back for a specific detail.
Skims, looks up, leaves.
Values terseness.
- Operator mid-task — is running this thing in production and needs to make it do a thing now.
Values step-order and concrete identifiers.
- Developer integrating — is wiring this into their own code.
Values signatures, examples, failure modes.
Different audiences change everything — pacing, depth, what's assumed, what's spelled out.
If you can't tell from the page's location and surrounding pages, ask.
-
Identify the Diataxis quadrant(s).
Diataxis names four quadrants: tutorial, how-to, reference, explanation (see the chalk:voice skill).
Each page leans toward one at the top level; each sub-section within it may hit a different quadrant.
The test isn't "where does this page live?" — it's "what is this paragraph/section for?".
Before writing, decide:
- What quadrant is this page as a whole?
- What quadrant is each section?
Don't blur them.
A how-to section that drifts into explanation loses the reader mid-task; an explanation section that drifts into reference buries the mental model.
-
Discover project conventions.
Conventions differ between projects and this skill does not prescribe them.
Read the repo before writing.
In order of priority:
- A docs README (e.g.
docs/README.md) — if present, it's the authoritative style guide.
Follow it even where it disagrees with your defaults.
- A
CLAUDE.md at the repo root or in the docs directory.
- Existing sibling pages — match their shape (frontmatter, heading depth, changelog format, version-marker style, callout syntax, cross-link style).
- Recent commits and PRs touching docs — they show what's been landing.
Project-specific conventions you're looking for:
- Frontmatter shape (title, description, sidebar fields, etc.).
- Version markers — is there an inline marker convention like
(v2.1+)?
Does it go on headings, in code comments, both?
- Changelog blocks — does each page carry a
<details> changelog?
What's the format?
What counts as a transition vs. an additive feature?
- Callout style — Starlight
:::note / :::caution, MDX admonitions, plain blockquotes?
- Cross-link style — site-relative paths?
Anchors?
What's the house convention?
- Diagrams — inline D2, Mermaid, PNG assets?
Where the project has a convention, match it.
Where it doesn't, make a call and be consistent within the page.
-
Pull the "why" from the issue-graph neighbourhood.
Like chalk:commit, this skill draws motivation from upstream context.
Cast the net at least one hop beyond the immediately-tracked issue — a single issue rarely carries all the reasoning that ends up mattering on a docs page.
Read:
- The tracked chalk issue and its comments — the primary source.
- Related issues — parent, sub-issues, blocked-by, blocks.
See the "Issue Relationships" section of the main chalk skill; the one-hop graph surfaces operational context, rejected alternatives, and why-now that don't fit in any single issue.
The github agent's neighbourhood query is the cheapest way to pull this.
- The landing PR(s) — description and review discussion.
Review discussion in particular catches edge cases and invariants that only got clarified during review.
- The landing commit body(ies) — multi-commit PRs often have per-commit rationales the PR description glosses over.
For a feature that's touched multiple issues and PRs, read across them — contradictions between old and new thinking usually mark where the docs need the clearest framing.
These carry the why that isn't visible in the code — root causes, operational guarantees, invariants, rejected alternatives, real-world failure modes.
They noticeably improve the resulting docs.
Distil, don't copy.
A chalk comment is author-to-maintainer; a docs page is author-to-user.
The audience is different; the phrasing has to be too.
-
Apply the chalk voice.
Load the chalk:voice skill (via the Skill tool) for the Diataxis framing and universal principles, then apply the quadrant-specific voice to each section.
Don't restate those rules inline — they live in chalk:voice.
Line format: sentence-per-line.
A docs page is checked into the repo and reviewed as a git diff, so put each sentence on its own line — it keeps diffs minimal (a one-sentence edit touches one line) and the structure scannable in source.
-
Ask clarifying questions — don't invent.
The main chalk skill's "Understanding Why" rule applies here: if the why isn't obvious from the issue graph, the PR, or the conversation, ask.
A one-sentence answer from the user beats a fabricated rationale every time, and fabricated rationales in docs are particularly corrosive — they look authoritative and they rot silently.
Ask when:
- The audience isn't clear from the page context.
- The quadrant isn't clear from the request ("document X" is ambiguous — tutorial, how-to, reference, or explainer?).
- The why isn't clear from the issue graph / PR / commits, and the section needs one.
Don't make it up.
- A project convention is missing and the call has material effect on the output (e.g. no changelog-format precedent and the change is a transition worth recording).
