API product naming & documentation generator

Purpose

Turn a technical spec or endpoint list into clean, RESTful resource names and complete reference documentation — endpoint descriptions, parameter tables, request/response examples, and error handling — that a developer can read once and integrate against without asking questions. Solves inconsistent naming, thin descriptions, and missing examples that slow API adoption and inflate support load.

When to Use

Invoke this skill when the user asks to:

• Name or rename API endpoints, resources, or methods
• Write reference documentation for a new or existing API
• Standardize inconsistent endpoint naming across a growing API surface
• Convert an OpenAPI/Swagger spec or raw endpoint list into readable developer docs
• Document request parameters, response fields, and error codes for an endpoint
• Improve developer experience or reduce integration-related support tickets for an API

Inputs Required

Before starting, collect:

• API surface: The endpoints, resources, or operations to name/document (raw list, OpenAPI spec, or feature description)
• Resource domain: What the API manages (e.g., payments, users, inventory, messaging)
• API style: REST / GraphQL / RPC — and current version if any
• Authentication method: API key / OAuth / bearer token / none
• Audience: Internal / partner / public developers, and their expected familiarity
• Existing conventions: Any naming patterns, casing, or base URL structure already in use
• Consumer language(s): Primary SDK or example language (cURL, JavaScript, Python, etc.)

If API style or example language is missing, default to REST with cURL examples and note the assumption.

Instructions

Step 1: Establish Naming Conventions

Lock the rules before naming anything, so output is internally consistent.

• Resources are nouns, plural: /invoices, /customers, /subscriptions — not /getInvoice or /invoice
• Actions come from HTTP methods, not names: GET (read), POST (create), PATCH (partial update), PUT (replace), DELETE (remove)
• Hierarchy via nesting, max 2 levels deep: /customers/{id}/invoices is fine; /customers/{id}/invoices/{id}/lines/{id}/taxes is a smell
• Casing: kebab-case or snake_case in paths, snake_case or camelCase in JSON fields — pick one and hold it
• Non-CRUD actions as sub-resources or verbs: /orders/{id}/cancel (POST) for state transitions that don't map to CRUD
• Query params for filtering/pagination: ?status=active&limit=50&cursor=... — never bake filters into the path
• If existing conventions were provided, adopt them and flag any violations rather than overriding silently.

Step 2: Name Each Resource and Endpoint

For every operation in the surface, produce:

• Resource name: The canonical noun
• Endpoint path: Full path with path parameters in {braces}
• HTTP method: Correct verb for the operation
• Operation summary: One imperative line (e.g., "Create a customer")
• Flag any name that is ambiguous, overloaded, or inconsistent with the established convention, with a suggested fix.

Step 3: Write Endpoint Descriptions

For each endpoint, write a 2–4 sentence description that answers: what it does, when a developer would call it, and any important behavior (idempotency, side effects, rate limits, async processing). Avoid restating the method name in prose — add information the path alone doesn't convey.

Step 4: Document Parameters and Fields

Produce a parameter table per endpoint with columns: Name, In (path/query/body/header), Type, Required, Description, Example. For request bodies and responses, document each field the same way. Descriptions must state constraints (min/max, enum values, format like ISO-8601) — not just "the customer's email."

Step 5: Generate Request and Response Examples

For each endpoint provide:

• A complete example request in the consumer's language, including auth header
• A realistic success response with representative values (not "string" / 0 placeholders) and the HTTP status code
• Values that are internally consistent across the example (the ID in the response matches the resource created)

Step 6: Document Errors and Edge Cases

For each endpoint list the likely error responses: status code, error code/slug, when it occurs, and how to resolve it. Cover at minimum authentication failure, validation failure, and not-found where applicable. Include a note on rate limiting and pagination behavior if relevant to the resource.

Step 7: Consistency Review

Sweep the full output for uniformity: casing, pluralization, parameter naming (user_id vs userId mixed), timestamp field conventions, and error format. Report any inconsistencies found and correct them.

Output Format

• Structure: Naming conventions section up front, then one documented block per endpoint, then a consistency review summary
• Length: 1,000–1,600 words (scales with number of endpoints)
• Format: Structured reference document — parameter tables, fenced code blocks for examples, prose only for descriptions
• Sections: Naming Conventions → Endpoint Reference (per endpoint: path + method + description + parameter table + request example + response example + errors) → Consistency Review & Flags
• Tone: Precise, developer-facing, assumes technical literacy — no marketing language, no filler

Quality Checklist

Before delivering output, verify:

• [ ] Every resource name is a plural noun and every action is expressed through the HTTP method — no verbs in paths except intentional state transitions
• [ ] Every endpoint has a description, parameter table, request example, response example, and error list
• [ ] Casing and field-naming conventions are identical across all endpoints (spot-check at least 3)
• [ ] Example values are realistic and internally consistent — no "string", 0, or lorem placeholders
• [ ] Each error entry includes a status code, a cause, and a resolution
• [ ] Any naming or convention violations found are explicitly flagged with a suggested fix

Notes

• The single biggest adoption killer is inconsistency — one endpoint using userId and another using user_id erodes trust faster than a missing feature; the consistency review exists to catch exactly this.
• Prefer boring, predictable names over clever ones. Developers should be able to guess your next endpoint before reading the docs.
• If the spec includes non-CRUD operations that don't fit REST cleanly, document them as action sub-resources and note the trade-off rather than forcing an awkward noun.
• When documenting an existing API you cannot rename, focus on description and example quality and list naming issues as a separate "future v-next" recommendation.

How to use this skill

This file is a Claude Code skill in Anthropic's standard format — markdown with YAML frontmatter at the top.

Installing in Claude Code:

• ~/.claude/skills/<folder-name>/SKILL.md — auto-loads in every session anywhere on your machine (recommended for skills you'll use across multiple projects)
• <your-project>/.claude/skills/<folder-name>/SKILL.md — auto-loads only when working in that project (recommended for project-specific skills)

Restart Claude Code or open a new session to register.

Using in Claude.ai, ChatGPT, Gemini, or other AI tools:

1. Drag this file into a new chat, or copy and paste its contents
2. Send your task or request as your next message — the AI will apply the skill where it fits

For Claude Code skill details: https://docs.anthropic.com/en/docs/claude-code/skills