Context Hub skill for creating API documentation (DOC.md) for arbitrary APIs

context-hub_cli_skills_create-api-docs_SKILL.md

name	description
create-api-docs	Use this skill when the user wants to create Context Hub API documentation (DOC.md) for an API, SDK, or library — either for contributing to the public registry or for private/internal use. This covers creating the directory structure, frontmatter, and LLM-optimized content for any arbitrary API.

Create API Docs for Context Hub

When the user wants to create a Context Hub doc for an API, SDK, or library, follow this process to produce well-structured DOC.md files that agents can consume.

Step 1 — Gather information

Ask the user for the following (skip any they've already provided):

1. API/SDK name — e.g. "Stripe", "Twilio", "our internal billing API"
2. Author/org name — the directory prefix, e.g. stripe, mycompany
3. Entry name — short slug for the doc, e.g. api, sdk, payments
4. Languages — which language variants to create: python, javascript, or both
5. SDK/package version — the current version on npm/pypi (e.g. 4.2.0)
6. Source type — official (from the API provider), maintainer (active maintainer), or community
7. Where to put it — content/ for public contribution, or a custom path for private use

If the user has existing API docs, an OpenAPI spec, or a URL to reference, ask them to share it so you can use it as source material.

Step 2 — Create the directory structure

Single-language doc

<author>/docs/<entry-name>/DOC.md

Multi-language doc

<author>/docs/<entry-name>/python/DOC.md
<author>/docs/<entry-name>/javascript/DOC.md

With reference files (optional, for longer docs)

<author>/docs/<entry-name>/python/DOC.md
<author>/docs/<entry-name>/python/references/
    auth.md
    errors.md
    advanced.md

Step 3 — Write the DOC.md

Every DOC.md must start with this YAML frontmatter:

---
name: <entry-name>
description: "<Short description of what this doc covers>"
metadata:
  languages: "<python|javascript>"
  versions: "<package-version>"
  revision: 1
  updated-on: "<YYYY-MM-DD>"
  source: <official|maintainer|community>
  tags: "<comma,separated,tags>"
---

Content structure — use these exact sections

Write the content using these sections in order. Use the heading names as written. You may skip a section only if it truly does not apply (e.g. "Models / Resources" for a library with no such concept). Do NOT rename sections or split them into multiple sub-sections — keep the top-level structure flat.

# <API Name> <Language> SDK Coding Guidelines

## Golden Rule
State the correct package name, install command, and import pattern.
Warn against common wrong package names or deprecated imports.
This is the ONLY place install commands should appear — do not repeat
them in a separate Installation section.

## Initialization
Show how to create a client/instance. Cover API key or auth setup.
Recommend environment variables over hardcoded keys. Include a
complete, minimal working example (install → import → init → one call).

## Core Operations
Cover the 3-5 most common operations with complete, runnable code examples.
Each example should show:
- The function call with realistic parameters
- The response shape
- Error handling if non-obvious
Name this section "Core Operations" even if you organize by sub-headings
within it (e.g. ### Creating a resource, ### Listing resources).

## Error Handling
Show how errors surface (exceptions, error codes, response shapes) and
the correct way to handle them. If the API has specific error codes or
error types, list the most common ones.

## Key Patterns
Cover other important patterns relevant to this API: pagination, streaming,
retries, webhooks, rate limiting, etc. Only include what applies — skip
this section entirely if there are no notable patterns beyond basic usage.

## Common Mistakes
List 3-5 things agents frequently get wrong with this API.

## Models / Resources / Endpoints (if applicable)
List current model names, resource types, or endpoint paths.

Depth balance

Each section should be roughly proportional to how often an agent will need it. Use this as a guide:

• Golden Rule + Initialization: ~15% of the doc (brief, get the agent coding fast)
• Core Operations: ~40% (this is the main value — invest here)
• Error Handling: ~15%
• Key Patterns + Common Mistakes + Models: ~30% combined

If any single topic (e.g. session management, auth flows, advanced config) grows beyond ~60 lines, move the advanced parts to a reference file and link to it. The main DOC.md should cover the common case; reference files cover depth.

Writing guidelines

• Be direct. No introductions, marketing, or "In this guide we will..."
• Show code first. A working example beats a paragraph of explanation.
• Cover the 90% case. Don't exhaustively document every option.
• Keep the main DOC.md under 500 lines. Move advanced content to reference files.
• Use real values in examples (realistic parameter names, plausible responses).
• Specify exact versions of packages, models, and API endpoints.
• Don't repeat information. If the install command is in the Golden Rule, don't show it again.

Step 4 — Create reference files (if needed)

If the doc exceeds ~400 lines, split advanced content into reference files:

references/
  auth.md          # Advanced authentication patterns
  errors.md        # Error codes and handling
  advanced.md      # Advanced features, edge cases
  migration.md     # Migration from older versions

Reference files don't need frontmatter. They are plain markdown. They are fetched with chub get <id> --file references/auth.md or chub get <id> --full.

Step 5 — Validate (mandatory)

After writing all files, you MUST run the validator. Do not skip this step.

chub build <content-dir> --validate-only --json

The validator checks:

• name exists in frontmatter (error if missing)
• metadata.languages exists for docs (error if missing)
• metadata.versions exists for docs (error if missing)
• description exists (warning if missing)
• metadata.source exists (warning if missing, defaults to community)
• No duplicate entry IDs

If the command exits with a non-zero code, there are errors. Read the output, fix the DOC.md files, and re-run until validation passes with zero errors. Address warnings too — they indicate missing fields that should be present.

Once validation passes, confirm the counts match what you created (e.g. if you wrote 2 DOC.md files, the output should show "docs": 2).

Example — complete single-language DOC.md

---
name: payments
description: "Acme Payments API for processing charges, refunds, and subscriptions"
metadata:
  languages: "python"
  versions: "3.1.0"
  revision: 1
  updated-on: "2026-03-10"
  source: community
  tags: "acme,payments,billing,api"
---

# Acme Payments Python SDK

## Golden Rule
Always use the official `acme-payments` package from PyPI.

**Install:** `pip install acme-payments`
**Import:** `from acme import PaymentsClient`

## Initialization

import os
from acme import PaymentsClient

client = PaymentsClient(api_key=os.environ["ACME_API_KEY"])

## Core Operations

### Create a charge

charge = client.charges.create(
    amount=2000,        # in cents
    currency="usd",
    source="tok_visa",
    description="Order #1234",
)
print(charge.id)  # "ch_abc123"

### Refund a charge

refund = client.refunds.create(charge_id="ch_abc123", amount=500)

## Error Handling

from acme.errors import AcmeError, CardDeclinedError

try:
    charge = client.charges.create(amount=2000, currency="usd", source="tok_visa")
except CardDeclinedError as e:
    print(f"Card declined: {e.decline_code}")
except AcmeError as e:
    print(f"API error {e.code}: {e.message}")

## Common Mistakes
1. Passing amount in dollars instead of cents
2. Not handling idempotency keys for retries
3. Using test keys in production

Quick reference

Languages supported	python, javascript
Frontmatter fields	name, description, metadata.languages, metadata.versions, metadata.revision, metadata.updated-on, metadata.source, metadata.tags
Source values	official, maintainer, community
Max DOC.md length	~500 lines (use references for more)
Validate command	chub build <dir> --validate-only