Stable Interface Design
A practical guide to designing stable, clear, and hard-to-misuse APIs and module interfaces.
The skill focuses on interface design and shows no malware, credential theft, covert exfiltration, or disproportionate automation. It promotes boundary validation and avoiding internal error disclosure. Points are deducted because least privilege, user confirmation, sensitive-data handling, dependency security, external effects, rollback, and data-flow disclosure are not specified; attribution is only indirect through the repository README/LICENSE, and the publisher is unverified.
The guidance is internally coherent across contracts, error semantics, validation, compatibility, and a verification checklist; repository CI provides some repository-wide structural and evaluation checks. Points are deducted because the assessed skill has no dedicated executable tests, examples contain omitted implementations, and abnormal-input behavior, failure feedback, and key-path reproduction are thin. Static calibration caps this at 10.
The frontmatter clearly targets API design, module boundaries, component props, REST/GraphQL, and frontend-backend boundaries, with reasonably clear triggers. Points are deducted because non-fit cases, input/output boundaries, and cross-stack limitations are not explicit, and there is no Chinese-language or mainland-China network reachability guidance.
The document has frontmatter, overview, usage triggers, principles, patterns, rationalization rebuttals, red flags, and verification, with useful examples. The README supplies installation guidance, while repository context supplies an MIT license, maintainers, and CI. Points are deducted because versioning, changelog, maintenance ownership, and update path are not directly documented in the skill; dependency notes, FAQs, known limitations, and troubleshooting are limited.
The material is directly usable as an API design checklist covering contract-first design, consistent errors, boundary validation, pagination, compatibility, and naming. Points are deducted because there is no project-specific output template, representative completed artifact, or execution evidence, so an agent must still apply substantial contextual judgment. Static calibration caps this at 7.
The skill provides auditable principles, code examples, and a final checklist, and repository CI indicates global skill validation and evaluation steps. Points are deducted because there are no assessed-skill-specific tests, third-party citations, or corroborating evidence types, and static review cannot confirm execution results; only limited evidence is justified.
- This is a static source review; examples, CI, and evaluation scripts were not executed. Repository-wide CI should not be treated as proof that this skill's key paths are validated.
- For production interfaces, separately address authentication and authorization, sensitive data, rate limits, idempotency, auditing, rollback, and compatibility policy.
- The publisher is not verified by the FollowSkills curated enterprise registry; independently verify provenance and maintenance before adoption.
- The documentation provides no Chinese-language or mainland-China network-environment guidance.
What does this skill do, and when should you use it?
This is one standalone skill in addyosmani/agent-skills, focused on APIs, module boundaries, component props, and frontend-backend contracts. It applies contract-first design, consistent error semantics, boundary validation, and backward-compatible extension across REST, GraphQL, and TypeScript interfaces. It also uses Hyrum's Law and the One-Version Rule to frame observable behavior and versioning decisions. It fits developers designing or changing public interfaces, although the supplied material does not show an automated test suite or runtime validation results for this skill.
Guides the user to define typed inputs, outputs, and error contracts before implementation; provides patterns for REST and GraphQL interfaces, resource paths, pagination, filtering, PATCH updates, sub-resources, and naming; identifies system boundaries where API input, form data, third-party responses, and configuration should be validated; recommends discriminated unions, input/output separation, and branded ID types; and ends with a verification checklist covering schemas, error consistency, pagination, naming, compatibility, and documentation.
- A backend developer designing a task REST API needs consistent resource paths, status codes, error bodies, and pagination.
- A frontend-backend team is defining shared type contracts and must separate caller-provided fields from server-generated output.
- A TypeScript engineer is modeling status variants or identifier types to prevent invalid combinations and accidental argument swaps.
- A maintainer is changing a public interface and wants to preserve existing consumers through additive optional fields.
- A team is defining module or component boundaries and needs to recognize observable behavior as a long-term contract.
What are this skill's strengths and limitations?
- Covers REST, GraphQL, TypeScript, module boundaries, component props, and related interface surfaces.
- Includes concrete examples for errors, pagination, filtering, PATCH updates, sub-resources, and naming.
- Emphasizes backward compatibility, boundary validation, and evidence-oriented verification.
- Uses only standard name and description frontmatter, with no visible platform-specific extensions.
- The supplied material does not show an automated test suite or actual runtime validation for this skill.
- It provides design guidance rather than scripts for generating, deploying, or running APIs.
- It does not provide framework-, database-, or API-gateway-specific implementation steps.
How do you install this skill?
The skill is located at skills/api-and-interface-design/SKILL.md in the repository. To install the full collection, run: npx skills add addyosmani/agent-skills. The README says the repository contains 24 skills and provides this supported single-skill command format: npx skills add addyosmani/agent-skills --skill api-and-interface-design.
How do you use this skill?
After installation in an Agent Skills-compatible client, invoke it when designing or changing an API, module boundary, component interface, or other public contract. Example trigger: "Design a task REST API. First define the input/output contracts, consistent errors, boundary validation, and pagination." The skill file does not document client-specific automatic-trigger behavior separately.
How does this skill compare with similar options?
The README names Superpowers and Matt Pocock's skills as comparison alternatives and links to a comparison document; the supplied material does not include that document's conclusions.