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:

Path Parameters:

Query Parameters:

Request Body:

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

Response

Success Response: 200 OK

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

Error Codes

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.

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"