api-and-interface-design
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.
Best for API design projectsWorks with GitHubLow risk
⌘source
- author
@addyosmani- language
- Shell
★17kstars
2.2kforks
Apr 18, 2026
✦overview.md
Key Features
- ·Designs stable, well-documented interfaces
- ·Makes the right thing easy and the wrong thing hard
- ·Applies to REST APIs, GraphQL schemas, and module boundaries
- ·Considers Hyrum's Law about observable behaviors
- ·Plans for deprecation at design time
Use Cases
- →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
Best for
- ✓API design projects
- ✓Team boundary definition
- ✓Public interface creation
name
api-and-interface-design
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.
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:
- Be intentional about what you expose. Every observable behavior is a potential commitment.
- Don't leak implementation details. If users can observe it, they will depend on it.
$install
1-click copynpx skills add addyosmani/agent-skills --skill api-and-interface-designSafety assessment
★
Clarity score
How clear and easy to understand the SKILL.md instructions are, rated from 1 to 5.
1/ 5
poorThe SKILL.md content is hard to understand and quite ambiguous.
◎
Actionability score
How directly an agent can act on the SKILL.md instructions, rated from 1 to 5.
1/ 5
not actionableThe SKILL.md is hard to act on; an agent would not know what to do.