Api And Interface Design

This covers the fundamentals of designing interfaces that won't haunt you later. It's built around Hyrum's Law, the idea that users will depend on every observable behavior whether you document it or not, so you need to be intentional about what you expose. The guidance is practical: validate at boundaries, extend rather than modify, use discriminated unions for variants, and keep error handling consistent across your entire API surface. It works for REST endpoints, GraphQL schemas, module boundaries, or React component props. The examples are TypeScript heavy but the principles apply anywhere code talks to code. Worth using when you're drawing lines between systems or teams.

install copies · 90 days. Times the install command was copied on this site in the last 90 days, bots filtered.: 7
skills.sh installs: 72.4K
GitHub stars: 114.6K
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add addyosmani/agent-skills --skill api-and-interface-design --agent claude-code

Installs into .claude/skills of the current project.

Files

API and Interface Design

Overview

Design stable, well-documented interfaces that are hard to misuse. Good interfaces make the right thing easy and the wrong thing hard. This applies to REST APIs, GraphQL schemas, module boundaries, component props, and any surface where one piece of code talks to another.

When to Use

Designing new API endpoints
Defining module boundaries or contracts between teams
Creating component prop interfaces
Establishing database schema that informs API shape
Changing existing public interfaces

Core Principles

Hyrum's Law

With a sufficient number of users of an API, all observable behaviors of your system will be depended on by somebody, regardless of what you promise in the contract.

This means: every public behavior — including undocumented quirks, error message text, timing, and ordering — becomes a de facto contract once users depend on it. Design implications:

SKILL.md on GitHub