api-docs-writer

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()

---

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"