| name | api-docs |
| description | Generate, validate, and maintain API documentation (REST/OpenAPI and GraphQL) with reproducible structure and evidence-backed confidence. |
| allowed-tools | Read, Write, Edit, Bash, Glob, Grep, Task, TodoWrite |
| model | sonnet |
| x-version | 3.2.0 |
| x-category | delivery |
| x-vcl-compliance | v3.1.1 |
| x-cognitive-frames | ["HON","MOR","COM","CLS","EVD","ASP","SPC"] |
STANDARD OPERATING PROCEDURE
Purpose
Ship accurate, consumable API docs with validated schemas, runnable examples, and clear auth/error guidance.
Trigger Conditions
- Positive: REST/GraphQL doc creation or updates, versioned API rollouts, deprecation notices, interactive explorer setup.
- Negative: Narrative/internal docs (route to
documentation) or prompt-focused tasks (route to prompt-architect).
Guardrails
- Structure-first: maintain
examples/, tests/, resources/, references/ alongside SKILL.md.
- Constraint extraction: capture HARD/SOFT/INFERRED constraints on audience, security posture, and versioning; confirm inferred.
- Validation: run spec validators (OpenAPI/GraphQL), exercise examples, and note unrun commands.
- Confidence ceilings: apply
{inference/report:0.70, research:0.85, observation/definition:0.95} to all claims.
- Safety: no secret exposure; redact internal endpoints when producing public docs.
Execution Phases
- Scope & Sources
- Identify surfaces (REST/GraphQL), auth schemes, target audience, and supported versions.
- Gather schemas, code annotations, and existing references; log constraints.
- Outline & Contracts
- Define required sections: overview, auth, endpoints/operations, errors, rate limits, changelog.
- Confirm INFERRED needs (SDK snippets, language coverage).
- Author & Validate
- Draft OpenAPI/GraphQL artifacts; generate runnable examples in
examples/.
- Validate specs (swagger-cli, graphql-schema-linter) and sample requests.
- Publish & Harden
- Wire interactive explorer (Swagger UI/GraphQL Playground) if in scope.
- Add tests in
tests/ (lint, link check, example execution) and store outputs in resources/.
- Review & Deliver
- Summarize deltas, risks, and next steps; cite sources in
references/.
- Provide confidence statement with ceiling.
Output Format
- Scope summary + constraints (HARD/SOFT/INFERRED, confirmed).
- Spec status and validation results.
- Example calls and changelog notes.
- Evidence with Confidence: X.XX (ceiling: TYPE Y.YY).
Validation Checklist
MCP / Memory Tags
- Namespace:
skills/delivery/api-docs/{api}/{version}
- Tags:
WHO=api-docs-{session}, WHY=skill-execution, WHAT=spec+docs
Confidence: 0.70 (ceiling: inference 0.70) - SOP integrates skill-forge structure-first and prompt-architect constraint/ceiling rules.
