Documentation API Reference
Overview
Use this skill to produce API references that enable clients to integrate correctly without reverse engineering source code.
Scope Boundaries
- Use this skill when the task matches the trigger condition described in
description. - Do not use this skill when the primary task falls outside this skill's domain.
Shared References
- Quality gates:
references/api-doc-quality-gates.md
Templates And Assets
- API reference template:
assets/api-reference-template.md
- Error catalog template:
assets/api-error-catalog-template.md
Inputs To Gather
- Current API contracts/specs and change diff.
- Authentication/authorization requirements.
- Request/response schemas, status codes, and error semantics.
- Versioning/deprecation policy.
Deliverables
- Endpoint/operation reference with examples.
- Error code and retryability guidance.
- Version/deprecation notes and migration hints.
- Known limits and behavioral caveats.
Quick Example Coverage Checklist
- Auth method and required headers.
- Request params/body schema with constraints.
- Success response + failure responses.
- Rate limits/idempotency behavior.
- Example curl/request/response snippets.
Quality Standard
- Doc content matches actual contract behavior.
- Required fields/constraints are explicit.
- Error behavior is actionable for client developers.
- Examples are realistic and syntactically valid.
Workflow
- Diff contract changes and identify impacted sections.
- Update operation docs with schema and behavior details using
assets/api-reference-template.md. - Add/refresh example requests and responses, including error mapping in
assets/api-error-catalog-template.md. - Validate consistency against source/spec with
references/api-doc-quality-gates.md. - Publish with migration notes where applicable.
Failure Conditions
- Stop when docs diverge from implemented contract.
- Stop when error semantics are undocumented for critical paths.
- Escalate when breaking changes lack migration guidance.