From skillry-documentation-and-tech-writing
Use when you need to produce or audit API reference documentation from code or an OpenAPI spec — complete endpoint/parameter coverage, runnable request/response examples, an error/status-code table, authentication notes, and a clear versioning and deprecation policy.
How this skill is triggered — by the user, by Claude, or both
Slash command
/skillry-documentation-and-tech-writing:302-api-reference-docsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Generate and verify complete, accurate API reference documentation derived from the source of truth — an OpenAPI/JSON Schema spec, typed function signatures, or route definitions. Every operation must document its parameters, request body, response shapes, authentication, error responses, and rate limits, with at least one runnable example per operation. Reference docs answer "what exactly does...
Generate and verify complete, accurate API reference documentation derived from the source of truth — an OpenAPI/JSON Schema spec, typed function signatures, or route definitions. Every operation must document its parameters, request body, response shapes, authentication, error responses, and rate limits, with at least one runnable example per operation. Reference docs answer "what exactly does this endpoint accept and return", distinct from tutorials (how to accomplish a goal).
# Find an OpenAPI / GraphQL / proto spec
find . -name "openapi*.y*ml" -o -name "openapi*.json" -o -name "swagger*.*" \
-o -name "*.graphql" -o -name "*.proto" 2>/dev/null | grep -v node_modules
# Validate the OpenAPI spec before trusting it
npx --yes @redocly/cli lint openapi.yaml
# or: npx --yes @stoplight/spectral-cli lint openapi.yaml
# List every path + method declared in the spec
python3 - <<'EOF'
import yaml
spec = yaml.safe_load(open("openapi.yaml"))
for path, ops in spec.get("paths", {}).items():
for method, op in ops.items():
print(f"{method.upper():6} {path} -> {op.get('summary','(no summary)')}")
EOF
Cross-check the live route table (framework router output) against the spec so no implemented endpoint is undocumented and no documented endpoint is dead.
# Static HTML reference from OpenAPI
npx --yes @redocly/cli build-docs openapi.yaml -o site/api.html
# For library/SDK docs, generate from signatures + docstrings
# Python: pdoc ./pkg -o site/api (or sphinx-apidoc)
# TypeScript: npx typedoc --out site/api src/index.ts
Each operation gets a complete request (method, URL, headers, body) and a real response with status code. Examples must use placeholder credentials and be copy-pasteable.
# Example block to embed, then verify against a test instance
curl -sS -X POST "$API_BASE/v1/widgets" \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "example-widget", "color": "blue"}'
# Expected: 201 Created, body: {"id":"wdg_123","name":"example-widget","color":"blue"}
Document every status code the operation can return, when it occurs, the error body schema, and the recommended client action.
State the auth scheme (bearer token, API key header, OAuth scopes) once, centrally. Define how versions are expressed (URI /v1/, header, or media type), the deprecation timeline, and the sunset signaling (e.g. Deprecation / Sunset response headers).
### POST /v1/widgets — Create a widget
Creates a widget. Requires scope `widgets:write`.
**Request body** (`application/json`)
| Field | Type | Required | Default | Notes |
|---------|--------|----------|---------|--------------------------|
| `name` | string | yes | — | 1–64 chars |
| `color` | string | no | `gray` | one of: gray, blue, red |
**Responses**
| Status | Meaning | Body schema | Client action |
|--------|--------------|-----------------|--------------------------|
| 201 | Created | `Widget` | Store the returned `id` |
| 400 | Invalid body | `Error` | Fix fields, retry |
| 401 | No/expired token | `Error` | Refresh credentials |
| 429 | Rate limited | `Error` | Honor `Retry-After` |
**Example**
curl -X POST "$API_BASE/v1/widgets" \
-H "Authorization: Bearer $API_TOKEN" \
-d '{"name":"demo","color":"blue"}'
# 201 -> {"id":"wdg_123","name":"demo","color":"blue"}
Produce: (1) a coverage report (endpoints in spec vs in code vs documented); (2) spec lint results; (3) the rendered reference output path; (4) per-operation parameter and error tables; (5) at least one verified runnable example; (6) the documented auth + versioning/deprecation policy; (7) a list of drift or gaps to fix.
Provides CDSS development patterns for drug interaction checking, dose validation, clinical scoring (NEWS2, qSOFA), and alert classification integrated into EMR workflows.
npx claudepluginhub fluxonlab/skillry --plugin skillry-documentation-and-tech-writing