API reference writer

Reference docs are only useful when they are complete. This skill writes one endpoint at a time and refuses to leave a field undocumented.

When to use

• Per endpoint, from the controller/handler, its validation rules and a sample response.
• On a whole route file to produce the index and flag endpoints without docs.

Input

Route (method, path, auth), validation rules or schema, the response serializer/resource, an actual response sample, and the error handling conventions.

Page structure

1. One line: what the endpoint does, in the caller's terms.
2. Request: method, path, auth requirement, path params, query params, body fields — each with type, required/optional, constraints from the validation rules, and a one-line meaning. No field without a meaning.
3. Response: status code, every field of the sample with type and meaning. Nested objects get their own table.
4. Errors: a table of status → when, derived from the validation rules and the handler (401 no token, 403 not owner, 404 not found, 422 with the field list).
5. Example: one runnable curl with placeholders in <angle brackets>, and the response it returns.
6. Notes: rate limits, idempotency, pagination — only when they exist in the code.

Rules

• Every constraint comes from the validation rules. Do not invent limits.
• If the sample response has a field the resource does not explain, mark it "undocumented — ask the owner" rather than guessing.
• Examples must be copy-pasteable: real header names, real JSON, no ellipses inside the request.
• Match the docs site's existing headings and casing.

Output format

## POST /v1/agents/{agent}/skills
Install a published skill on one of your agents. Idempotent.

**Auth:** bearer token of the agent's owner.

| body field | type | required | rules | meaning |
| skill | string | yes | `owner/name` | the skill to install |

**Response 201**
| field | type | meaning |
| installed | bool | always true on success |
| skills | string[] | every skill now on the agent |

**Errors**
| 401 | missing/invalid token |
| 403 | agent belongs to another user |
| 404 | agent or skill not found, or skill not published |
| 422 | `skill` not in `owner/name` form |

curl -X POST https://emdly.com/v1/agents/claw-01/skills -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -d '{"skill":"opsmith/jira-ticket-scorer"}'

License

MIT