Api Docs WriterCAUTION

1255 professional Agent Skills for Claude, ChatGPT, Gemini, Cursor & Codex — PRDs, postmortems, leases, medical bills, layoffs, go-bags, new countries. Plain markdown, MIT, in Anthropic's plugin directory. Plus a typed decision layer: which skill, is it safe, ship or slip. Free in-browser or npx pm-

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

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

Work from what is given. If any of these is missing, still produce the complete output: fill each gap with a reasonable assumption marked *(assumed, confirm)* and list those assumptions at the end. Ask a question first only when the core subject itself is missing (there is nothing to write about).
- **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:**

```json
{
  "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`**

```json
{
  "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:**
```bash
curl -X POST https://api.example.com/v1/endpoint \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"field_name": "value"}'
```

**Python:**
```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 | 

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (5)

templates/pm-discovery-agent/skills/assumption-mapper/SKILL.md

templates/pm-discovery-agent/skills/discovery-interview-guide/SKILL.md

templates/pm-discovery-agent/skills/job-story-mapper/SKILL.md

templates/pm-discovery-agent/skills/user-interview-synthesis/SKILL.md

templates/pm-launch-agent/skills/content-calendar/SKILL.md

Gates applied: no_behavioural_pass.