К основному содержанию
скилл CX Codex

api-documentation · bradtaylorsf — скилл Claude Code: что делает, установка

Скилл api-documentation задаёт шаблоны для документации REST и GraphQL API. Он пригодится для описания эндпоинтов, схем, ошибок и примеров SDK.

MIT 1 установок ★ 8 обновлён 2026-02-05

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add bradtaylorsf/alphaagent-team --skill api-documentation -a claude-code
Открыть на GitHub

Что делает api-documentation

Скилл задаёт структуру документации REST API: метод и путь, авторизацию, параметры, тело запроса, успешный ответ и ошибки. Отдельные разделы описывают Bearer token, API key и OAuth 2.0, а также обычную и cursor-based пагинацию с примерами параметров и ответов.

Для GraphQL он предлагает документировать типы, input-типы, queries и mutations вместе с аргументами, примерами запросов и ответов. В наборе есть примеры SDK для JavaScript/TypeScript, Python и cURL. Ошибки оформляются через единый JSON с кодом, сообщением, деталями и requestId.

Скилл связан с субагентом api-doc-writer. Он рассчитан именно на REST и GraphQL, поэтому описание других API-стилей этим набором шаблонов не покрывается.

Какие задачи решает

  • описать REST-эндпоинт с параметрами и ответами
  • зафиксировать способы авторизации API
  • оформить постраничную и cursor-based пагинацию
  • задокументировать GraphQL queries и mutations
  • добавить примеры SDK для JavaScript/TypeScript, Python и cURL

Примеры запросов агенту

  • Оформи документацию REST-эндпоинта /api/v1/users/:id с параметрами, авторизацией, ответами и ошибками.
  • Опиши GraphQL mutation createUser: добавь input, успешный ответ и ошибки.
  • Добавь к документации API примеры вызовов на Python и cURL, а также раздел о пагинации.

Как установить api-documentation

1Через Skills CLI (Vercel)

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

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/api-documentation/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об api-documentation

Как установить api-documentation в Claude Code?

Выполните npx skills add bradtaylorsf/alphaagent-team --skill api-documentation -a claude-code, затем проверьте файл ~/.claude/skills/api-documentation/SKILL.md.

Что делает api-documentation?

Скилл задаёт шаблоны для REST и GraphQL API: эндпоинтов, авторизации, пагинации, ошибок, схем, queries, mutations и SDK-примеров.

Какие форматы API поддерживает api-documentation?

Он охватывает REST и GraphQL. Для REST предусмотрены обычная и cursor-based пагинация, а для GraphQL — описание типов, input-типов, queries и mutations.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Тексты и документация» →

Сначала — api-documentation от других авторов.

api-documentation bobmatnyc Скилл api-documentation для Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI и OpenCode с правилами документирования API и кодовых интерфейсов. Агент получает единый набор практик вместо повторяющихся инструкций в каждом промпте. CX Codex +1 397установок api-documentation akillness Скилл api-documentation генерирует и обновляет документацию API: справочники эндпоинтов, быстрые старты, гайды по вебхукам и навигацию портала. Запускается при синхронизации документации со схемами OpenAPI или GraphQL. CX Codex +1 385установок api-reference-documentation aj-geddes Скилл api-reference-documentation помогает агенту собрать справочник по API: эндпоинты, аутентификация, примеры запросов и ответов, спецификация OpenAPI. CX Codex +1 501установок api-documentation-generator davila7 Скилл api-documentation-generator сканирует роуты и схемы в кодовой базе и оформляет справочник к REST и GraphQL API. Готовит примеры вызовов, схемы ответов и кодов ошибок. CX Codex +1 235установок doc-api davila7 Команда doc-api для Claude Code генерирует документацию API по кодовой базе проекта. Она находит маршруты, контроллеры и схемы данных, формируя спецификации OpenAPI или интерактивный Swagger UI. CX Codex +1 733установок api-documentation-writer OneWave-AI Скилл api-documentation-writer формирует документацию для REST, GraphQL или gRPC API. Он создаёт спецификации OpenAPI, примеры запросов на нескольких языках и описания ошибок с лимитами. CX Codex +1 389установок api-integration-specialist Alysson Franklin Субагент api-integration-specialist для проектирования REST и GraphQL API, документации, SDK и порталов разработчика. Заточен под B2B-архитектуру и внутренние сервисы. ★ 1 013звёзд репо api-versioning-policy Samuel Berthe Скилл api-versioning-policy помогает составить регламент версионирования и вывода API из эксплуатации. Пригодится при подготовке к ломающим изменениям или переходу на схему /v2. CX Codex +1 10 100установок

Из того же набора2

Спонсоры проекта

Компании, которые помогают держать аналитику открытой