When to use this
- A new or changed endpoint needs reference documentation.
- Existing API docs don't match what the code actually does.
- Not for a public marketing-style API overview -- this is reference documentation: precise, complete, and derived from the implementation.
The skill file
Copy this verbatim. It's written in the SKILL.md format (YAML frontmatter + markdown instructions) that Claude Code, and increasingly other agent tools, read directly.
--- name: api-doc-generator description: Generate reference documentation for an API endpoint (or set of endpoints) by reading the actual handler implementation -- request/response schema, status codes, error cases, auth requirements -- not just the happy path. Use for new or changed endpoints. --- # API Doc Generator Read the handler code, not just its top-level comment -- error branches and validation logic are where real API docs usually go stale first. ## For each endpoint, document - **Method + path**, including path/query parameters and their types. - **Auth requirement**: what's needed (and what scope/permission, if the system has granular permissions). - **Request body schema**: required vs. optional fields, types, and any validation constraints visible in the code (max length, allowed enum values, format). - **Response schema** for the success case, with the actual status code used (200 vs 201 vs 204 -- check, don't assume). - **Error responses**: every distinct error status code the handler can return, what triggers each, and the error body shape. - **Rate limits / idempotency notes**, if the implementation has them. ## Process 1. Read the full handler, including every early-return and thrown error, not just the final success response. 2. Check middleware for auth/validation that isn't visible in the handler body itself. 3. Cross-check against any existing request/response type definitions (schema files, DTOs) as the source of truth for field names/types. ## Output Match this project's existing API doc format (OpenAPI/Swagger fragment, markdown reference doc, or inline doc comments) if one exists; otherwise a clear markdown reference block per endpoint.
Installing it elsewhere
The frontmatter/body split above is Claude Code's convention. Here's how to carry the same instructions into other tools:
Save the file below verbatim (frontmatter included) at that path, project-local or in ~/.claude/skills/ for a user-level skill. Claude Code loads the name/description pair to decide when to pull it in, or you invoke it directly as /api-doc-generator.
Convert the YAML frontmatter to Cursor's rule format (description, globs, alwaysApply: false) and keep the markdown body as the rule content. Cursor surfaces it by description match, same idea as Claude Code's auto-load.
Codex CLI (and increasingly other agentic CLIs) read AGENTS.md at the repo root as always-on instructions. Paste the markdown body under a heading like ## {title}; for GitHub Copilot's coding agent, the equivalent file is .github/copilot-instructions.md.
Append the markdown body to .windsurfrules at the repo root. Windsurf treats the whole file as always-on context, so keep only the instructions you want applied on every request.
- Documenting only the success path and missing error status codes the handler actually returns.
- Guessing field types instead of reading the actual schema/type definitions.
- Letting docs drift silently when a handler changes but nothing prompts a doc update -- treat doc updates as part of the same diff as the code change.