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

What the api-design skill makes the agent do

A skill is a folder containing a SKILL.md file with instructions the agent reads when a task matches. This one is a set of REST design conventions. When it is active, the agent uses rules such as writing resource names as plural, lowercase, kebab-case nouns, returning 201 Created with a Location header after a POST, and returning a consistent error object with a code, a message and optional field details.

The skill also covers offset versus cursor pagination, filter and sort syntax, sparse field sets, bearer tokens and API keys, rate limit headers and tiers, and a versioning policy. It does not run code or contact any service. It only shapes how the agent reasons and writes about API design.

Install the api-design skill from the ZIP

Download the ZIP for this skill from this page and unzip it. The skill is a single file, SKILL.md. Put the unzipped folder in one of two places: your user skills folder at ~/.claude/skills/, or a project-specific folder at .claude/skills/ inside your project. Use the user folder if you want the skill available everywhere, and the project folder if you want it only for one codebase.

If you use the Claude apps instead of files on disk, open Settings, go to Capabilities, and upload the skill under Skills.

• Personal: ~/.claude/skills/api-design/
• Per project: .claude/skills/api-design/ inside the project
• Claude apps: Settings → Capabilities → Skills, then upload

Trigger the skill with natural requests

You do not need a special command. The skill is meant to activate when your request matches its use cases, which the source lists as designing a new API endpoint, reviewing an existing API contract, adding pagination, filtering or sorting, implementing error handling, planning a versioning strategy, or building a public or partner-facing API.

Name the API work clearly and include the detail that matters, such as the resource, the client type or the problem you are solving. Vague requests like 'make it better' are less likely to match.

• Design endpoints for a team-members resource with create, update and cancel actions.
• Review this OpenAPI-style list of endpoints for naming and status code consistency.
• Add cursor pagination to our orders endpoint, which feeds an infinite scroll feed.
• Plan how we retire v1 of our public API without breaking partners.

Examples of what the agent produces

For a request to add a cancel action to orders, the agent should suggest POST /api/v1/orders/:id/cancel, since the source lists this as the pattern for actions that do not map to CRUD, and should avoid verbs in the base URL. For a request about a missing record, it should return 404 with a structured error body rather than 200 with an error flag.

For a request about a list endpoint, the agent will typically propose the source's collection envelope with data, meta and links, and will explain the trade-off between offset pagination, which supports jumping to page N, and cursor pagination, which stays consistent under concurrent inserts.

What you need before using it

The skill lists no requirements. It does not run scripts and does not use the network, so there is nothing to install beyond the skill file itself. You still need a working agent environment that supports skills, and enough API context in your request for the advice to be useful.

Because the skill is a reference, its output is only as accurate as the details you give it. Share your actual endpoints, data sizes and client types when you can.

• No additional packages or services are listed
• No scripts are run by the skill
• No network access is used by the skill

Safety notes on scripts, network and security

The skill is a text guide. According to its listing, it runs no scripts and uses no network, so it cannot send your API data anywhere on its own. Review the contents of SKILL.md after unzipping if you want to confirm this yourself.

The examples cover authentication and rate limiting only in general terms. The source's own guidance is that they are general patterns, so treat authentication design, token handling and rate limit values as items to check with a security review before a production release.

• Do not paste real secrets or live API keys into requests
• Have a security review for production authentication and rate limiting
• Check any numeric limits (for example 100/min or 1000/min) against your own traffic and business needs

Tips for getting better results

Give the agent the existing conventions in your codebase. The skill's advice is general, so if your team already uses a different error format or pagination style, say so and ask the agent to reconcile the two rather than replace yours silently.

Ask for a review against the skill's checklists. The source's bad-versus-good examples, such as getUsers versus users, team_members versus team-members, and 200 for every response, make a good basis for a consistency pass over an existing contract.

• State whether the API is public, partner-facing or internal, since the skill recommends different defaults
• Ask for both the URL design and the status codes so they stay consistent
• For versioning, describe which changes are breaking, such as removing or renaming a field