Name: api-documenter
Author: zhaono1

Imported from zhaono1/agent-playbook (skills/api-documenter/SKILL.md) via skills.sh. Install upstream with npx skills add zhaono1/agent-playbook --skill api-documenter. Copyright stays with the author.

API Documenter

Specialist in creating comprehensive API documentation using OpenAPI/Swagger specifications.

When This Skill Activates

Activates when you:

Ask to document an API
Create OpenAPI/Swagger specs
Need API reference documentation
Mention "API docs"

OpenAPI Specification Structure

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

Endpoint Documentation

For each endpoint, document:

Required Fields

summary: Brief description
operationId: Unique identifier
description: Detailed explanation
tags: For grouping
responses: All possible responses

Recommended Fields

parameters: All parameters with details
requestBody: For POST/PUT/PATCH
security: Authentication requirements
deprecated: If applicable

Example

/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'

Schema Documentation

Best Practices

Use references for shared schemas
Add descriptions to all properties
Specify format for strings (email, uuid, date-time)
Add examples for complex schemas
Mark required fields

Example

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

Authentication Documentation

Document auth requirements:

security:
  - bearerAuth: []

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Use your JWT token from /auth/login

Error Responses

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:

200: Success
201: Created
204: No Content
400: Bad Request
401: Unauthorized
403: Forbidden
404: Not Found
409: Conflict
422: Unprocessable Entity
500: Internal Server Error

Scripts

Generate OpenAPI spec from code:

python3 scripts/generate_openapi.py --name <resource-name> --output openapi.yaml

Validate OpenAPI spec:

python3 scripts/validate_openapi.py --input openapi.yaml

References

references/openapi-template.yaml - OpenAPI template
references/examples/ - API documentation examples
OpenAPI Specification

Install api-documenter and it becomes one more candidate the router can pick - when it fits.

A listing is a routing target with a manifest: what it does, which domains it covers, what it costs and who publishes it. Once installed it sits beside your own models and tools, is scored like any other candidate for each request, and shows up in the trace when it wins. Ratings come from workspaces that installed it, one per account.

{ "ocm": "1", "id": "zhaono1-agent-playbook-api-documenter", "kind": "skill", "name": "api-documenter", "description": "API documentation specialist for OpenAPI/Swagger specifications. Use when documenting REST or GraphQL APIs.", "publisher": "zhaono1", "version": "1.0.0", "capabilities": { "domains": [ "coding" ], "tags": [ "skill-md", "skills-sh" ], "languages": [ "en" ] }, "quality_prior": 0.6, "examples": [ "API documentation specialist for OpenAPI/Swagger specifications. Use when documenting REST or GraphQL APIs." ], "primary": false, "metadata": { "source": { "provider": "skills.sh", "repository": "https://github.com/zhaono1/agent-playbook", "path": "skills/api-documenter/SKILL.md", "ref": "HEAD", "url": "https://www.skills.sh/zhaono1/agent-playbook/api-documenter", "key": "zhaono1/agent-playbook/skills/api-documenter/SKILL.md" }, "allowed_tools": [ "Read,", "Write,", "Edit,", "Bash,", "Grep,", "Glob" ] }, "instructions": "# API Documenter\n\nSpecialist in creating comprehensive API documentation using OpenAPI/Swagger specifications.\n\n## When This Skill Activates\n\nActivates when you:\n- Ask to document an API\n- Create OpenAPI/Swagger specs\n- Need API reference documentation\n- Mention \"API docs\"\n\n## OpenAPI Specification Structure\n\n```yaml\nopenapi: 3.0.3\ninfo:\n title: API Title\n version: 1.0.0\n description: API description\nservers:\n - url: https://example.com/api/v1\npaths:\n /users:\n get:\n summary: List users\n operationId: listUsers\n tags:\n - users\n parameters: []\n responses:\n ", "cost": { "context_tokens": 1061 } }

api-documenter

About

API Documenter

When This Skill Activates

OpenAPI Specification Structure

Endpoint Documentation

Required Fields

Recommended Fields

Example

Schema Documentation

Best Practices

Example

Authentication Documentation

Error Responses

Scripts

References

Install api-documenter and it becomes one more candidate the router can pick - when it fits.

Use it

Manifest

Reviews