API Reference Writer

Reference documentation is a contract written in the reader's language: every endpoint, every field, every error, exactly as the service behaves — not as the team remembers it. This skill produces API reference material from the source of truth (handlers, route tables, schemas, serializers), verifies claims against code rather than tribal memory, and writes entries a developer can integrate against without ever opening the implementation.

When to use this skill

• An API exists but its documentation is missing, stale, or scattered across chat threads
• A new endpoint is shipping and needs reference docs as part of the change
• Consumers keep asking questions the docs should answer (auth, pagination, error shapes)
• Generating or repairing a machine-readable API description alongside the human-readable docs

Workflow

1. Locate the source of truth: route definitions, request and response schemas, validation rules, serializers, auth middleware. Documentation is transcription plus judgment — find what to transcribe before exercising judgment.
2. Inventory the surface: every route, method, and status code actually emitted. Diff this inventory against the existing docs, and lead with the endpoints that are present-but-undocumented and documented-but-gone.
3. Document the shared contract once, at the top: base URL structure, authentication mechanics, content types, pagination convention, rate-limit behavior, and the error envelope. Endpoint entries then reference these instead of restating them slightly differently each time — drift between restatements is how docs learn to lie.
4. Write each endpoint entry to a fixed shape (below). For every field: type, required or optional, constraints, and — the part everyone skips — its meaning. "The reconciliation cursor from the previous page" documents; "the cursor field" merely decorates.
5. Document errors as behavior, not as a table of codes: what the caller did to earn each error, what the response body looks like, and whether retrying helps. The unhappy path is where integrators live during their worst week; write for that week.
6. Verify every example against the running service or its test suite. Examples must round-trip: the request shown produces the response shown. An unverified example is a bug with nice formatting.
7. Finish with a freshness anchor: record the commit or version the docs describe, so the next writer diffs from a known point instead of re-auditing the world.

Output format

Per endpoint:

### <METHOD> /path/{param}
<one sentence: what it does and when a caller wants it>

Auth: <requirement>   Idempotent: <yes/no>
Parameters (path, query, body):
| name | type | required | meaning + constraints |

Response 200: <shape, with field meanings>
Errors: <status — trigger condition, body shape, retry guidance>
Example: <verified request/response pair>

Quality bar

• Zero undocumented fields in any documented response — partial field lists are worse than absence, because they read as complete.
• Every example verified against the actual service, and the method stated (test suite, live call, recorded fixture).
• Optionality and nullability stated separately: "may be omitted" and "may be null" are different promises.
• Deprecations marked with sunset guidance and a replacement, never silently retained.
• The finish line: a reader integrating from scratch never needs to open the server code.