Skip to content
Skills Library
Programming · Writing

api-documentation

/api-documentation

Use when source code has changed and API docs are stale, or a new endpoint lacks documentation — generates accurate docs from implementation, not guesswork.

Licence
MIT
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when source code has changed and API docs are stale, or a new endpoint lacks documentation — generates accurate docs from implementation, not guesswork.

Original author description

Use when source code has changed and API docs are stale, or a new endpoint lacks documentation — generates accurate docs from implementation, not guesswork.

How it works

  1. When to Use
  2. Prerequisites
  3. Workflow
  4. Examples
  5. Tips
Original SKILL.md headings · 170 lines, 635 words
SKILL.md preview
---
name: api-documentation
description: Use when source code has changed and API docs are stale, or a new endpoint lacks documentation — generates accurate docs from implementation, not guesswork.
metadata:
  category: documentation
  agent_type: general-purpose
---

# API Documentation

## When to Use

- Building or updating REST/GraphQL API documentation
- Onboarding new developers who need to understand available endpoints
- Preparing API reference docs for external consumers
- Ensuring API docs stay synchronized with implementation
- Creating OpenAPI/Swagger specifications from existing code

## Prerequisites

- API source code with route definitions
- Understanding of the API framework (Express, FastAPI, Gin, etc.)
- Knowledge of request/response formats and authentication requirements

## Workflow

### 1. Discover All Endpoints

```powershell
# Express / Node.js
grep -rn "router\.\(get\|post\|put\|delete\|patch\)\|app\.\(get\|post\|put\|delete\|patch\)" src/ --include="*.ts" --include="*.js"

# FastAPI / Python
grep -rn "@app\.\(get\|post\|put\|delete\)\|@router\." src/ --include="*.py"

# Go / Gin
grep -rn "\.GET\|\.POST\|\.PUT\|\.DELETE" . --include="*.go"
```

Use `explore` agent for a comprehensive map:

```text
task agent_type: "explore"
prompt: "Map all API endpoints in this project. For each endpoint list: HTTP method, path, handler function name, file location, and any middleware applied."
```

### 2. Document Each Endpoint

For each endpoint, capture:

```markdown
## POST /api/users

Create a new user account.

**Authentication:** Bearer token required

**Request Body:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | Yes | Valid email address |
| name | string | Yes | Display name (1-100 chars) |
| role | string | No | User role (default: "viewer") |

**Response 201:**
```json
{
  "id": "usr_abc123",
  "email": "user@example.com",
  "name": "Jane Doe",
  "role": "viewer",
  "createdAt": "2024-01-15T10:30:00Z"
}
```

**Error Responses:**

| Status | Description |
|--------|-------------|
| 400 | Invalid request body |
| 409 | Email already exists |
| 401 | Missing or invalid auth token |

```text

### 3. Extract Types and Schemas
```powershell
# Find request/response type definitions
grep -rn "interface.*Request\|interface.*Response\|type.*Payload" src/ --include="*.ts" -A 10

# Find validation schemas (Zod, Joi, etc.)
grep -rn "z\.object\|Joi\.object\|Schema" src/ --include="*.ts" -A 10
```

### 4. Document Authentication

```powershell
# Find auth middleware and configuration
grep -rn "auth\|jwt\|bearer\|apiKey\|passport" src/middleware/ --include="*.ts" -A 5
```

```markdown
## Authentication

All endpoints except `POST /auth/login` require a Bearer token.

```bash
curl -H "Authorization: Bearer <token>" https://api.example.com/users
```

### Obtaining a Token

```bash
curl -X POST https://api.example.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "secret"}'
```

```text

### 5. Add Working Examples
```powershell
# Test each documented example against a running server
# Start the dev server
npm run dev  # mode: async, detach: true

# Verify an endpoint
curl -s http://localhost:3000/api/health | python -m json.tool
```

### 6. Generate OpenAPI Spec (Optional)

```powershell
# If using a framework that supports auto-generation
npx swagger-jsdoc -d src/swagger-config.js -o docs/openapi.json

# Or generate from TypeScript types
npx ts-to-openapi --input src/types/ --output docs/openapi.yaml
```

## Examples

### Documenting a CRUD API

```powershell
# 1. Find all route files
glob pattern="src/routes/**/*.ts"

# 2. For each route file, extract endpoints and their handlers
grep -rn "router\." src/routes/users.ts -A 3

# 3. Find the handler implementation for request/response details
grep -rn "export.*function\|export.*const.*=" src/controllers/users.ts -A 15
```

### Quick API Reference Table

```markdown
| Method | Path | Description | Auth |
|--------|------|-------------|------|
| GET | /api/users | List all users | Yes |
| POST | /api/users | Create user | Yes |
| GET | /api/users/:id | Get user by ID | Yes |
| PUT | /api/users/:id | Update user | Yes |
| DELETE | /api/users/:id | Delete user | Admin |
```

## Tips

- **Generate from code** when possible — manually written docs drift from reality
- Include `curl` examples for every endpoint — they're the most portable format
- Document error responses, not just success cases
- Add rate limiting and pagination details if applicable
- Version your API docs alongside API code (same branch, same PR)
- Use `task` agent to verify documented curl commands actually work against the API
- Include a Postman collection or similar importable format for API consumers

Versions

RepositoryScoreLicence
This page · drvoss/everything-copilot-cli100MIT
akillness/jeo-skills100MIT
OKHP3/skillz100MIT
helx0071/skillsmo100MIT
postmanlabs/postman-plugin100Apache-2.0
LambdaTest/agent-skills100MIT
autohandai/community-skills100Apache-2.0
zircote-plugins/documentation-review100MIT
j4flmao/agent-skills95MIT

Database snapshot: 13.11.2026 · package version 271c1999311a (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100agent-documentation-writer
    Specialist subagent: Generates comprehensive documentation including READMEs, API docs, architecture docs, and inline comments. Use when documenting code, creating guides, or explaining systems.
  • 100code-documentation
    Analyze source code repositories and create, update, and validate accurate technical documentation. Use when developers request README generation, API documentation, architecture documentation, codebase explanation, or documentation maintenance.
  • 100project-docs
    Generate project documentation from codebase analysis — ARCHITECTURE.md, API_ENDPOINTS.md, DATABASE_SCHEMA.md. Reads source code, schema files, routes, and config to produce accurate, structured docs. Use when starting a project, onboarding contributors, or when docs are missing…
  • 100documentation
    Use this skill when the user asks you to write, update, or fix project documentation — READMEs, API docs, user guides, ADRs, or other Markdown docs. Also use when code changes need user-facing docs updates. Only write Markdown files; do not use for implementation, planning or test work.
  • 100documentation-updater
    Update all project documentation including implementation docs, user guides, API docs, and architecture diagrams. Use when finalizing features to ensure comprehensive documentation.
  • 100generating-api-docs
    Create comprehensive API documentation with examples, authentication guides, and SDKs. Use when creating comprehensive API documentation. Trigger with phrases like "generate API docs", "create API documentation", or "document the API".

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.