Publish or refresh developer-facing API documentation for REST, GraphQL, webhook, SDK, and developer-portal surfaces: reference docs, quickstarts, task guides, auth/setup notes for API consumers, truthful example requests, error/retry/limit guidance, and migration updates. Use when the contract already exists and the main job is helping integrators succeed with the API, not designing resources or versioning strategy. Triggers on: API docs, developer portal, OpenAPI reference, SDK docs, webhook docs, quickstart, integration guide, endpoint reference, pagination docs, rate-limit docs, migration note, and partner API guide. Route contract design to `api-design`, internal specs/runbooks to `technical-writing`, end-user UI help to `user-guide-writing`, auth implementation to `authentication-setup`, and release-note hygiene to `changelog-maintenance`.
Instrucciones de origen · Vista previa de solo lectura
name
api-documentation
description
Publish or refresh developer-facing API documentation for REST, GraphQL, webhook, SDK, and developer-portal surfaces: reference docs, quickstarts, task guides, auth/setup notes for API consumers, truthful example requests, error/retry/limit guidance, and migration updates. Use when the contract already exists and the main job is helping integrators succeed with the API, not designing resources or versioning strategy. Triggers on: API docs, developer portal, OpenAPI reference, SDK docs, webhook docs, quickstart, integration guide, endpoint reference, pagination docs, rate-limit docs, migration note, and partner API guide. Route contract design to `api-design`, internal specs/runbooks to `technical-writing`, end-user UI help to `user-guide-writing`, auth implementation to `authentication-setup`, and release-note hygiene to `changelog-maintenance`.
allowed-tools
Read Write Edit Glob Grep
compatibility
Best for docs-as-code repos, developer portals, OpenAPI/GraphQL references, SDK docs, and integration guides where the output helps external or internal integrators use an API safely and successfully.
Use this skill when the main job is publishing or refreshing developer-facing API docs that help integrators reach first success, understand reference truth, and stay unblocked as the API evolves.
api-documentation is the documentation-cluster anchor for:
endpoint / schema reference docs
quickstarts and first-success flows
task-oriented integration guides
SDK guides
webhook delivery / verification docs
developer-portal navigation and grouped reference surfaces
migration updates attached to the docs surface
Read these support docs before choosing the mode or output packet:
A team needs API reference, quickstarts, or portal pages that external developers, partners, or internal integrators can actually use.
An OpenAPI or schema artifact already exists, but the docs need structure, examples, auth/setup guidance, error handling, or clearer navigation.
Existing API docs drifted after auth, versioning, retry, pagination, webhook, or SDK changes.
A public, partner, or internal API launch needs developer-facing guides, migration notes, or trustworthy examples.
A large API surface needs grouping, selective publishing, or cleaner portal structure instead of one giant reference dump.
When not to use this skill
The main job is designing resources, endpoint shape, schema rules, or versioning strategy → use api-design.
The main job is writing internal specs, ADRs, runbooks, rollout docs, or system migration procedures → use technical-writing.
The main job is end-user/product UI onboarding, screenshots, tutorials, or help-center docs → use user-guide-writing.
The main job is implementing auth/session/provider behavior rather than documenting how API consumers authenticate → use authentication-setup.
The main job is release-note, semver, or changelog hygiene → use .
changelog-maintenance
There is no credible source of truth for the API behavior yet → route missing contract questions back to api-design instead of inventing docs from vibes.
reference → endpoint/schema truth with parameters, fields, errors, limits, and examples
quickstart → fastest path to first successful API call or webhook receipt
task-guide → one workflow or integration outcome
sdk-guide → language/client-library guidance plus examples and caveats
webhook-guide → delivery, verification, retry, and local-debug guidance
migration-update → changed behavior and transition path on the docs surface
If the surface is large, also decide whether the task is about grouping/navigation as much as prose. Do not hide large-surface information architecture inside a generic “write docs” request.
Step 2: Confirm boundary skills and the real developer job
Answer these four questions before writing:
Who is integrating with this API, and what exact job should they complete after reading?
What artifact is the real contract source of truth today?
Which docs surface are you updating: portal, repo docs, SDK site, internal catalog, or mixed?
Which neighboring skills must stay out of scope?
Quick route-out table:
If the request sounds like...
Use
"Design the endpoints / resources / schema before coding"
api-design
"Write the architecture doc / ADR / rollout plan / runbook"
technical-writing
"Write customer help docs for using the product UI"
Expose navigation decisions on large APIs: grouping, selective publishing, and related-guide links matter.
Link outward deliberately: quickstarts point to deeper reference; reference points to task guides; migration updates point to changelog/release notes rather than replacing them.
Could a new integrator reach first success with this doc set?
Are auth and environment assumptions visible before the first call?
Do examples match real behavior?
Are errors, limits, retries, pagination, or verification notes present where needed?
Is the output packet small enough for the request?
Are route-outs to api-design, technical-writing, user-guide-writing, authentication-setup, and changelog-maintenance still explicit?
Examples
Example 1: Partner API quickstart
Input: “Write the quickstart for our Orders API so partners can create an API key, send the first POST /orders, and verify the returned order ID.”
Good output shape: chooses quickstart, shows prerequisites and auth early, gives one first-success request plus a success check, and links to the deeper reference surface.
Example 2: Large reference cleanup
Input: “Our developer portal publishes one huge OpenAPI collection; help us regroup endpoints, expose only partner-safe sections, and add navigation that developers can scan.”
Good output shape: treats this as reference plus navigation/grouping work, proposes grouped sections or selective publishing, preserves truthful reference links, and does not pretend auto-generation alone solves the structure problem.
Example 3: Webhook change notice
Input: “Update our webhook docs because invoice.paid now retries for 24 hours, includes attempt_count, and requires HMAC verification on every delivery.”
Good output shape: chooses webhook-guide or migration-update, documents retry and verification behavior, updates affected examples, and keeps implementation details and release-note hygiene out of scope.
Example 4: Route-out to API design
Input: “We haven’t decided whether this should be REST or GraphQL, and we need a resource model and pagination plan.”
Good output shape: routes the task to api-design, explains that contract/interface work must happen before docs publication, and may note what docs surfaces will be needed later.
Best practices
Treat API docs as developer workflow artifacts, not as schema rendering alone.
Keep contract design separate from developer-facing publication.
Prefer small, truthful packets over one giant portal page.
Make auth, examples, limits, retries, pagination, and webhook behavior explicit early.
Document navigation/grouping decisions for large surfaces instead of burying them in prose.
Tie docs maintenance to real truth sources so refreshes do not drift.
Route adjacent writing, auth implementation, and release hygiene tasks to the right neighboring skill.
