Skip to content

skillDocumentation

API Documentation

Documents HTTP endpoints from the real handlers, with request and response examples, error cases and auth, so integrators succeed on the first call.

npx workspacetemplates add api-documentation --tool claude-code

Writes 1 file to .claude/skills/api-documentation/

.claude/skills/api-documentation/SKILL.md28 lines · 1.6 KBFile
---
name: api-documentation
description: Documents HTTP endpoints from the real handlers, with request and response examples, error cases and auth, so integrators succeed on the first call.
---

# API documentation

Document what the code does, not what the design doc hoped it would do.

## Steps

1. Find the surface: route definitions, controllers, OpenAPI or schema files, validators, middleware. List every endpoint with method and path before writing anything.
2. For each endpoint read the handler to learn the real parameters, which are required, defaults, size limits and the shape of the success body. Read the validator for exact constraints.
3. Collect error behavior: which status codes can come back, the error body format, and the trigger for each (missing field, bad token, not found, conflict, rate limit).
4. Write one shared section first: base URL, authentication (header name, token format, how to get a key, expiry), pagination style, rate limits, versioning, idempotency.
5. Write each endpoint as: purpose in one line; `curl` example with realistic values; request parameters as a table (name, type, required, notes); success response with a real JSON body; error table.
6. If a test or local server exists, run the curl examples and paste the real output.

## Rules

- Use dummy values like `YOUR_API_KEY`, never real secrets.
- Mark undocumented or deprecated behavior as such; do not hide it.
- Keep field names exactly as the code spells them.
- Do not invent endpoints, fields or status codes.

## Report

The docs file path, the endpoints covered, the examples you ran, and mismatches found between code and any existing spec.

What it does

Generated reference pages list parameters but rarely show a working call. This skill has the agent read each handler, route and validator, then write documentation an integrator can follow with only a terminal and an API key.

Every endpoint gets a runnable example, the success body, and the errors a caller will actually hit. Authentication, pagination and rate limits are written once and linked from each endpoint.

Example

you › Write docs for the /v1/invoices endpoints

agent › Wrote docs/api/invoices.md covering 5 endpoints (list, get, create, void, download PDF). Ran all curl examples against the dev server. Found a mismatch: the OpenAPI file says amount is a string, the handler requires an integer in cents. Documented the code behavior and flagged the spec.

Questions

Can it update an OpenAPI file instead of Markdown?
Yes, tell it the target format. It then edits the spec and still checks every example against the handlers.
What if the code and the old docs disagree?
The code wins. The disagreement is listed in the report so you can decide whether the code or the contract is wrong.
  • Architecture Decision Records

    SkillDocumentation

    Free
  • Code Comments Docstrings

    SkillDocumentation

    Free
  • Design Doc Writing

    SkillDocumentation

    Free
  • Diagram as Code

    SkillDocumentation

    Free