Write clear, developer-facing API documentation

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"