authoring-api-reference — SKILL.md

Variant: standard · When to use: authoring (or amending) the published, consumer-facing API reference — to a bar where a client developer can authenticate, make a first successful call, and integrate every operation from the reference alone, with every endpoint, field, and error consistent with the upstream api-spec contract (no drift, nothing fabricated).

Overview

This skill is the how-to of writing a strong published, consumer-facing API reference — the documentation an integrating client developer reads to call an API. It carries the producer's judgment — the research method and the quality bar — not the section list. It assumes two collaborators: an api-reference template tool that supplies the section structure, and a deep-research capability to ground the onboarding narrative, examples, and conventions in established public-API-docs practice. The producer is handed the upstream api-spec (the engineering wire contract every endpoint, field, and error is derived from) and, where present, the feature-spec (the usage context — what each operation is for) and the architecture-doc (auth/versioning context) — never a blank page. The bar to clear: a developer can authenticate, make a first successful call, and correctly use every operation from the reference alone, and every documented endpoint, shape, and error traces to the api-spec contract — no drift, nothing fabricated.

The reference is the narrative + onboarding + worked-example layer on top of the api-spec contract. It adds the getting-started walkthrough, the auth walkthrough, the worked examples, the pagination/error/rate-limit/deprecation guidance, and the troubleshooting the contract omits — it does not redefine, replace, or contradict the contract.

When to activate

• Authoring a published, consumer-facing API reference from an upstream api-spec that defines the operations a client integrates against.
• Documenting per-endpoint usage (purpose, typed parameters, worked request + response examples, error responses) plus getting-started + authentication, events/webhooks where the API emits them, pagination, an errors + rate-limits guide, code samples, and versioning + deprecation.
• Filling an api-reference template with researched, contract-consistent, runnable per-endpoint content.
• Adding the human-authored narrative + examples + drift check on top of a reference whose endpoint catalog is auto-generated from OpenAPI.
• Amending an existing reference when the upstream contract changes (a new/changed/deprecated endpoint) — re-syncing the affected blocks (see Step 7).

Do NOT activate when: