API Documentation

by @tunajam in Web & API

# Install this skill:

npx skills add tunajam/packs

Or install specific skill: npx add-skill https://github.com/tunajam/packs/tree/main/registry/api-documentation

# Description

User created

# SKILL.md

API Documentation

Write clear, useful API documentation.

When to Use

Documenting new endpoints
Improving existing API docs
Creating API reference guides
Generating OpenAPI specs

Documentation Structure

Endpoint Documentation

## Create User

Creates a new user account.

### Request

`POST /api/users`

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

**Body**
```json
{
  "email": "[email protected]",
  "name": "Alice Smith",
  "role": "member"
}

Field	Type	Required	Description
email	string	Yes	Valid email address
name	string	Yes	Full name (2-100 chars)
role	string	No	One of: admin, member. Default: member

Response

Success (201 Created)

{
  "id": "usr_abc123",
  "email": "[email protected]",
  "name": "Alice Smith",
  "role": "member",
  "createdAt": "2024-01-15T10:30:00Z"
}

Errors

Status	Code	Description
400	VALIDATION_ERROR	Invalid request body
401	UNAUTHORIZED	Missing or invalid token
409	EMAIL_EXISTS	Email already registered

Example

curl -X POST https://api.example.com/api/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "name": "Alice"}'

## What to Document

### For Each Endpoint

1. **Description** - What it does, when to use it
2. **URL and method** - `POST /api/users`
3. **Authentication** - Required auth type
4. **Parameters** - Path, query, header, body
5. **Request body** - Schema with types and validation
6. **Response** - Success and error responses
7. **Examples** - curl commands, request/response pairs

### For the API Overall

1. **Overview** - What the API does
2. **Authentication** - How to get and use tokens
3. **Rate limiting** - Limits and headers
4. **Versioning** - How versions work
5. **Error handling** - Standard error format
6. **Pagination** - How to paginate results
7. **Changelog** - Breaking changes

## Guidelines

### Be Specific

```markdown
// ❌ Vague
Returns user data.

// ✅ Specific
Returns the user's profile including name, email, and role.
Does not include sensitive fields like password hash.

Show Real Examples

// ❌ Abstract
Returns a user object.

// ✅ Concrete
```json
{
  "id": "usr_abc123",
  "name": "Alice Smith",
  "email": "[email protected]"
}

Document Errors

| Status | When |
|--------|------|
| 400 | Invalid request body or parameters |
| 401 | Missing or expired token |
| 403 | User lacks permission |
| 404 | Resource not found |
| 429 | Rate limit exceeded |
| 500 | Server error |

Include Edge Cases

What happens with empty arrays?
What about null vs missing fields?
Behavior at pagination boundaries?
Rate limit exceeded response?

OpenAPI/Swagger

openapi: 3.0.0
info:
  title: My API
  version: 1.0.0

paths:
  /users:
    post:
      summary: Create a user
      operationId: createUser
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/ValidationError'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          example: usr_abc123
        email:
          type: string
          format: email
        name:
          type: string

Checklist

[ ] Every endpoint documented
[ ] Real example requests and responses
[ ] All parameters listed with types
[ ] Error responses documented
[ ] Authentication explained
[ ] Rate limits documented
[ ] Curl examples provided

# README.md

🎒 packs

Skills for AI agents. One command.

brew install packs

Quick Start

# Browse packs in the TUI
packs

# Search for skills
packs find "commit message"

# Install from registry
packs get commit-message

# Install from GitHub
packs get @blader/humanizer

# Pipe to clipboard
packs get commit-message | pbcopy

What Are Packs?

Packs are reusable instructions for AI agents. Three types:

Type	File	Purpose
Skill	`SKILL.md`	How to do X (procedural)
Context	`CONTEXT.md`	What is X (knowledge)
Prompt	`PROMPT.md`	Ready-to-use instructions

Commands

`packs` — TUI Browser

Launch the interactive browser to discover and install packs.

  🎒 packs                                      [?] help [q] quit
  ────────────────────────────────────────────────────────────────
  [1] All  [2] Skills   [3] Contexts   [4] Prompts
  ────────────────────────────────────────────────────────────────

> 📦 commit-message          1.0.0  ★ 892   Generate conventional commits
  📦 humanizer               1.0.0  ★ 543   Remove AI patterns from writing
  📚 react-query             2.1.0  ★ 1247  React Query patterns and best...

Keys: ↑↓ navigate · ⏎ details · g quick install · / search · 1-4 filter

`packs get <pack>` — Install

# From packs.sh registry
packs get commit-message
packs get [email protected]      # specific version

# From GitHub (@ shorthand)
packs get @user/repo/skill
packs get @blader/humanizer         # root-level skill

# Custom install location
packs get commit-message -o ./skills/

# Output to stdout (for piping)
packs get commit-message | pbcopy

Auto-detection: Installs to the right place based on your agent:
- Claude Code → ~/.claude/skills/
- Clawdbot → ./skills/
- Codex → ~/.codex/skills/
- Generic → ~/.packs/skills/

`packs find [query]` — Search

packs find                          # list popular
packs find "commit"                 # search by keyword
packs find --type context           # filter by type
packs find --json                   # JSON output for agents

`packs info <pack>` — Details

packs info humanizer
packs info --json react-query

`packs submit <ref>` — Publish

packs submit @myname/my-skills/commit-helper

Requires a pack.yaml in your GitHub repo:

name: commit-helper
version: 1.0.0
type: skill
description: Generate helpful commit messages
author: myname
license: MIT
tags:
  - git
  - commits

For AI Agents

Packs is designed to be used by AI agents, not just humans.

# JSON output for parsing
packs find --json "testing" | jq '.[0].name'

# Machine-readable help
packs get --help

# Non-interactive install
packs get commit-message --install

Example agent workflow:

User: "Help me write better commit messages"

Agent thinks: I should check if there's a skill for this
Agent runs: packs find --json "commit message"
Agent gets: [{"name": "commit-message", "description": "Generate conventional..."}]
Agent runs: packs get commit-message
Agent reads: ~/.claude/skills/commit-message/SKILL.md
Agent follows the skill instructions

Configuration

packs config              # show current config
packs config path         # config file location
packs config reset        # reset to defaults

Config file: ~/.packs/config.yaml

registry: https://api.packs.sh
telemetry: true
# skills_dir: ~/.packs/skills  # override auto-detection

Environment variables:
- PACKS_REGISTRY — override registry URL
- PACKS_SKILLS_DIR — override skills directory
- PACKS_NO_TELEMETRY=1 — disable telemetry

Creating Packs

See the pack creation guide or use the template:

my-skill/
├── pack.yaml       # metadata
├── SKILL.md        # instructions
└── README.md       # optional docs

License

MIT

# Supported AI Coding Agents

This skill is compatible with the SKILL.md standard and works with all major AI coding agents:

⚡ Amp 🚀 Antigravity 🤖 Claude Code 🦀 Clawdbot 📝 Codex ▶️ Cursor 🤖 Droid 💎 Gemini CLI 🐙 GitHub Copilot 🪿 Goose 📊 Kilo Code 🔧 Kiro CLI 💻 OpenCode 🦘 Roo Code 🌲 Trae 🏄 Windsurf

Learn more about the SKILL.md standard and how to use these skills with your preferred AI coding agent.

API Documentation

# Description

# SKILL.md

API Documentation

When to Use

Documentation Structure

Endpoint Documentation

Response

Example

Show Real Examples

Document Errors

Include Edge Cases

OpenAPI/Swagger

Checklist

# README.md

🎒 packs

Quick Start

What Are Packs?

Commands

packs — TUI Browser

packs get <pack> — Install

packs find [query] — Search

packs info <pack> — Details

packs submit <ref> — Publish

For AI Agents

Configuration

Creating Packs

Links

License

# Related Skills

# Supported AI Coding Agents

Confirm

Submit a Skill

`packs` — TUI Browser

`packs get <pack>` — Install

`packs find [query]` — Search

`packs info <pack>` — Details

`packs submit <ref>` — Publish