// OpenAPI 3.1 specification writing, request/response examples, error documentation, versioning, and interactive API portal patterns.
| name | api-documentation |
| description | OpenAPI 3.1 specification writing, request/response examples, error documentation, versioning, and interactive API portal patterns. |
Guidelines for creating comprehensive, developer-friendly API documentation.
openapi: 3.1.0
info:
title: Task API
version: 1.0.0
paths:
/api/v1/tasks:
post:
summary: Create a task
operationId: createTask
tags: [Tasks]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTaskRequest'
example:
title: "Deploy fix"
priority: "high"
responses:
'201':
description: Task created
content:
application/json:
schema:
$ref: '#/components/schemas/Task'
'400':
$ref: '#/components/responses/ValidationError'
'401':
$ref: '#/components/responses/Unauthorized'
operationId — used for SDK generation.$ref for schemas, responses, parameters.{
"error": {
"code": "TASK_NOT_FOUND",
"message": "Task 'abc123' not found",
"details": [
{ "field": "id", "issue": "No task exists with this ID" }
]
}
}
Document every error code with:
Token-efficient communication protocol. Activate ONLY when: (1) user explicitly requests it (e.g., "use omni", "be concise", "compress output"), (2) dispatched as a sub-agent in /workflow-team pipelines where token budget matters, or (3) agent-to-agent communication via /omni headless modifier. Never activate by default in normal conversations — users expect natural language responses unless they opt in. Compresses prose form while preserving 100% technical accuracy. Code blocks, tool calls, file paths, and data are NEVER compressed.
Structured code review protocol for inspecting code quality against the full rule set. Use when auditing code written by yourself or another agent, during the /audit workflow, or when the user asks for a code review.
Pre-flight checklist and post-implementation self-review protocol. Use before generating any code (pre-flight) and after writing code but before verification (self-review) to catch issues early.
Comprehensive protocol for validating root causes of software issues. Use when you need to systematically debug a complex bug, flaky test, or unknown system behavior by forming hypotheses and validating them with specific tasks.
Profile-driven performance optimization protocol. Use when profiling data (CPU, heap, trace) is available or when the user requests performance analysis. Covers methodology, pattern catalog, safety invariants, and when-to-stop heuristics. Language-specific tooling is in languages/*.md.
Architecture Decision Record skill for documenting significant architectural decisions with context, options, and consequences. Use during the Research phase when choosing between approaches, or whenever the user asks to document an architectural decision.