API Reference Writer
Generates an accurate API reference from source and handlers: endpoints, params, request and response shapes, status codes, and auth.
What this skill does
Key features
- Reads route handlers to document only endpoints that actually exist
- Captures params, request and response shapes, and status codes
- Records auth requirements per endpoint
- Notes gaps where behavior is unclear instead of guessing
Use cases
- Documenting a REST service that has no reference yet
- Keeping an API reference in sync with the handlers
- Producing Markdown docs from Express or FastAPI routes
SKILL.md
The skill definition — its metadata and the exact instructions an agent follows. Copy it into a SKILL.md file in your agent's skills folder.
| name | api-docs |
|---|---|
| description | Generate an accurate Markdown API reference from real route handlers, documenting only observed behavior. |
| allowed-tools | Read, Grep |
| output | markdown API reference |
| invents_endpoints | never |
Musts
- Read the actual route handlers before writing any endpoint.
- Document only endpoints, params, and status codes the code actually implements.
- Record the auth requirement for each endpoint as the code enforces it.
- Show request and response shapes drawn from the handler, not assumed.
- Mark anything ambiguous as a gap rather than inventing behavior.
Guidelines
- Group endpoints by resource and keep a consistent method and path format.
- Include realistic example requests and responses derived from the code.
- Note default values, required fields, and error responses when the handler sets them.
- Prefer linking to the source location for each documented route.
Output format
## <METHOD> <path>
<one-line description>
**Auth:** <required scope or none>
**Parameters**
| name | in | type | required | description |
| ---- | -- | ---- | -------- | ----------- |
**Responses**
| status | body |
| ------ | ---- |
**Gaps:** <anything the code did not make clear>FAQ
Will it invent endpoints or fields?
No. It documents only what the handlers actually implement. Where behavior is ambiguous it flags a gap instead of guessing an endpoint, parameter, or status code.
Does it output OpenAPI?
It produces readable Markdown by default and can mirror OpenAPI structure. It reflects the source, so review any generated schema before publishing.
Before running any skill, read its instructions and the tools it's allowed to use, and test it on a safe target first. See LLM security best practices.