---
# YAML FRONTMATTER
name: my-skill-name
description: "What this skill does (1 sentence)"
version: "1.0.0"
author: "Your Name"
triggers:
  - keyword1
  - keyword2
  - keyword3
category: technical # or creative, business, personal, system
related_skills:
  - other-skill-1
  - other-skill-2
---

# MARKDOWN CONTENT

## Purpose

What this skill teaches Claude.

## When to Use

Specific scenarios where this skill applies.

## Core Patterns

The actual knowledge, with code examples.

## Anti-Patterns

What NOT to do.

## Examples

Real, working examples.

Level 1: Frontmatter (~50 lines)
  → Claude scans to decide relevance

Level 2: Main content (~450 lines)
  → Core patterns and examples

Level 3: Resources folder (unlimited)
  → Deep reference material, loaded on demand

~/.claude/skills/your-skill/
├── SKILL.md              # Core instructions (Level 1)
├── CLAUDE.md             # Auto-loaded context (Level 2)
└── resources/            # Deep references (Level 3)
    ├── examples.md
    ├── patterns.md
    └── advanced.md

mkdir -p ~/.claude/skills/api-documentation
cd ~/.claude/skills/api-documentation

---
name: api-documentation
description: "Best practices for writing clear, complete API documentation"
version: "1.0.0"
author: "Your Name"
triggers:
  - api docs
  - api documentation
  - document api
  - endpoint documentation
  - swagger
  - openapi
category: technical
related_skills:
  - technical-writing
  - rest-api-design
---

# API Documentation Skill

## Purpose

This skill teaches Claude how to write API documentation that developers actually want to read. Focus on clarity, completeness, and practical examples.

## When to Use

Activate this skill when:

- Writing documentation for REST APIs
- Creating OpenAPI/Swagger specs
- Documenting endpoint behavior
- Writing API reference guides

## Core Patterns

### Pattern 1: The Endpoint Template

Every endpoint should document:

````markdown
## `POST /api/users`

Create a new user account.

### Request

**Headers:**
| Header | Required | Description |
|--------|----------|-------------|
| `Authorization` | Yes | Bearer token |
| `Content-Type` | Yes | `application/json` |

**Body:**

```json
{
  "email": "user@example.com",
  "name": "John Doe",
  "role": "member"
}
```
````

**Parameters:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `email` | string | Yes | Valid email address |
| `name` | string | Yes | Display name (2-100 chars) |
| `role` | string | No | Default: "member" |

### Response

**Success (201 Created):**

```json
{
  "id": "usr_abc123",
  "email": "user@example.com",
  "name": "John Doe",
  "role": "member",
  "created_at": "2026-01-27T10:00:00Z"
}
```

**Errors:**
| Code | Description |
|------|-------------|
| 400 | Invalid request body |
| 409 | Email already exists |
| 401 | Invalid or missing token |

### Example

```bash
curl -X POST https://api.example.com/api/users \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "name": "John Doe"}'
```

## Errors

### 400 Bad Request

**When:** Request body is malformed or missing required fields.

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": [{ "field": "email", "issue": "Must be valid email format" }]
  }
}
```

### Pattern 3: Authentication Section

```markdown
## Authentication

All API requests require a Bearer token in the Authorization header:

```bash
Authorization: Bearer YOUR_API_KEY

POST /api/auth/refresh

## Anti-Patterns

### Don't: Assume Context

❌ Bad:

✅ Good:

### Don't: Skip Error Cases

❌ Bad: Only documenting the happy path
✅ Good: Every endpoint lists possible errors

### Don't: Use Placeholder Data

❌ Bad: `"id": "xxx"`
✅ Good: `"id": "usr_abc123"` (realistic format)

## Examples

### Complete Endpoint Documentation

[See resources/examples.md for full examples]

## Related Skills

- `technical-writing` - General technical writing patterns
- `rest-api-design` - API design principles

{
  "rules": [
    {
      "skill": "api-documentation",
      "triggers": {
        "keywords": [
          "api docs",
          "api documentation",
          "document api",
          "endpoint",
          "swagger",
          "openapi"
        ],
        "filePatterns": ["**/api/**/*.md", "**/docs/api/**/*"],
        "commands": []
      },
      "priority": "medium",
      "maxConcurrent": 3
    }
  ]
}

# Open Claude Code
claude

# Say something that should trigger the skill
"Help me document this REST API endpoint for user creation"

# Claude should now have API documentation knowledge

## When to Use

Activate this skill when:

- User mentions [specific keywords]
- Working with [specific file types]
- Task involves [specific domain]

Do NOT use when:

- [Situation where skill doesn't apply]

### Pattern: Rate Limiting Headers

❌ Abstract:
"Include rate limit headers in responses"

✅ Concrete:

```http
HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1706356800
```

### 3. Include Anti-Patterns

Show what NOT to do. This prevents Claude from making common mistakes:

```markdown
## Anti-Patterns

### Don't: Over-Engineer Simple Endpoints

❌ Bad:
```typescript
class UserCreationRequestValidatorFactory {
  // 50 lines of abstraction
}

function validateUser(data) {
  // Direct validation
}

### 4. Link Related Skills

Help Claude know when to combine skills:

```markdown
## Related Skills

- `test-driven-development` - When writing tests for the API
- `security-best-practices` - For authentication patterns
- `typescript-patterns` - If using TypeScript SDK

## Quick Reference

| Method | Endpoint     | Description    |
| ------ | ------------ | -------------- |
| GET    | `/users`     | List all users |
| POST   | `/users`     | Create user    |
| GET    | `/users/:id` | Get user by ID |
| PUT    | `/users/:id` | Update user    |
| DELETE | `/users/:id` | Delete user    |

{
  "rules": [
    {
      "skill": "skill-name",
      "triggers": {
        "keywords": ["word1", "word2"],
        "filePatterns": ["**/*.tsx", "src/components/**/*"],
        "commands": ["/article-creator", "/spec"]
      },
      "priority": "high", // high, medium, low
      "maxConcurrent": 3 // Max skills loaded at once
    }
  ]
}

{
  "triggers": {
    "keywords": ["react"], // OR
    "filePatterns": ["*.tsx"], // OR
    "commands": ["/spec"] // Any of these triggers activation
  }
}

your-project/
├── .claude/
│   └── skills/
│       └── your-skill/
│           └── SKILL.md
├── src/
├── package.json
└── ...