Build or update the BlueBubbles external channel plugin for Moltbot (extension package, REST...
API Documentation
1
0
# 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 |
|---|---|---|---|
| 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
Links
- Website: packs.sh
- Registry: github.com/tunajam/packs-registry
- API: github.com/tunajam/packs-api
License
MIT
# Related Skills
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Manage Trello boards, lists, and cards via the Trello REST API.
Add a new endpoint or endpoints to Ghost's Admin API at `ghost/api/admin/**`.
# 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.