How to use the API Design Patterns agent skill (api-design)

What the api-design skill makes the agent do

An agent skill is a folder with a SKILL.md file that describes how to handle a certain kind of task. When the skill is active, the agent follows the conventions in that file instead of its general defaults. This skill covers REST API design: resource naming, HTTP status codes, response formats, pagination, filtering, sorting, search, authentication patterns, versioning and rate limiting.

In practice, the agent uses these rules to design new endpoints or to check an existing API contract and suggest fixes. The skill's own guidance says to use plural, lowercase, kebab-case resource names, for example /api/v1/team-members, and to avoid verbs and snake_case in URLs.

• Resource names: plural nouns in kebab-case, with nested paths for ownership such as /api/v1/users/:id/orders
• Status codes: 201 with a Location header for created resources, 400 or 422 with field-level details for validation failures, 429 for rate limits
• Responses: a data envelope, collection responses with meta and links, and a structured error object with code, message and details
• Pagination: offset-based for admin screens and search, cursor-based for feeds and large or public datasets
• Filtering and sorting: bracket operators such as price[gte], comma-separated values and a leading minus for descending sort

How do you install the api-design skill?

There are two ways to install it. Download the ZIP from this page and unzip it into one of these folders: ~/.claude/skills/ to make it available in all your projects, or the .claude/skills/ folder inside a single project to limit it to that project.

If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the skill there. Either way, the folder should contain the files listed for this skill: SKILL.md and agents/openai.yaml.

• Option A (all projects): unzip into ~/.claude/skills/
• Option B (one project): unzip into the .claude/skills/ folder of that project
• Option C (Claude apps): Settings, then Capabilities, then Skills, then upload

How do you trigger the skill with natural requests?

You do not need a special command. The skill describes when it applies: designing or reviewing REST endpoints, resource names, status codes, pagination or versioning. Ask in those terms and the agent should load it. Naming the skill directly in your request can also help.

Give the agent your endpoints, resource list or existing contract, and say what you want: a design proposal, a review, or a list of problems.

• Design new endpoints for an orders feature with cancel and refund actions
• Review this list of routes for naming and status code mistakes
• Should this search endpoint use offset or cursor pagination?
• Plan how to version our public API before the first partner release
• Use the api-design skill to check these error responses

What does a typical result look like?

Suppose you paste in routes such as /api/v1/getUsers and /api/v1/team_members. Based on the skill's naming rules, the agent should flag the verb in the URL and the snake_case, and suggest /api/v1/users and /api/v1/team-members. It can also suggest that a cancel action such as POST /api/v1/orders/:id/cancel is an acceptable use of a verb, since the skill allows verbs for actions that do not map to CRUD.

For error handling, the skill's common mistakes section says to avoid returning 200 with an error body. The agent should instead suggest the matching HTTP status and a structured error like the example in the skill, with a code, a message and field-level details for validation failures.

What does the skill need, and what should you watch for?

The skill lists no requirements. It does not run scripts and does not use the network, so it only supplies written guidance to the agent. Your agent still reads your code or contracts as you share them, so only share what you are comfortable sharing.

The skill is REST-specific. It does not address GraphQL or gRPC. If your team already has an internal API standard, the skill's defaults may conflict with it, so tell the agent which standard to follow or leave the skill off for that work.

• Requirements: none listed
• Runs scripts: no
• Uses network: no
• Not for GraphQL or gRPC
• Can conflict with an established internal API standard

Tips for getting better results

Give the agent real context. Paste the full route list, example request and response bodies, and the clients that consume the API. The skill's advice on pagination and versioning depends on how the data grows and who depends on it.

Ask for a review in stages: naming first, then status codes, then responses. This makes the changes easier to check. The rate-limiting guidance in the skill describes the X-RateLimit headers and a 429 response with Retry-After, so ask about those specifically if you need them.

• Paste real routes and bodies, not summaries
• Name your existing conventions if you have any
• Review in stages: naming, then status codes, then responses
• Check the agent's suggested status codes against your framework's behaviour