Agent Skills
› mohitagw15856/pm-claude-skills
› api-docs-writer
api-docs-writer
GitHub将原始API规范、端点描述或Postman集合转换为面向开发者的清晰文档。支持生成包含参数、请求/响应示例及错误代码的端点文档，适用于开发者门户、README或Wiki。
Trigger Scenarios
编写API端点文档
创建API参考文档
制作开发者指南
将原始规范或Postman集合转化为文档
Install
npx skills add mohitagw15856/pm-claude-skills --skill api-docs-writer -g -y
SKILL.md
Frontmatter
{
"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.
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"
Version History
- a38bc30 Current 2026-07-05 11:29
