Kipt

API design skill: what it does and how to install it

Addy Osmani's API design skill teaches your agent contract-first interfaces, one error format, boundary validation and idempotency keys. How to install it.

By the Kipt team · Updated 23 October 2026

Source: addyosmani/agent-skills · Maintainer: community: Addy Osmani · License: MIT · Checked: 23 October 2026

What is the API design skill?

The API design skill, api-and-interface-design, teaches a coding agent to design interfaces that are stable and hard to misuse: endpoints, type contracts between modules, component props and frontend to backend boundaries. It is for developers who let an agent create or change public interfaces and want consistent errors, safe evolution and fewer breaking changes.

It is one of 25 skills in addyosmani/agent-skills, which the README calls "Production-grade engineering skills for AI coding agents." The skill's description: "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."

As of 23 October 2026, its skills.sh page listed about 61,000 installs.

What does it do?

The whole skill is one SKILL.md. There are no scripts or reference files. It is built from a few principles, each with a TypeScript or REST example:

  • Hyrum's Law. Every observable behavior, including error text, timing and ordering, becomes something a user depends on. So expose only what you mean to support and plan deprecation at design time.
  • The One-Version Rule. Avoid making consumers choose between versions; extend rather than fork.
  • Contract first. Define the interface (for example a TaskAPI with typed inputs and outputs) before the implementation.
  • Consistent error semantics. One error shape with a machine-readable code, a human message and optional details, plus a fixed mapping of status codes (400, 401, 403, 404, 409, 422, 500).
  • Validate at boundaries. Validate input in route handlers, form handlers, environment loading and third-party responses, which it says to treat as untrusted. Don't revalidate between internal functions that share types.
  • Prefer addition over modification. New fields are optional; existing fields never change type or disappear.
  • Predictable naming. Plural nouns in REST paths, camelCase query params and fields, is/has/can booleans, UPPER_SNAKE enum values.
  • Honouring an idempotency key. The longest section. Derive the key from the intent, not the attempt; claim it atomically with a unique constraint instead of check-then-insert; fail loudly when the same key arrives with a different body; choose a response for in-flight duplicates (409, wait, or 202); and keep keys longer than any retry or dead-letter replay path.

It also covers REST patterns (resource design, pagination, filtering, PATCH for partial updates) and TypeScript patterns (discriminated unions, separate input and output types, branded ID types). It closes with a table of "Common Rationalizations", a "Red Flags" list and a verification checklist the agent runs after designing an API.

How do you install the API design skill?

The README's quick start leads with the skills CLI and also documents native plugins.

Just this skill (any agent). The skills CLI installs into Claude Code, Cursor, Codex and other agents:

npx skills add addyosmani/agent-skills --skill api-and-interface-design

Add -g to install it for every project. For Claude Code the folder lands in .claude/skills/api-and-interface-design/, or ~/.claude/skills/api-and-interface-design/ with -g, the standard Claude Code skill locations. Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills.

The skill points to a sibling, deprecation-and-migration, for safely removing things users depend on. If you want that too, add --skill deprecation-and-migration to the same command.

Claude Code plugin (all 25 skills plus commands). Run these inside Claude Code:

/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills

The README notes the marketplace clones over SSH; if that fails, add the marketplace with the full HTTPS URL instead. Plugin skills are namespaced, so this one appears as /agent-skills:api-and-interface-design.

Codex plugin. From the README (Codex CLI v0.122 or later):

codex plugin marketplace add addyosmani/agent-skills
codex plugin add agent-skills@agent-skills

claude.ai. Zip the folder and upload it under Customize, then Skills, as the Claude Help Center explains. Since the skill is a single Markdown file, it works well in chat for reviewing an API proposal.

How do you use it?

The README says designing an API triggers the skill automatically, so describe the job. Example prompts (suggestions, not quotes from the repo):

  • "Design the REST endpoints for comments on tasks, with types for inputs, outputs and errors, before writing any handlers."
  • "Our endpoints return errors in three different shapes. Propose one format and a migration plan."
  • "Add a priority field to the task API without breaking existing clients."
  • "Make POST /payments safe to retry with an idempotency key, including what happens when two retries arrive at once."
  • "Review this module's public interface. What would users start depending on that we don't want to promise?"

It has no requirements: no packages, CLIs or keys. The examples use TypeScript and a schema validator's safeParse, but the rules apply to any language.

Tips and limits

  • Opinions, not standards. Choices such as camelCase fields, 422 for validation errors and page-based pagination are the skill's conventions. If your API already follows other ones, tell the agent to keep yours; consistency is the skill's own first rule.
  • Single file, nothing runs. The skill ships no code. As of 23 October 2026, skills.sh showed Gen Agent Trust Hub, Socket and Snyk all as Pass.
  • Per-skill installs skip shared checklists. The README warns that installing one skill copies only its folder, not the repo-level references/ directory. This skill doesn't link to those checklists, so it works on its own.
  • Pairs with the rest of the pack. The README's lifecycle commands (/spec, /plan, /build and others) pull in skills like this one when they apply.
  • License. The repo is MIT licensed.

Save it in your Kipt library

In Kipt, open Skills and paste the skill's GitHub folder link into the import box. Kipt reads the SKILL.md and its files; for a repo with many skills, like this one, it shows a list to pick from. You can also drop the folder or a .zip. Your skills live in your own private GitHub repo and install into Claude Code or Codex with one command:

npx skills add https://github.com/<you>/<repo>.git --all -g

Kipt is not affiliated with Addy Osmani.

Similar skills

Questions

What is the API design skill?

api-and-interface-design is an Agent Skill in Addy Osmani's agent-skills repo. It guides a coding agent when it designs REST or GraphQL endpoints, module boundaries, type contracts or component props, with rules such as contract first, one error format, validation at system edges and additive changes only.

How do I install the API design skill?

Run npx skills add addyosmani/agent-skills --skill api-and-interface-design for this skill only. In Claude Code you can also install the whole pack with /plugin marketplace add addyosmani/agent-skills and /plugin install agent-skills@addy-agent-skills.

Does the API design skill only cover REST?

No. The skill applies to REST APIs, GraphQL schemas, module boundaries, component props and any surface where one piece of code talks to another. Its worked examples are REST and TypeScript, so those get the most concrete guidance.

What does the skill say about idempotency keys?

It treats accepting an Idempotency-Key header as the contract and storing it properly as the implementation. Derive the key from the intent, claim it atomically with a unique constraint, reject a reused key with a different body, decide what an in-flight duplicate gets, and keep keys longer than your longest retry path.

Will the agent use it automatically?

Yes, it is model-invoked. The repo README says designing an API triggers api-and-interface-design. You can also name it in your request or call it directly as a skill.

More in Skill directory

All guides

Keep your prompts and skills in one place, in your own GitHub. Install every skill with one command.

Get started

Kipt is an independent product, not affiliated with or endorsed by Anthropic, OpenAI, Cursor or GitHub. Claude, ChatGPT, Codex, Cursor and GitHub are trademarks of their owners.