Skip to main content
skill CX Codex

api-documentation · bradtaylorsf — Claude Code skill: what it does, install

The api-documentation skill sets patterns for REST and GraphQL API docs. Use it when endpoints, schemas, errors, pagination, and SDK examples need a consistent structure.

MIT 1 installs ★ 8 updated 2026-02-05

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add bradtaylorsf/alphaagent-team --skill api-documentation -a claude-code
Open on GitHub

What api-documentation does

The skill lays out REST endpoint pages with the HTTP method, path, auth mode, parameters, request body, success response, and error cases. It also covers Bearer tokens, API keys, OAuth 2.0, standard pagination, and cursor-based pagination with request and response examples.

For GraphQL, the patterns cover schema types, input types, queries, and mutations. Each section can include arguments, sample operations, variables, and returned data. The package also shows SDK examples for JavaScript/TypeScript, Python, and cURL, plus a shared JSON shape for errors with a code, message, details, and requestId.

The skill is used by the api-doc-writer agent. It focuses on REST and GraphQL, so other API styles fall outside these documented patterns.

What it helps with

  • document a REST endpoint with parameters and responses
  • record the authentication methods an API accepts
  • describe page-based and cursor-based pagination
  • write reference pages for GraphQL queries and mutations
  • add SDK examples for JavaScript/TypeScript, Python, and cURL

Example prompts for the agent

  • Document the REST endpoint /api/v1/users/:id with its parameters, auth, responses, and errors.
  • Write GraphQL documentation for the createUser mutation, including its input and failure response.
  • Add Python and cURL examples to the API docs and describe the pagination format.

How to install api-documentation

1Skills CLI (Vercel)

npx skills add bradtaylorsf/alphaagent-team --skill api-documentation -a claude-code

2Manually: put the files in place

~/.claude/skills/api-documentation/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/api-documentation/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about api-documentation

How do I install api-documentation in Claude Code?

Run npx skills add bradtaylorsf/alphaagent-team --skill api-documentation -a claude-code, then check ~/.claude/skills/api-documentation/SKILL.md.

What does api-documentation do?

It provides documentation patterns for REST and GraphQL APIs, covering endpoints, auth, pagination, errors, schemas, queries, mutations, and SDK examples.

Which API styles does api-documentation cover?

It covers REST and GraphQL. REST patterns include regular and cursor-based pagination, while GraphQL patterns cover types, input types, queries, and mutations.

Source text

SKILL.md · MIT
---
name: api-documentation
description: API documentation standards and patterns
---

# API Documentation Skill

Standards for documenting REST and GraphQL APIs.

## REST API Documentation

### Endpoint Format

```markdown
## Endpoint Name

Brief description of what this endpoint does.

**Method:** `GET` | `POST` | `PUT` | `PATCH` | `DELETE`
**Path:** `/api/v1/resource/:id`
**Auth:** Bearer token | API key | None

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| id | string | Resource ID |

### Query Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| page | integer | No | 1 | Page number |
| limit | integer | No | 20 | Items per page |
| sort | string | No | -createdAt | Sort field |

### Request Body

\`\`\`json
{
  "field1": "value",
  "field2": 123
}
\`\`\`

### Response

**Success (200 OK)**

\`\`\`json
{
  "data": { ... },
  "meta": { ... }
}
\`\`\`

**Errors**

| Status | Code | Description |
|--------|------|-------------|
| 400 | VALIDATION_ERROR | Invalid input |
| 404 | NOT_FOUND | Resource not found |
```

### Authentication Section

```markdown
# Authentication

All API requests require authentication via one of:

## Bearer Token (Recommended)

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

Tokens expire after 1 hour. Use the refresh token to obtain a new access token.

## API Key

\`\`\`bash
curl -H "X-API-Key: <api-key>" https://api.example.com/v1/users
\`\`\`

API keys don't expire but can be revoked in the dashboard.

## OAuth 2.0

For third-party integrations:

1. Redirect to `/oauth/authorize`
2. User grants permission
3. Receive authorization code
4. Exchange code for tokens
```

### Pagination Documentation

```markdown
# Pagination

List endpoints return paginated results.

## Request Parameters

| Parameter | Type | Default | Max | Description |
|-----------|------|---------|-----|-------------|
| page | integer | 1 | - | Page number (1-indexed) |
| limit | integer | 20 | 100 | Items per page |

## Response Format

\`\`\`json
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8,
    "hasNext": true,
    "hasPrev": false
  }
}
\`\`\`

## Cursor-Based Pagination

For large datasets, use cursor pagination:

\`\`\`bash
GET /api/v1/events?cursor=abc123&limit=50
\`\`\`

\`\`\`json
{
  "data": [...],
  "cursors": {
    "next": "def456",
    "prev": null
  }
}
\`\`\`
```

### Error Documentation

```markdown
# Error Handling

## Error Response Format

All errors return a consistent JSON structure:

\`\`\`json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ],
    "requestId": "req_abc123"
  }
}
\`\`\`

## Error Codes

### Client Errors (4xx)

| Code | Status | Description | Resolution |
|------|--------|-------------|------------|
| VALIDATION_ERROR | 400 | Invalid input | Check request body |
| UNAUTHORIZED | 401 | No valid credentials | Include auth header |
| FORBIDDEN | 403 | Insufficient permissions | Request access |
| NOT_FOUND | 404 | Resource doesn't exist | Check resource ID |
| CONFLICT | 409 | Resource already exists | Use different values |
| RATE_LIMITED | 429 | Too many requests | Wait and retry |

### Server Errors (5xx)

| Code | Status | Description | Resolution |
|------|--------|-------------|------------|
| INTERNAL_ERROR | 500 | Server error | Contact support |
| SERVICE_UNAVAILABLE | 503 | Maintenance | Retry later |
```

## GraphQL Documentation

### Schema Documentation

```markdown
# GraphQL Schema

## Types

### User

\`\`\`graphql
type User {
  """Unique identifier"""
  id: ID!

  """User's email address"""
  email: String!

  """Display name"""
  name: String

  """Account creation timestamp"""
  createdAt: DateTime!

  """User's orders"""
  orders(first: Int, after: String): OrderConnection!
}
\`\`\`

### Input Types

\`\`\`graphql
input CreateUserInput {
  email: String!
  name: String
  role: UserRole = USER
}
\`\`\`
```

### Query Documentation

```markdown
## Queries

### user

Fetch a single user by ID.

\`\`\`graphql
query GetUser($id: ID!) {
  user(id: $id) {
    id
    email
    name
    createdAt
  }
}
\`\`\`

**Arguments:**

| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| id | ID | Yes | User ID |

**Example:**

\`\`\`json
{
  "id": "usr_123"
}
\`\`\`

**Response:**

\`\`\`json
{
  "data": {
    "user": {
      "id": "usr_123",
      "email": "[email protected]",
      "name": "John Doe",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  }
}
\`\`\`
```

### Mutation Documentation

```markdown
## Mutations

### createUser

Create a new user account.

\`\`\`graphql
mutation CreateUser($input: CreateUserInput!) {
  createUser(input: $input) {
    user {
      id
      email
    }
    errors {
      field
      message
    }
  }
}
\`\`\`

**Input:**

\`\`\`json
{
  "input": {
    "email": "[email protected]",
    "name": "Jane Smith"
  }
}
\`\`\`

**Success Response:**

\`\`\`json
{
  "data": {
    "createUser": {
      "user": {
        "id": "usr_456",
        "email": "[email protected]"
      },
      "errors": null
    }
  }
}
\`\`\`

**Error Response:**

\`\`\`json
{
  "data": {
    "createUser": {
      "user": null,
      "errors": [
        {
          "field": "email",
          "message": "Email already exists"
        }
      ]
    }
  }
}
\`\`\`
```

## SDK Examples

### Language-Specific Examples

```markdown
## SDK Examples

### JavaScript/TypeScript

\`\`\`typescript
import { Client } from '@api/sdk'

const client = new Client({ apiKey: 'your-key' })

// List users
const users = await client.users.list({ limit: 10 })

// Create user
const user = await client.users.create({
  email: '[email protected]',
  name: 'John Doe'
})
\`\`\`

### Python

\`\`\`python
from api_sdk import Client

client = Client(api_key='your-key')

# List users
users = client.users.list(limit=10)

# Create user
user = client.users.create(
    email='[email protected]',
    name='John Doe'
)
\`\`\`

### cURL

\`\`\`bash
# List users
curl -X GET "https://api.example.com/v1/users?limit=10" \
  -H "Authorization: Bearer $API_KEY"

# Create user
curl -X POST "https://api.example.com/v1/users" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","name":"John Doe"}'
\`\`\`
```

## Integration

Used by:
- `api-doc-writer` agent

© bradtaylorsf · MIT · bradtaylorsf/alphaagent-team

Similar skills

All skills for Writing and docs →

api-documentation by other authors comes first.

api-documentation bobmatnyc api-documentation — a skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode that brings API and interface documentation patterns to the agent. It cuts 100–150 lines of repeated guidance from every agent prompt. CX Codex +1 397installs api-documentation akillness api-documentation is a Claude Code skill that generates and updates API references, quickstarts, webhook guides, and portal navigation. It runs when syncing developer docs with OpenAPI or GraphQL contracts. CX Codex +1 385installs api-reference-documentation aj-geddes api-reference-documentation — a skill that walks the agent through writing API reference docs: endpoints, auth, request and response examples, OpenAPI specs. CX Codex +1 501installs api-documentation-generator davila7 api-documentation-generator analyzes your codebase to produce API reference pages for REST and GraphQL services. Includes request payloads, status codes, and code snippets. CX Codex +1 235installs doc-api davila7 doc-api is a Claude Code command that generates API documentation directly from source code. It scans project controllers and routes to build OpenAPI specs or interactive Swagger UI. CX Codex +1 733installs api-documentation-writer OneWave-AI api-documentation-writer generates developer documentation, OpenAPI specs, and code samples for REST, GraphQL, and gRPC APIs. It structures endpoints, error formats, and rate limits. CX Codex +1 389installs api-integration-specialist Alysson Franklin api-integration-specialist — a subagent that designs REST and GraphQL APIs, documentation, SDKs and developer portals. Built for B2B architecture and internal services. ★ 1,013repo stars api-versioning-policy Samuel Berthe api-versioning-policy defines an API versioning and deprecation policy covering breaking changes, notice windows, and sunset timelines. Built for teams rolling out /v2 or deprecating endpoints. CX Codex +1 10,100installs

From the same set2

Project sponsors

Companies that keep this analytics open