with one click
api-and-interface-design
Design stable APIs, module contracts, schemas, component boundaries, command interfaces, or other public integration surfaces that are predictable, documented, and hard to misuse.
Menu
Design stable APIs, module contracts, schemas, component boundaries, command interfaces, or other public integration surfaces that are predictable, documented, and hard to misuse.
Create, update, or review Agent Skill directories and SKILL.md files for valid frontmatter, structure, portability, progressive disclosure, and validation readiness.
Extracts what the user actually wants instead of what they think they should want. Achieves this through one-question-at-a-time interview until ~95% confidence about the underlying intent. Use when an ask is underspecified ("build me X" without "for whom" or "why now"), when the user explicitly invokes ("interview me", "grill me", "are we sure?", "stress-test my thinking"), or when you catch yourself silently filling in ambiguous requirements before any plan, spec, or code exists.
Discover and run the project's local formatting, linting, static analysis, test, and build checks before handoff.
Update project-facing documentation after a user-visible behavior, configuration, operation, or workflow change.
Discovers and invokes agent skills. Use when starting a session or when you need to discover which skill applies to the current task. This is the meta-skill that governs how all other skills are discovered and invoked.
Add logs, metrics, traces, profiling, or operational notes for meaningful workflows without unsupported performance claims.
| name | api-and-interface-design |
| description | Design stable APIs, module contracts, schemas, component boundaries, command interfaces, or other public integration surfaces that are predictable, documented, and hard to misuse. |
| metadata | {"version":"1.1.1"} |
Use this skill when designing or changing a surface that another caller, component, service, team, user, or automated process depends on. The goal is to make the interface explicit, stable, observable enough to verify, and difficult to misuse.
This applies to HTTP APIs, message contracts, library interfaces, module boundaries, plugin hooks, command-line interfaces, component inputs, schemas, configuration surfaces, and any other boundary where one part of a system talks to another.
Use this skill when you need to:
Do not use this skill to standardize internal helper shapes that have no durable consumer or observable boundary.
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.
Treat observable behavior as a commitment. This includes response shape, error codes, message text, ordering, timing, default values, side effects, and undocumented quirks.
Design implications:
Avoid forcing consumers to choose between multiple active versions of the same interface or dependency. Multiple versions increase maintenance cost and create compatibility problems when different consumers need different versions at the same time.
Prefer extending one stable interface over forking it. If multiple versions are unavoidable, document the support window, migration path, and removal criteria.
State what boundary is being designed and who or what consumes it.
Capture:
The more durable or widely consumed the interface is, the more explicit the contract should be.
Describe the interface before building the implementation. Use the contract format that fits the project, such as an OpenAPI document, schema file, protocol definition, type definition, command help text, ADR, README section, or test fixture.
At minimum, define:
For example, a neutral resource contract might state:
Operation: create item
Input: required name, optional description
Output: item identifier, name, description, creation timestamp
Errors: validation failed, duplicate name, unauthorized
Compatibility: future optional fields may be added to output
Pick one error strategy for the boundary and apply it consistently.
Define:
For request-response APIs, this might be a status code plus a structured error body. For libraries, it might be typed exceptions or result values. For command interfaces, it might be exit codes plus structured output.
Do not mix patterns at the same boundary without a documented reason. If some operations return empty values, some raise errors, and others return structured errors, consumers cannot reliably predict behavior.
Validate external or less-trusted data where it enters the system. After validation, keep internal code focused on domain behavior instead of repeatedly revalidating the same already-trusted data.
Validate data from:
Treat third-party responses as untrusted. Validate their shape and content before using them in logic, rendering, persistence, or security decisions.
Avoid scattering duplicate validation between internal functions that share the same trusted contract.
Extend interfaces without breaking existing consumers.
Usually compatible:
Usually breaking:
When a breaking change is unavoidable, use a deprecation and migration workflow
to plan communication, migration, compatibility support, and removal timing. If
the deprecation-and-migration skill is available, use it for that follow-up
planning.
Use names that match the existing interface style and domain language. Prefer one convention per boundary over mixing styles.
Check names for:
Do not import a naming convention from another language, framework, or transport unless it is already the project convention or required by consumers.
For list or search operations, define:
For partial updates, define:
Do not require callers to provide fields that the system owns, such as generated identifiers, creation timestamps, computed values, or audit fields.
Keep separate shapes for:
This separation keeps callers from depending on implementation details and makes future changes easier.
Validate the design and implementation with consumer-facing checks.
Useful verification includes:
Verification should prove the contract is understandable and stable from the consumer's point of view, not only that the provider implementation works.