api-documentation
API Documentation: OpenAPI/Swagger specs, Postman collections, API reference patterns, and client SDK docs
Profile →npx skills add cosmicstack-labs/mercury-agent-skills --skill api-documentation --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
What it does
Documents APIs and their documentation workflow, focusing on OpenAPI/Swagger specs, Postman collections, API reference patterns, and client SDK docs.
How it works
- Emphasizes that the OpenAPI/Swagger specification is the single source of truth for the API and that docs, client libraries, and tests should be generated from it.
- Stresses documenting authentication, error handling, rate limits, pagination, and workflows to improve developer experience.
- Requires every endpoint to include a runnable example with both success and error responses.
- Calls for versioning, deprecation notices, and migration guides.
- Presents an API Documentation Maturity Model with levels from Minimal to Exemplary and specifies a target minimum level for internal/public APIs.
- Provides actionable guidance on an OpenAPI 3.0/3.1 structure and includes sample configuration snippets for Redocly and Spectral linting.
- Includes a section on Authentication Documentation covering API Key Auth and OAuth 2.0, plus an Authentication Guide with examples in curl, Python, and JavaScript.
- Outlines standard Error Response Patterns and an example error payload schema.
When to use it
Use when documenting an API’s specification-driven docs and its authentication, error handling, and SDK generation workflows.
What it can touch
Linter and tooling guidance for OpenAPI specs (Redocly CLI, Spectral) is included for validating and building docs.
Caveats
No licensing or explicit risk is stated beyond general guidance; relies on OpenAPI/OpenAPI 3.0+ tooling and standard schemas. Specific limitations or caveats are not enumerated beyond the provided structure.
# API Documentation Document APIs that developers love to integrate with — complete, accurate, and testable from the spec itself. ## Core Principles ### 1. The Spec Is the Source of Truth Your OpenAPI/Swagger specification should be the single source of truth for your API. Generate documentation, client libraries, and test suites from it. Never let docs drift from the spec. ### 2. Document the Experience, Not Just the Endpoints Good API docs don't just list endpoints — they explain authentication, error handling, rate limits, pagination, and common workflows. Developer experience is documentation. ### 3. Every Endpoint Needs a Runnable Example Every API endpoint should have at least one complete request/response example that a developer can copy, paste, and run. Show both success and error responses. ### 4. Version Everything, Deprecate Gracefully APIs evolve. Documentation must clearly indicate which versions are active, deprecated, and sunset. Give consumers time to migrate with clear migration guides. --- ## API Documentation Maturity Model | Level | Completeness | Accuracy | Interactivity | Versioning | Client Generation | |-------|-------------|----------|---------------|-----
- Core Principles
- 1. The Spec Is the Source of Truth
- 2. Document the Experience, Not Just the Endpoints
- 3. Every Endpoint Needs a Runnable Example
- 4. Version Everything, Deprecate Gracefully
- API Documentation Maturity Model
- Actionable Guidance
- OpenAPI 3.0/3.1 Specification Structure
- Linting and Validating OpenAPI Specs
- Authentication Documentation
- Error Response Patterns
- Rate Limiting Documentation
- Postman Collection Structure
- SDK Documentation Patterns
Install Redocly CLI npm install -g @redocly/cli Lint your spec (catches common issues) npx @redocly/cli lint openapi.yaml Lint with a specific ruleset npx @redocly/cli lint openapi.yaml \ Validate against OpenAPI 3.0 schema npx @redocly/cli lint --format openapi-3.0 Generate beautiful API reference HTML npx @redocly/cli build-docs openapi.yaml \
What does the api-documentation skill do?
API Documentation: OpenAPI/Swagger specs, Postman collections, API reference patterns, and client SDK docs
How do I install it?
Run `npx skills add cosmicstack-labs/mercury-agent-skills --skill api-documentation --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From cosmicstack-labs/mercury-agent-skills, a repository with 364 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.