Menu
API documentation specialist for OpenAPI/Swagger specifications. Use when documenting REST or GraphQL APIs.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Designs technical solutions and architecture. Use when user says "design solution", "architecture design", "technical design", or "方案设计" WITHOUT mentioning PRD. For PRD-specific work, use prd-planner skill instead.
Workflow hook metadata for agent-playbook skills. This skill documents trigger intent between skills - DO NOT use directly, and do not assume hooks execute unless the host runtime explicitly supports them.
Reviews pull requests and code changes for quality, security, and best practices. Use when user asks for code review, PR review, or mentions reviewing changes.
Helps write Git commit messages following the Conventional Commits specification. Use this skill when the user asks to commit changes, write commit messages, format commits, or mentions git commits.
Creates pull requests with bilingual documentation checks. Use when user asks to create PR, make a pull request, or submit changes for review. Ensures English and Chinese README files stay in sync when user-facing skill catalog changes require it.
Deployment automation specialist for CI/CD pipelines and infrastructure. Use when setting up deployment, configuring CI/CD, or managing releases.
| name | api-documenter |
| description | API documentation specialist for OpenAPI/Swagger specifications. Use when documenting REST or GraphQL APIs. |
| allowed-tools | Read, Write, Edit, Bash, Grep, Glob |
| metadata | {"hooks":{"after_complete":[{"trigger":"session-logger","mode":"auto","reason":"Log documentation activity"}]}} |
Specialist in creating comprehensive API documentation using OpenAPI/Swagger specifications.
Activates when you:
openapi: 3.0.3
info:
title: API Title
version: 1.0.0
description: API description
servers:
- url: https://example.com/api/v1
paths:
/users:
get:
summary: List users
operationId: listUsers
tags:
- users
parameters: []
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
components:
schemas:
User:
type: object
properties:
id:
type: string
name:
type: string
For each endpoint, document:
/users/{id}:
get:
summary: Get a user by ID
operationId: getUserById
description: Retrieves a single user by their unique identifier
tags:
- users
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The user ID
responses:
'200':
description: User found
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'404':
description: User not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
User:
type: object
required:
- id
- email
properties:
id:
type: string
format: uuid
description: Unique user identifier
example: "550e8400-e29b-41d4-a716-446655440000"
email:
type: string
format: email
description: User's email address
example: "user@example.com"
createdAt:
type: string
format: date-time
description: Account creation timestamp
Document auth requirements:
security:
- bearerAuth: []
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Use your JWT token from /auth/login
Standard error format:
components:
schemas:
Error:
type: object
properties:
error:
type: string
description: Error message
code:
type: string
description: Application-specific error code
details:
type: object
description: Additional error details
Common HTTP status codes:
Generate OpenAPI spec from code:
python scripts/generate_openapi.py
Validate OpenAPI spec:
python scripts/validate_openapi.py openapi.yaml
references/openapi-template.yaml - OpenAPI templatereferences/examples/ - API documentation examples