API and Interface Design skill for Claude Code: design contracts that do not break users

Makes your agent design APIs and module boundaries contract first, with consistent errors and changes that do not break users.

Installs: 67.5K; on skills.sh
Stars: 112.6K; on GitHub
Updated: Nov 2026; last repo commit

api-and-interface-design makes the agent define an interface before it writes the code behind it. It loads when you design or change REST or GraphQL endpoints, module boundaries, component props or type contracts between frontend and backend.

It works from a set of rules: contract first, one error format, validate only at the edges, add fields instead of changing them, predictable names and careful idempotency keys for retries. It bundles no scripts and runs nothing by itself.

Good for

Backend developers designing REST or GraphQL endpoints
Teams defining contracts between frontend and backend
Maintainers changing a public interface

Install api-and-interface-design

Claude Code

Copy this prompt.

Install the api-and-interface-design skill in Claude Code. Run this command:

npx skills add https://github.com/addyosmani/agent-skills --skill api-and-interface-design

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

From its listing on skills.sh. Source.

What's in the skill

When it loads

Guides stable API and interface design. Use when designing APIs, module boundaries, or any public interface. Use when creating REST or GraphQL endpoints, defining type contracts between modules, or establishing boundaries between frontend and backend.

Sections in SKILL.md

Overview
When to Use
Core Principles
Hyrum's Law
The One-Version Rule
1. Contract First
2. Consistent Error Semantics
3. Validate at Boundaries
4. Prefer Addition Over Modification
5. Predictable Naming
6. Honouring an Idempotency Key
REST API Patterns
Resource Design
Pagination
Filtering
Partial Updates (PATCH)

Key facts

Author: addyosmani (repo owner)
Installs on skills.sh: 67,465 (Nov 2, 2026)
GitHub stars: 112,555 on the agent-skills repo (Nov 2, 2026)
License: MIT
Last commit: 2026-11-01
What installs: 1 file: SKILL.md
Needs: Nothing beyond the skill file; it points to the deprecation-and-migration skill for removing old interfaces
Works in: Claude Code, Codex, Cursor, Gemini CLI, Copilot, OpenCode and more, per the README

What it includes

Treat every observable behavior as a commitment once users depend on it
Design implication: expose only what you mean to, and plan deprecation at design time.
Hyrum's Law
Avoid making consumers pick between versions of the same API
Extend instead of forking.
One-Version Rule
Write the interface and its behavior before the implementation
Example TaskAPI interface with create, list, get, update and idempotent delete.
Contract first
One error shape and a fixed status code mapping everywhere
400, 401, 403, 404, 409, 422 and 500 each have a defined meaning; never mix thrown errors, nulls and error objects.
Consistent error semantics
Check input where it enters the system, not between internal functions
Treats third-party API responses as untrusted data.
Validate at boundaries
Add optional fields; never change types or remove fields
Keeps existing consumers working.
Prefer addition over modification
Plural nouns, camelCase params, is/has/can booleans, UPPER_SNAKE enums
A table of conventions.
Predictable naming
Derive the key from the intent, claim it atomically, guard the payload
Covers retries, in-flight duplicates (409, wait or 202), the unknown outcome and how long to keep keys.
Honouring an idempotency key
Resource design, pagination, filtering and PATCH for partial updates
Example endpoints and request/response shapes.
REST patterns
Discriminated unions, input/output types and branded IDs
Short before and after examples.
TypeScript patterns

From the official docs

Questions

What does api-and-interface-design do?

It makes Claude design APIs and module boundaries with a stable contract: types and behavior first, consistent errors, validation at the edges and additive changes.

How do I install api-and-interface-design?

Use the install box above. The README also lists npx skills add addyosmani/agent-skills --skill api-and-interface-design for one skill, and a Claude Code plugin for the whole pack (/plugin marketplace add addyosmani/agent-skills, then /plugin install agent-skills@addy-agent-skills). A one-skill install copies only skills/api-and-interface-design/ and not the repo-level references folder; the README says the skill still works.

Does it only apply to REST?

No. The SKILL.md says it applies to REST APIs, GraphQL schemas, module boundaries, component props and any place where one piece of code talks to another.

Does it cover retries and duplicate requests?

Yes. A section on idempotency keys covers deriving the key from the intent, claiming it with a unique constraint, rejecting a reused key with a different body, and keeping keys longer than the longest retry path.

Is it safe to run?

It is a text file of instructions and bundles no scripts. It guides the code the agent writes, so review the generated interfaces like any other change.

Does it work in Codex, Cursor or other tools?

The README documents Codex (codex plugin marketplace add addyosmani/agent-skills, then codex plugin add agent-skills@agent-skills, Codex CLI v0.122 or newer), Cursor (copy skills into .cursor/skills/), Gemini CLI, Windsurf, OpenCode, GitHub Copilot, Kiro and others. It says the skills are plain Markdown that work with any agent that accepts instruction files. It does not mention the Claude app.

Information

updated Nov 2, 2026

Repository: addyosmani/agent-skills
Folder: skills/api-and-interface-design

addyosmani/agent-skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 2

api-and-interface-design SKILL.md · github.com
addyosmani/agent-skills README · github.com