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
npx skills add bradtaylorsf/alphaagent-team --skill api-documentation -a claude-codeWhat 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/:idwith its parameters, auth, responses, and errors. - Write GraphQL documentation for the
createUsermutation, 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-code2Manually: put the files in place
~/.claude/skills/api-documentation/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/api-documentation/
1Skills CLI (Vercel)
npx skills add bradtaylorsf/alphaagent-team --skill api-documentation -a codex2Manually: put the files in place
.agents/skills/api-documentation/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add bradtaylorsf/alphaagent-team --skill api-documentation -a cursor2Manually: put the files in place
.cursor/skills/api-documentation/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install bradtaylorsf/alphaagent-team plugins/aai-docs/skills/api-documentation2Manually: put the files in place
.github/skills/api-documentation/SKILL.md1Skills CLI (Vercel)
npx skills add bradtaylorsf/alphaagent-team --skill api-documentation -a gemini-cli2Platform CLI
gemini skills install https://github.com/bradtaylorsf/alphaagent-team --path plugins/aai-docs/skills/api-documentationManually: put the files in place
.devin/skills/api-documentation/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add bradtaylorsf/alphaagent-team --skill api-documentation -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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.