| name | api-documentation |
| display_name | API Documentation |
| description | Creates or reviews API documentation for endpoints, SDKs, schemas, examples, errors, authentication, and compatibility behavior. |
| category | documentation |
| version | 1.0.0 |
| tags | ["api","documentation","openapi","sdk","examples"] |
| providers | ["claude-code","codex","copilot","openclaw","hermes-agent"] |
| author | agent-skills contributors |
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
- Identify the API surface: endpoints, methods, request bodies, response shapes, auth, errors, pagination, rate limits, and webhooks.
- Document the user goal before implementation details.
- Include accurate request and response examples with realistic values.
- Explain authentication, permissions, idempotency, retries, errors, and compatibility behavior.
- Check examples against code or schemas when possible.
- Add migration notes or versioning behavior if the API changed.
- 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.