api-documentation

name	api-documentation
description	Creates or reviews API documentation for endpoints, SDKs, schemas, examples, errors, authentication, and compatibility behavior.

API Documentation

Use this skill when writing, reviewing, or improving documentation for HTTP APIs, SDK methods, schemas, webhooks, or integrations.

Inputs

• API code, route definitions, OpenAPI schema, SDK source, docs draft, examples, or user workflow
• Audience: external developers, internal teams, partners, or operators

Steps

1. Identify the API surface: endpoints, methods, request bodies, response shapes, auth, errors, pagination, rate limits, and webhooks.
2. Document the user goal before implementation details.
3. Include accurate request and response examples with realistic values.
4. Explain authentication, permissions, idempotency, retries, errors, and compatibility behavior.
5. Check examples against code or schemas when possible.
6. Add migration notes or versioning behavior if the API changed.
7. Remove ambiguous wording and hidden assumptions.

Output

Return:

• API documentation draft or review notes
• Missing fields or behaviors
• Example requests and responses
• Error and edge-case coverage
• Compatibility or migration notes

Guidelines

• Do not fabricate undocumented behavior. Mark assumptions clearly.
• Prefer examples that users can adapt directly.
• Keep docs aligned with source code and schemas.