API Docs Writer Skill

API documentation written by the developer who built the API is almost always incomplete — not because they do not care, but because they already know what everything does. This skill reads the code without that prior knowledge and documents what is actually there, not what was intended.

What the skill does

• Endpoint documentation. For each route: HTTP method, path, description, authentication requirements, and a plain-language explanation of what it does.
• Parameter tables. Query parameters, path parameters, and request body fields — name, type, required/optional, constraints, and description.
• Request/response schemas. JSON schema or plain-language description of the expected request body and the full response structure, including nested fields.
• Error codes. Every error response the endpoint can return, with the condition that triggers it.
• Code examples. Working curl commands and code snippets (in the language you specify) for the most common use cases.
• Authentication section. How to authenticate, what header or token to use, and how to obtain credentials.

How it works

1. Paste your route handlers. Drop in the code for one or more endpoints — the actual handler functions, not just the route definitions.
2. Specify the format. Markdown for a README, OpenAPI YAML, or plain prose — the skill adapts the output format.
3. First draft. Complete documentation for every endpoint in the pasted code.
4. Iteration. Ask to add an example, expand error codes, or write docs for additional endpoints.

How to use it

1. Click ⬇ Download this Claude Skill above.
2. Import through Claude Desktop (Customize → Skills → + → Create skill → Upload a skill) or drop into .claude/commands/. Full walkthrough in the import tutorial.
3. Invoke the skill:

   /api-docs-writer
   

   Or specify the format:

   /api-docs-writer Express REST API. Output as Markdown. Include curl examples for each endpoint.
   

---

Quick-start prompt (no download)

Write complete API documentation for the following route handlers.

For each endpoint, document:

• Method and path
• Description: what it does in plain language
• Authentication: required or not, how to pass credentials
• Parameters: path params, query params, and request body fields — name, type, required/optional, constraints, description
• Response: full schema of the success response with field descriptions
• Error responses: every error code this endpoint can return and what triggers it
• Example: a working curl command for the most common use case

Output format: [Markdown / OpenAPI YAML / plain text] Framework: [Express / FastAPI / Rails / etc.]

[paste route handler code here]

Tips:

• Paste all handlers for a resource together (e.g., all user endpoints at once) so the skill can produce consistent documentation across related routes.
• Ask for OpenAPI YAML output if you want machine-readable documentation that tools like Swagger UI can render.
• If your handlers use shared middleware for auth or validation, paste that too — the skill uses it to document the auth requirements and input constraints accurately.
• Ask for a "quick reference" section at the top after the full docs are done — a table of all endpoints with method, path, and a one-line description.

⚠ This skill has been tested and optimized for Claude. Results may vary with other AI assistants.