api-and-interface-design
by addyosmaniThe api-and-interface-design skill helps you design stable, hard-to-misuse public interfaces for REST, GraphQL, SDKs, component props, and module boundaries. Use it when API Development needs clear contracts, safer defaults, and a credible path to evolve without breaking consumers.
This skill scores 78/100, which means it is a solid directory listing candidate: agents get a clear trigger surface and substantial design guidance, but users should expect a text-heavy advisory skill rather than a tightly operationalized workflow with tools or installable support files.
- Strong triggerability from frontmatter and "When to Use" guidance covering APIs, module boundaries, component props, and public interfaces.
- Substantial real content in SKILL.md, including core principles like Hyrum's Law and guidance for interface stability, contracts, and change management.
- Good progressive disclosure through multiple H2/H3 sections, code fences, and repo/file references that help agents navigate the material instead of relying on a generic prompt.
- No scripts, references, rules, or other support files, so execution depends heavily on the model interpreting prose correctly.
- No install command or explicit step-by-step operating checklist, which may limit consistency when agents must turn the guidance into concrete outputs.
Overview of api-and-interface-design skill
What the api-and-interface-design skill does
The api-and-interface-design skill helps you design public interfaces that stay usable as real consumers start depending on them. It is meant for REST endpoints, GraphQL schemas, SDK methods, component props, module boundaries, and any contract between teams or systems. The job-to-be-done is not just “generate an API,” but shape one that is clear, hard to misuse, and safer to evolve later.
Who should install it
This skill is best for engineers, tech leads, platform teams, and AI-assisted developers who are defining a new interface or changing an existing one. It is especially useful when multiple consumers will rely on the result, when backward compatibility matters, or when you need better defaults than a generic “design me an API” prompt.
Why it is different from a generic prompt
The main differentiator is its emphasis on interface stability, especially Hyrum's Law: once users can observe a behavior, someone will depend on it. That pushes the model to think beyond happy-path shapes and consider naming, defaults, error behavior, exposed details, and future deprecation risk. For API Development, that is more valuable than raw endpoint brainstorming.
How to Use api-and-interface-design skill
Install context and where to read first
Install the skill in your agent environment with the standard Skills flow for the addyosmani/agent-skills repository, then open skills/api-and-interface-design/SKILL.md first. There are no extra helper scripts or references in this skill, so most of the value is in reading the core principles and applying them directly in your prompt.
If you are browsing the repo manually, start here:
skills/api-and-interface-design/SKILL.md
What input the api-and-interface-design skill needs
The api-and-interface-design install decision usually depends on whether you can give the model enough context. Strong inputs include:
- who the consumers are
- whether the interface is public, internal, or partner-facing
- current constraints such as backward compatibility, latency, auth, or data model limits
- examples of likely requests and responses
- what must stay stable over time
- known migration or versioning concerns
Weak input: “Design a payments API.”
Strong input: “Design a partner-facing REST API for invoice retrieval and refund initiation. Consumers are third-party accounting platforms. We need idempotency, stable error codes, pagination, and a migration path from our existing /v1/charges endpoints.”
Turn a rough goal into a usable prompt
A good api-and-interface-design usage prompt should ask for both the interface and the reasoning behind it. Include:
- interface type: REST, GraphQL, SDK, component props, internal module API
- consumers and misuse risks
- compatibility expectations
- required operations
- non-goals
- output format you want
Example prompt:
- “Use the
api-and-interface-designskill to propose a REST API for user notification preferences. Include resource model, endpoints, request/response examples, error model, pagination/filtering choices, and design tradeoffs. Optimize for long-term compatibility and avoiding accidental contract leaks.”
This works better than a bare request because it tells the skill what stability problem to solve, not just what feature to expose.
Practical workflow and output checks
Use this workflow:
- Ask for an initial interface proposal.
- Ask the model to identify accidental contracts and hidden compatibility risks.
- Revise the design before implementation.
- Only then generate schemas, OpenAPI, resolvers, or code stubs.
Before accepting output, check:
- Are names obvious and durable?
- Does it expose implementation details clients might depend on?
- Are error semantics consistent?
- Are optional fields, defaults, and ordering choices intentional?
- Is there a credible path to change or deprecate later?
api-and-interface-design skill FAQ
Is this skill only for web APIs?
No. The api-and-interface-design skill also fits module interfaces, library methods, component props, and service boundaries. If another developer or system consumes it, the same contract-stability logic applies.
When is api-and-interface-design not the right fit?
Skip it when you only need quick prototype code with no meaningful consumers, or when the interface is purely local and disposable. It is also not a substitute for deep domain modeling, security review, or protocol-specific compliance work. Use it to improve interface shape, not to certify production readiness.
Is it better than a normal API design prompt?
Usually yes, if you care about change tolerance. Ordinary prompts often optimize for completeness or speed, but miss de facto contracts such as field behavior, ordering, error text, or defaults. This api-and-interface-design guide is more useful when the cost of future breakage is high.
Is it beginner-friendly?
Yes, but beginners should provide more context and ask for explanation-heavy output. A good pattern is: “Explain each design choice, list tradeoffs, and flag any decision that may become a long-term compatibility burden.” That turns the skill into a learning aid instead of a black box.
How to Improve api-and-interface-design skill
Give stronger constraints, not broader requests
The fastest way to improve api-and-interface-design for API Development results is to narrow the problem. State what clients must rely on, what they must not rely on, and what may change. The skill performs better with real boundaries than with open-ended ideation.
Ask explicitly for misuse resistance
Many bad interfaces are technically complete but easy to use incorrectly. Tell the model to make the right thing easy and the wrong thing hard. Ask for:
- safer defaults
- clearer naming
- reduced ambiguity
- fewer observable implementation leaks
- explicit deprecation or versioning strategy
Watch for common failure modes
Common weak outputs include over-designed resource models, leaking storage structure into the API, unstable enum choices, vague error handling, and adding fields “just in case.” If you see these, ask the model to simplify the contract and remove anything that creates unnecessary commitment under Hyrum's Law.
Iterate with consumer examples and change scenarios
After the first draft, improve the api-and-interface-design skill by supplying real client examples:
- one ideal consumer flow
- one edge case
- one likely future change
Then ask: “Which parts of this interface would become breaking changes if adopted widely?” That second pass is often where the skill becomes meaningfully better than a one-shot prompt.