rubenzarroca/sdd-plugin/sdd-api-docs

/sdd:api-docs — Fetch and cache external API documentation

You are fetching real documentation for an external API/service and caching it locally so that all downstream SDD commands (plan, implement) use verified API contracts instead of assumptions from training data.

Why this exists: Claude's training data may contain outdated, incomplete, or incorrect API documentation. When building integrations, this causes code that looks correct but fails at deploy time. This skill forces a documentation-first approach: read the real docs, cache them locally, and use them as the single source of truth.

Step 1: Parse arguments

Parse from $ARGUMENTS:

• Service name (required): kebab-case identifier (e.g., stripe, bigquery, holded-api)
• Docs URL (optional): direct URL to the API documentation

If no service name is provided, ask: "Which external service do you need to document? Give me the name and optionally the URL to its API docs."

Step 2: Check for existing cache

Check if .sdd/api-docs/{service-name}.json already exists by calling sdd_api_list with the service name.

If it exists, report:

• When it was fetched (fetched_at)
• How many endpoints are cached
• Ask: "Documentation for {service} is already cached (fetched {date}). Do you want to refresh it or keep the current version?"

If the user wants to keep it, stop.

Step 3: Locate documentation

If a docs URL was provided:

Use WebFetch to read the documentation page. If the page is large or paginated, fetch the most relevant sections:

1. Authentication / Authorization
2. API reference / Endpoints
3. Rate limits
4. Error codes
5. SDKs / Libraries

If no URL was provided:

Use WebSearch to find the official API documentation:

• Search: "{service-name}" API documentation site:docs OR site:developer
• Identify the official documentation site (prefer official docs over third-party tutorials)
• Use WebFetch on the official docs pages

Multi-page documentation:

Most API docs span multiple pages. Follow this strategy:

1. Fetch the main API reference/overview page first
2. Identify the endpoints relevant to the project (cross-reference with the feature spec if one exists in .sdd/state.json)
3. Fetch individual endpoint documentation pages as needed
4. Stop when you have enough detail for the endpoints the project will actually use — do NOT try to document the entire API

Step 4: Extract and structure

From the fetched documentation, extract and organize into this structure:

{
  "service": "{service-name}",
  "base_url": "{base API URL}",
  "auth": {
    "type": "{bearer|api_key|oauth2|basic|custom}",
    "header": "{header name, e.g., Authorization}",
    "notes": "{any important auth details — token format, scopes, etc.}"
  },
  "rate_limits": {
    "rpm": null,
    "rps": null,
    "notes": "{rate limit details from the docs}"
  },
  "endpoints": [
    {
      "method": "{GET|POST|PUT|PATCH|DELETE}",
      "path": "{/endpoint/path}",
      "purpose": "{one-line description}",
      "request": {},
      "response": {},
      "errors": [
        { "code": 400, "meaning": "{when this happens}" }
      ]
    }
  ],
  "sdk": {
    "package": "{npm/pip package name}",
    "version": "{recommended version}",
    "notes": "{installation, initialization}"
  },
  "fetched_at": "{ISO 8601 timestamp}",
  "source_url": "{URL where docs were fetched from}"
}

Extraction rules:

1. Request/response shapes must come from the docs, not from memory. If the docs show a field called amount_in_cents, use that — do not normalize to amount. The whole point is to capture the real API contract.

1. Include all error codes documented. Error handling is where assumptions cause the most deploy failures.

1. Capture auth details precisely. Token format, required headers, scopes, API key placement (header vs query param) — these details matter.

1. Rate limits matter for architecture. If the docs mention rate limits, capture them. They affect retry logic, caching decisions, and queue design.

1. Only document endpoints the project needs. If the feature spec exists, cross-reference it. A project using Stripe for payments doesn't need the Stripe Connect endpoints documented.

1. When the docs are ambiguous or unclear, note it in the notes field rather than guessing. Example: "notes": "Docs unclear on whether pagination is cursor-based or offset-based. Verify with a test call."

Step 5: Save the cache

Ensure .sdd/api-docs/ directory exists. Save the structured JSON to .sdd/api-docs/{service-name}.json.

Step 6: Verify with MCP

Call sdd_api_list with the service name to verify the cache was saved correctly. Report:

API documentation cached for {service-name}:
  Source: {source_url}
  Auth: {auth.type}
  Endpoints: {N} documented
  Rate limits: {summary or "not documented"}
  SDK: {package@version or "none"}
 
Cached at: .sdd/api-docs/{service-name}.json
 
This documentation will be used by:
  - /sdd:plan — to verify external dependencies before planning
  - /sdd:implement — to load exact API contracts when building integration tasks
 
To refresh: /sdd:api-docs {service-name} [new-url]

Step 7: Show endpoint index

List all cached endpoints in a compact table:

| Method | Path | Purpose |
|--------|------|---------|
| POST | /charges | Create a new charge |
| GET | /charges/:id | Retrieve a charge |

Ask: "Are these the endpoints you'll need, or should I fetch docs for additional ones?"

If the user requests additional endpoints, go back to Step 3 targeting those specific endpoints, then merge into the existing cache file.

Restrictions

• Do NOT invent or assume API details. Every field in the output must come from the fetched documentation. If something isn't in the docs, leave it as null or omit it — never fill it from training data.
• Do NOT modify any project source code. This command produces only the cache file.
• Do NOT read project source code. Only read state.json (to cross-reference feature specs) and the external documentation.
• Context budget: the fetched docs may be large. Extract what's needed and discard the rest. The structured JSON is the deliverable, not a copy of the full docs.
• If WebFetch fails (e.g., docs behind auth wall, CORS issues), report clearly: "Could not fetch docs from {url}. You may need to provide the documentation manually. Create .sdd/api-docs/{service}.json with the structure shown above, or paste the relevant docs and I'll structure them for you."

$ARGUMENTS