api-and-interface-designcommit 63128d0SKILL.md · Architecture
API and Interface Design
Guides stable, hard-to-misuse APIs and module interfaces: contract first, consistent errors, validation at boundaries and additive changes.
npx skills add addyosmani/agent-skills --skill api-and-interface-designCommand selected. Copy it manually.
- Permissions
- read-repo
- write-files
- shell
- network
- Compatible with
- Claude Code, Codex, Cursor, Copilot, Gemini CLI
- GitHub
- 112.3k
- Source
- Community · Addy Osmani
- Status
- Scan passed
- License
- MIT
- Category
- Architecture
Core rule
Hyrum's Law: every observable behavior will be depended on, so be intentional about what you expose.
Execution Phases
Phase 01Contract first
Define typed input and output interfaces before implementing; the contract is the spec.
Phase 02Errors and validation
Use one error format everywhere, validate only at system boundaries, and treat third-party API responses as untrusted.
Phase 03Design for extension
Add optional fields rather than changing or removing them, follow the one-version rule and consistent naming, and paginate list endpoints.
Phase 04Honour idempotency keys
Derive keys from intent, claim them atomically with a unique constraint, reject a reused key with a different body, and retain keys past the longest retry path.
Phase 05Verify with the checklist
Confirm typed inputs and outputs on every endpoint, one error format, backward-compatible changes, and types or docs committed with the implementation.
Permissions (summarised from SKILL.md)
| Capability | Needed | Details |
|---|---|---|
| File writes | Required | Writes interface types, schemas, API handler code and accompanying docs. |
| Command execution | Not required | The skill does not call for running commands. |
| Network outbound | Not required | No network access. |
SKILL.md frontmatter (YAML)
---
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.
---