Guide · Agent skill
How to use the API and Interface Design agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The api-and-interface-design skill is a guideline file that tells an AI coding agent how to design stable, hard-to-misuse interfaces: REST or GraphQL endpoints, module boundaries, type contracts and component prop interfaces. It is written for developers and teams who want consistent, backward-compatible APIs. After this guide you will know what the skill changes about the agent's behaviour, how to install it, how to trigger it with plain requests and where its limits are.
API and Interface Designaddyosmani/agent-skills · MIT Download the skill Quick start
- 1Download the ZIP. Get the skill ZIP from this page and unzip it so that SKILL.md sits in its own folder.
- 2Choose an install location. Put the folder in ~/.claude/skills/ for all projects, or in .claude/skills/ inside one project.
- 3Or upload it in the Claude apps. In the Claude apps, open Settings → Capabilities → Skills and upload the skill.
- 4Describe your interface task. Ask for an API, endpoint, module boundary or prop interface in plain language, including existing consumers or retry needs.
- 5Review the design. Check the contract, error shape, naming and idempotency handling against your own requirements before writing code.
What does the skill make the agent do?
When the skill is active, the agent applies a set of interface design principles whenever you ask it to design an API, endpoint, module boundary or component prop interface. The source describes the main habits it encourages: define the contract before implementing it, use one consistent error format, validate input only at system edges, add fields instead of changing existing ones, and use predictable naming.
It also covers idempotency keys, so that retried requests do not cause duplicate actions such as double charges.
- Contract first: write the interface, then the implementation
- Consistent error semantics: one error shape and one status code mapping across endpoints
- Validation at boundaries: check external input at route handlers, form handlers, third-party responses and configuration
- Additive changes: add optional fields rather than removing or retyping existing ones
- Predictable naming: plural nouns for REST endpoints, camelCase fields, UPPER_SNAKE enum values
- Idempotency: derive keys from intent and enforce uniqueness so retries are safe
How do you install the api-and-interface-design skill?
Download the ZIP file from this page and unzip it. The skill folder contains a file called SKILL.md, which holds all of the guidance. Place the folder in one of two locations depending on how you want to use it.
For a personal install that applies to all your projects, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder so it travels with that repository.
If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/
- Project only: .claude/skills/ inside your project
- Claude apps: Settings → Capabilities → Skills, then upload
How do you trigger the skill with a natural request?
You do not need a special command. The skill's description tells the agent when it applies: designing APIs, module boundaries or any public interface, creating REST or GraphQL endpoints, defining type contracts between modules, and setting boundaries between frontend and backend. Ask for one of these tasks in plain language and the guidance is relevant.
Name the surface you are designing and any constraints you care about, such as existing consumers or retry behaviour. That gives the agent something concrete to apply the principles to.
- Design a REST API for managing tasks, with create, list, get, update and delete.
- Define the type contract between our billing module and the checkout module.
- Add a POST endpoint for orders that is safe to retry if the network drops.
- Review this public GraphQL schema before we change the Order type.
What does a good interface look like under this skill?
The skill's examples use a TypeScript-style task API. The contract lists each operation with a comment on its behaviour, for example a partial update where only provided fields change, and an idempotent delete that succeeds even if the item is already deleted.
Errors follow one shape everywhere, with a machine-readable code, a human-readable message and optional details. Status codes map to meanings: 400 for invalid data, 401 for not authenticated, 403 for not authorised, 404 for not found, 409 for conflicts, 422 for failed validation and 500 for server errors without internal details.
interface APIError { error: { code: string; message: string; details?: unknown; }; }What are the idempotency key rules?
The skill treats idempotency as a contract the server must actually honour. A key that is accepted but handled carelessly can be worse than no key, because the client then assumes retries are safe.
The source says the key must stay the same across retries of one intent and differ between separate intents. It should come from the client or the initiating event, not from the layer that retries. A new random key per attempt, or a key built from user and amount, will either create duplicate charges or merge legitimate ones.
- Claim the key with a unique constraint in one database operation rather than checking then acting
- Reject a reused key that arrives with a different request body, instead of replaying the first response
throw new Error('use req.headers[idempotency-key] or charge:v1:orderId, never a fresh UUID per attempt')What are the limits and safety notes?
The skill declares no requirements, runs no scripts and makes no network calls. It is a set of guidelines in a single SKILL.md file, not an automated tool. It shapes the design advice the agent gives you; it does not generate a finished, working implementation and it does not run your tests.
Treat its advice as a starting point for review. The skill suits public interfaces with real consumers. For throwaway scripts or internal code with no other users, the extra rigour usually adds little.
- Requires: nothing listed
- Runs scripts: no
- Uses network: no
- Files: SKILL.md
What people use it for
- Designing a new set of REST endpoints for a task or order resource with consistent error responses
- Defining a type contract between a backend service and a frontend team before either side builds
- Reviewing a public GraphQL schema before a breaking change
- Making a payment or order endpoint safe to retry without duplicate actions
Frequently asked questions
Is the api and interface design agent skill free?
The skill is listed under the MIT licence, which is stated on this page. The source does not mention pricing, so check the licence text in the download for the terms.
What do I need to run the api-and-interface-design skill?
The skill lists no requirements, runs no scripts and makes no network calls. You need an agent environment that supports skills and a place to put the SKILL.md folder.
Where do I install an agent skill like this?
Unzip the folder into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps you can upload it under Settings → Capabilities → Skills.
Will the skill write my API code for me?
No. The skill shapes design guidance and does not generate working code or run tests. It is a guideline file, so you still implement and test the interface yourself.
Why isn't my agent following the skill?
Check that SKILL.md is inside the folder you installed, in one of the supported locations. Then ask for an interface design task explicitly, such as designing an endpoint or module boundary, so the description matches your request.
How is this different from just asking an agent to design an API?
Without the skill, the agent works from general knowledge. With it, the agent is guided by specific rules from this file, such as additive changes, one error format, boundary validation and idempotency keys.
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
Choose this skill if you design REST or GraphQL endpoints, type contracts between modules or frontend and backend boundaries, and you need consistent, backward-compatible interfaces. Pick something else if you are writing a simple one-off script or internal code with no other consumers, or if you expect the skill to produce and test working code.
Download the skill