Reference writer
Purpose
Write technical reference that describes the machinery accurately, neutrally, and in a predictable structure.
Reference is for truth, certainty, and lookup while working.
When to use
Use this skill when the user asks for:
- •API docs
- •CLI command docs
- •configuration reference
- •parameter tables
- •schema docs
- •error code lists
- •version compatibility matrices
Do not use this skill for onboarding, tasks, or conceptual justification.
Core principles
- •describe and only describe
- •neutral, factual, and precise
- •structured around the thing being documented
- •complete enough for lookup
- •consistent in format and terminology
- •examples may illustrate, but must not turn into tutorials
Reader need
The reader asks:
- •What is this?
- •What are the valid inputs?
- •What does it return or affect?
- •What constraints, defaults, or limits apply?
- •What errors or warnings exist?
Structure patterns
Choose one consistent pattern per item type.
API endpoint
- •Name
- •Purpose
- •Method / path
- •Authentication
- •Parameters
- •Request body
- •Response body
- •Errors
- •Examples
- •Notes / limits
CLI command
- •Name
- •Synopsis
- •Arguments
- •Options
- •Defaults
- •Exit codes
- •Examples
- •Related commands
Config key
- •Name
- •Type
- •Default
- •Required or optional
- •Allowed values
- •Effect
- •Constraints
- •Example
Writing rules
- •avoid persuasion and opinion
- •avoid "best practice" unless clearly marked and linked elsewhere
- •avoid long narrative prose
- •use standard headings and repeated patterns
- •mirror the structure of the product where possible
- •make scanning easy
Examples policy
Examples are allowed when they clarify usage, but they must stay illustrative.
Good:
- •one short request example
- •one short response example
- •one command example showing syntax
Bad:
- •long walkthroughs
- •conceptual essays attached to every field
- •advice-heavy examples disguised as reference
Inputs to gather
- •product surface being documented
- •canonical names and terminology
- •exact signatures, defaults, constraints, limits
- •warnings and error cases
- •version and compatibility notes
- •examples that reflect reality
Output contract
Produce reference that:
- •is structured consistently
- •is easy to scan
- •states facts cleanly
- •separates facts from advice
- •can be trusted during active work
Anti-patterns to remove
- •recommendation language without a clear basis
- •tutorial prose
- •hidden defaults
- •vague types like "object" without schema details
- •missing constraints and edge cases
- •inconsistent naming across entries
Final self-check
Before returning, verify:
- •the document is neutral
- •the structure mirrors the product surface
- •repeated items use a repeated template
- •warnings and limits are explicit
- •examples illustrate rather than teach