Skip to content
Get packs

API and Interface Design

Guides designing stable, hard-to-misuse APIs, module boundaries, and type contracts

Source Download skill
Repository
addyosmani/agent-skills
Stars
112,668
Licence
MIT
Files
1 file

What it does

When installed, the agent follows a set of interface design principles whenever you ask it to design an API, endpoint, module boundary, or component prop interface. It nudges toward defining the contract first, using consistent error formats, validating input only at system edges, adding fields rather than changing existing ones, and using predictable naming. It also covers idempotency keys so retried requests don't cause duplicate actions like double charges.

Great for

  • Developers designing REST or GraphQL endpoints who want consistent, backward-compatible APIs
  • Teams defining contracts between frontend and backend or between modules
  • Engineers reviewing an existing public interface before changing it

Skip it if

  • Simple one-off scripts or internal code with no other consumers, where the extra design rigor adds little value
  • Anyone expecting the skill to generate working code or run tests; it only shapes design guidance, and the file is a guideline rather than an automated tool

Try asking

  • “Design a REST API for managing projects and tasks with pagination and filtering”
  • “Review this endpoint's error responses and suggest a consistent error format”
  • “Define TypeScript interfaces for the boundary between my React frontend and Node backend”
  • “Plan how to make our payment creation endpoint safe to retry with an idempotency key”
Step-by-step guide: how to use API and Interface DesignInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 1 original files, the MIT licence and an attribution note.

    api-and-interface-design.zip
  2. 2

    Add it to your agent

    Claude Code (all projects)

    mkdir -p ~/.claude/skills && unzip api-and-interface-design.zip -d ~/.claude/skills/

    Claude Code / Agent SDK (this project only)

    mkdir -p .claude/skills && unzip api-and-interface-design.zip -d .claude/skills/

    Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.

  3. 3

    Ask for the task

    No special command needed — the agent reads the skill's description and loads it when your request matches. Try one of the prompts above.

Get better results

  • Describe your consumers and what already depends on the interface so the agent can weigh Hyrum's Law and compatibility concerns
  • Ask for a contract or type definition first, then the implementation, to follow the contract-first approach
  • Share your existing error conventions so the agent can align with them rather than introducing a new pattern

What's inside

  • SKILL.md

Redistributed unmodified from addyosmani/agent-skills under the MIT licence. The assessment was drafted with AI from the skill's files on 2026-10-29. Skills can instruct your agent to run code — read SKILL.md and any scripts before installing.