Help us improve
Share bugs, ideas, or general feedback.
From grimoire
Guides writing developer-friendly API reference documentation, endpoint descriptions, and SDK docs using OpenAPI 3.1 standards and best practices from Stripe/Google.
npx claudepluginhub jeffreytse/grimoire --plugin grimoireHow this skill is triggered — by the user, by Claude, or both
Slash command
/grimoire:write-api-documentationThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Produce accurate, developer-friendly API documentation that enables independent integration without support escalation.
Writes and improves API reference documentation, endpoint descriptions, and OpenAPI specifications following practices from Stripe, Twilio, and GitHub.
Generates API documentation from code, covering endpoints, parameters, request/response examples, authentication, error handling, and usage guidelines. Supports REST, GraphQL, and WebSocket APIs.
Transforms raw API specs, endpoint descriptions, or Postman collections into clean developer-facing documentation with endpoint summaries, parameters, request/response examples, and error codes.
Share bugs, ideas, or general feedback.
Produce accurate, developer-friendly API documentation that enables independent integration without support escalation.
Adopted by: Stripe (industry benchmark for API docs), Twilio, GitHub, AWS, and all major API-first companies; OpenAPI Specification is the de facto standard with 10,000+ public APIs documented; Google Developer Documentation Style Guide is used by 1,000+ Google products and widely adopted externally. Impact: Well-documented APIs reduce developer time-to-first-call by 60–80%; Stripe's docs are credited as a key factor in developer adoption that drove the company from $0 to $95B valuation. Why best: APIs are products; documentation is the UI. Bad docs mean developers integrate incorrectly, generate support tickets, or abandon the API.
Sources: Google Developer Documentation Style Guide; OpenAPI Specification 3.1 (OAI); Stripe API Documentation (reference benchmark); Redocly API documentation standards.
Document every endpoint with OpenAPI 3.1 — write a machine-readable OpenAPI spec first. Each endpoint needs: HTTP method, path, operationId, summary (one line), description, parameters, request body schema, response schemas for every status code.
Write a getting-started guide — before any reference docs, provide: authentication setup (with working code example), the simplest possible working request, expected response, and a "what next" path. Target time-to-first-successful-call under 15 minutes.
Document authentication explicitly — specify the auth scheme (API key, OAuth 2.0, JWT), where credentials go (header, query param, body), how to obtain credentials, and how to rotate or revoke them. Include a working curl example.
Write parameter descriptions that explain, not restate — bad: user_id: The user's ID. Good: user_id: Unique identifier of the user whose data to retrieve. Find this in the Users list or account settings.
Provide working code examples in multiple languages — include curl, Python, JavaScript/Node, and Ruby at minimum. Examples must be copy-paste runnable. Use real, syntactically correct values — not <your-value-here> placeholders.
Document all error responses — for every endpoint, list every non-200 status code with: HTTP status, error code string, human-readable message, what caused it, and how to fix it. This is the most under-documented aspect of most APIs.
Explain rate limits, pagination, and versioning — document: requests/second or requests/minute limits, pagination strategy (cursor, offset, page), API versioning scheme and deprecation policy, and how to request higher limits.
Add a changelog — every API change (new endpoint, new parameter, deprecation, breaking change) must appear in a dated changelog with migration guidance for breaking changes.
Test every code example — run every example in the documentation against the production API before publishing. Broken examples destroy developer trust immediately.
Implement feedback mechanisms — add inline "Was this helpful?" ratings, a GitHub link to suggest edits, and a support path. Review low-rated pages monthly.
error: "invalid_request" without explanation forces developers to contact support for every integration issue.user_id, userId, and userID in different endpoints creates integration errors and erodes trust.