Skip to content
Get packs

Guide · Agent skill

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

Updated · written with AI from the project's own documentation and checked against our catalogue data

The api-design skill is a reference guide that teaches an AI agent the REST API conventions used in production APIs: how to name resources, which HTTP status codes to return, how to shape success and error responses, and how to paginate, filter and sort collections. It is written for backend developers and teams who review API contracts. After this guide you will know what the skill changes about the agent's behaviour, how to install it from the ZIP, and how to ask for work that triggers it.

API Design Patternsaffaan-m/ECC · MIT

Quick start

  1. 1Download the ZIP. Get the api-design skill ZIP from this page and unzip it.
  2. 2Place the folder. Move the unzipped folder to ~/.claude/skills/ for personal use or to .claude/skills/ in your project.
  3. 3Or upload in the apps. In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the skill.
  4. 4Make a request. Ask for endpoint design, an API review, or pagination, filtering or error handling help in plain language.
  5. 5Check the output. Compare suggested URLs, status codes and response shapes with your existing clients before you apply them.

What is an agent skill and what does api-design make the agent do?

An agent skill is a folder with a SKILL.md file that an AI agent loads when a task matches the skill's description. This one is based on the ECC project and is written in Spanish.

Once it is loaded, the agent follows a consistent set of REST design conventions when it designs or reviews endpoints. The skill is a set of patterns and examples, not a tool: it does not change files or call services by itself.

  • Name URLs as plural, lowercase, kebab-case nouns (for example /api/v1/team-members)
  • Choose HTTP status codes such as 201 with a Location header, 404, 409, 422 and 429
  • Structure success responses with a data wrapper and error responses with a code, message and per-field details
  • Choose offset or cursor pagination, and design filtering, sorting, search and sparse fieldsets
  • Cover token and API key authentication patterns and versioning and rate limiting guidance

How do you install the api-design skill?

Download the ZIP for this skill from this page and unzip it. You can install it in one of two places. For a personal setup, put the unzipped folder in ~/.claude/skills/. For a single project, put it in the project's .claude/skills/ folder.

You can also upload the skill in the Claude apps. Open Settings, go to Capabilities, then Skills, and upload it there.

  • Personal: ~/.claude/skills/ (available across your projects)
  • Project only: .claude/skills/ inside your project folder
  • Claude apps: Settings → Capabilities → Skills

How do you trigger the skill with natural requests?

You do not need a special command. The skill is meant to be used when you design new endpoints, review an existing API contract, add pagination, filtering or sorting, implement error handling, plan versioning, or build public or partner APIs. Name the task in plain language and mention REST or the endpoint you care about.

Give the agent the resource names, the consumers and any constraints such as dataset size. The guidance on offset versus cursor pagination, for example, depends on whether the dataset is small or large.

  • "Design the REST endpoints for a team-members resource with create, update and cancel actions."
  • "Review this API contract for inconsistent error formats and wrong status codes."
  • "Add cursor pagination and a status filter to the orders list endpoint."
  • "Plan a versioning strategy for a public partner API."

What does a good result look like?

For a new endpoint, expect plural kebab-case paths, a status code for each method and error bodies with a stable code field. For a review, expect the agent to point out specific URLs or responses that break these conventions and suggest the corrected form.

Keep in mind that the skill is a reference. Check any suggested status code or paging scheme against your own clients and existing contracts before you change production behaviour.

GET /api/v1/users POST /api/v1/users GET /api/v1/users/:id PATCH /api/v1/users/:id DELETE /api/v1/users/:id

What does the skill need and what are the safety notes?

The skill lists no requirements. It does not run scripts and does not use the network. It only supplies guidance that the agent reads while working.

The content assumes you already know HTTP and REST. It is not a substitute for a security review of authentication and authorization design, even though the file includes token and ownership-check examples.

  • Requires: nothing listed
  • Runs scripts: no
  • Uses network: no
  • Files: SKILL.md

What tips help you get better results?

Be specific about the consumers of the API. The skill suggests cursor pagination by default for public APIs and offset pagination for admin dashboards and search results, so say which group you serve.

Ask for a review of the whole contract, not one endpoint at a time, so the agent can check naming and error formats for consistency.

  • State whether the API is public, partner-facing or internal, since the envelope advice differs
  • Give the expected dataset size when you ask about pagination
  • Ask for per-field error details when validation is involved
  • Ask the agent to keep the response envelope the same across all endpoints

What people use it for

  • Designing the endpoints of a new REST API for a SaaS product
  • Reviewing an existing contract for inconsistent error formats or misused status codes
  • Choosing offset or cursor pagination for a feed versus an admin table
  • Adding filtering, sorting and sparse fieldsets to a collection endpoint
  • Planning versioning and rate limit responses for a partner-facing API

Frequently asked questions

Is the api-design skill free?

The source lists the licence as MIT. Check the repository's licence file for the exact terms before you reuse the content in your own project.

What do I need to use the api-design skill?

The skill lists no requirements. You need an agent environment that supports skills, such as the Claude apps or Claude Code, and you should know HTTP and REST basics to judge the advice.

Does the api-design skill run code or access the internet?

No. The skill runs no scripts and uses no network. It is a SKILL.md reference that guides the agent's answers.

Where do I put the api-design skill folder?

Put it in ~/.claude/skills/ for personal use or in .claude/skills/ inside a project. You can also upload it under Settings, Capabilities, Skills in the Claude apps.

Can I use api-design for GraphQL or gRPC?

No. The skill covers REST patterns, and most of its advice does not apply to GraphQL, gRPC or other non-REST styles.

Why is the skill written in Spanish and does that matter?

The SKILL.md file is in Spanish, so the guidance text is Spanish. The URL and JSON examples are language-neutral, so developers who read English can still follow the patterns.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use api-design if you are a backend developer designing or reviewing a REST API and you want consistent naming, status codes, pagination and error formats. Pick something else if you do not work with APIs, if you use GraphQL or gRPC, or if you need a security review of your authentication design.

Download the skill