---

name: api-docs-writer description: "Write clear, developer-facing API documentation. Use when asked to document an API endpoint, write API reference docs, create a developer guide, or turn a raw spec/Postman collection into documentation. Produces endpoint documentation with descriptions, parameters, request/response examples, and error codes."

API Docs Writer Skill

This skill transforms raw API specs, endpoint descriptions, or Postman collections into clean, developer-facing documentation following OpenAPI-adjacent conventions. Output is ready for a developer portal, README, or Notion/Confluence page.

Required Inputs

Ask the user for these if not provided:

• API or endpoint details (raw spec, Postman export, or verbal description)
• Auth method (API key / Bearer token / OAuth 2.0 / None)
• Base URL
• API version (e.g. v1, v2.3, or "unversioned" — affects deprecation notes and versioning headers)
• Rate limits (requests per second/minute per token or IP, if known — or "unknown")
• Audience (internal developers / external partners / public)
• Output format (Markdown for developer portals and READMEs / Plain prose for Confluence or Notion — note: OpenAPI YAML is not produced by this skill)

Output Format

For each endpoint, produce the following:

---

[METHOD] /path/to/endpoint

Summary: [One line — what this endpoint does]

Description: [2–4 sentences. When to use this endpoint. What it returns. Any important behaviour to know (pagination, rate limits, async processing, etc.)]

Authentication: [Required / Optional — method]

---

Request

Headers:

| Header | Required | Description | |---|---|---| | Authorization | Yes | Bearer <token> | | Content-Type | Yes | application/json |

Path Parameters:

| Parameter | Type | Required | Description | |---|---|---|---| | id | string | Yes | Unique identifier for the resource |

Query Parameters:

| Parameter | Type | Required | Default | Description | |---|---|---|---|---| | limit | integer | No | 20 | Max results per page (1–100) | | cursor | string | No | — | Pagination cursor from previous response |

Request Body:

{
  "field_name": "value",
  "another_field": 42
}

| Field | Type | Required | Description | |---|---|---|---| | field_name | string | Yes | [Plain description of what this field does] | | another_field | integer | No | [Description. Include valid range or enum values if applicable] |

---

Response

Success Response: 200 OK

{
  "id": "abc123",
  "status": "active",
  "created_at": "2025-04-01T10:00:00Z"
}

| Field | Type | Description | |---|---|---| | id | string | Unique identifier for the created/retrieved resource | | status | string | Current status. Enum: active, inactive, pending | | created_at | ISO 8601 string | Timestamp of creation in UTC |

---

Error Codes

| Status Code | Error Code | Description | How to Resolve | |---|---|---|---| | 400 | INVALID_REQUEST | Request body is malformed or missing required fields | Check request body against schema above | | 401 | UNAUTHORIZED | Missing or invalid authentication token | Verify your API key or refresh your token | | 404 | NOT_FOUND | The requested resource does not exist | Check the ID in the path parameter | | 429 | RATE_LIMITED | Too many requests | Back off and retry after Retry-After header value | | 500 | INTERNAL_ERROR | Unexpected server error | Retry with exponential backoff; contact support if persists |

---

Code Examples

Produce examples in at least 2 languages relevant to the audience (default: cURL + Python):

cURL:

curl -X POST https://api.example.com/v1/endpoint \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"field_name": "value"}'

Python:

import requests

response = requests.post(
    "https://api.example.com/v1/endpoint",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={"field_name": "value"}
)
data = response.json()

---

Deeper Materials

This skill ships with support files — use them when they are available:

• references/example-first-docs.md — Example-First API Docs: the Rules That Make Docs Usable. Apply it while producing the output; it carries the calibration and judgment calls the method summary above compresses.
• templates/endpoint-entry.md — a fill-in version of the deliverable with the quality gates inline. Offer it when the user wants to work the document themselves rather than have it generated.

Scoring Rubric (0–40)

Score any output of this skill before handing it over; 32+ is ship-quality.

| Dimension | 0 | 5 | 10 | |---|---|---|---| | Parameter completeness | Fields listed without types or required/optional flags | Tables complete, but descriptions say what a field is, not what it does; enums and ranges missing | Every field typed and constrained (enums, ranges, formats), described by behaviour and consequence | | Error-path coverage | Happy path only — no error table | Standard 400/401/404/429/500 rows present but with no resolution guidance | Full standard set plus endpoint-specific codes, each with what the developer should do, including unsafe-retry cases | | Example runnability | Pseudo-code, undefined variables, or "YOUR_ENDPOINT" placeholders | Examples exist but aren't copy-paste-runnable or use only one language | ≥2 languages, real base URL, obviously-fake placeholder credentials, runnable as pasted | | Behavioural candour | Async behaviour, pagination, idempotency, and legacy quirks omitted | Quirks mentioned in prose but absent from examples and error rows | Gotchas documented with the exact requests/responses they produce, including awkward legacy behaviour |

Quality Checks

• [ ] Every parameter is documented (type, required/optional, description)
• [ ] Response fields are fully documented with types
• [ ] All relevant error codes are listed with resolution guidance
• [ ] Error codes cover at minimum: 400 (bad request), 401/403 (auth), 404 (not found), 429 (rate limited), 500 (server error) — or explicitly note which don't apply to this endpoint
• [ ] Code examples use the actual base URL and a realistic placeholder token — no examples reference undefined variables or "YOUR_ENDPOINT" outside the snippet
• [ ] Auth method is clearly stated at the top
• [ ] Enum values are listed where applicable
• [ ] Pagination documented if the endpoint is a list endpoint

Anti-Patterns

• [ ] Do not document only the happy path — every endpoint must have error codes for at least 400, 401/403, 404, 429, and 500
• [ ] Do not use placeholder values like "YOUR_ENDPOINT" or "INSERT_TOKEN" in code examples — use realistic-looking placeholders anchored to the actual base URL
• [ ] Do not skip enum values for fields with a fixed set of accepted values — undocumented enums cause integration bugs
• [ ] Do not omit pagination documentation on list endpoints — developers who miss this will build integrations that silently miss data
• [ ] Do not describe what a field "is" without describing what it "does" — "the ID" is not documentation; "the unique identifier used to retrieve or update this resource" is

Usage Examples

• "Document this API endpoint: [paste spec or description]"
• "Turn this Postman collection into developer docs"
• "Write API reference docs for [endpoint]"
• "Write a developer guide for our [product] API"