DEVELOPMENT WORKFLOW / Addy Osmani
API and Interface Design
Designs stable API contracts, consistent errors and retry-safe idempotency behavior.
“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.”
01 / THE REASONING
Why this made the selection.
- Explains atomic idempotency claims, payload-hash checks and explicit handling of an unknown downstream outcome.
- Connects backwards-compatible schema changes with pagination, boundary validation and retention of retry keys.
02 / THE REVIEW RECORD
What we actually inspected.
Source review has boundaries.
A clear record is more useful than a “safe” badge.
Material inspected
- skills/api-and-interface-design/SKILL.md (complete frontmatter and body)
- https://github.com/addyosmani/agent-skills/blob/1401c8b8030e023baeebb31781a6653fe8e93026/LICENSE (applicable licence text)
Our findings
- Explains atomic idempotency claims, payload-hash checks and explicit handling of an unknown downstream outcome.
- Connects backwards-compatible schema changes with pagination, boundary validation and retention of retry keys.
- Reads and edits API schemas, handlers, tests and documentation through the host; examples include state-changing service code.
Not established by this review
- Host discovery, task execution and model quality were not tested.
- Referenced helpers, sibling plugins and external service operations were not exhaustively audited or executed.
The review applies to the material and revision named here. A newer upstream release can change its behavior.
03 / PUT IT TO WORK
Add a skill to your workflow.
DOCUMENTED COMMAND
npx skills@1.7.1 add https://github.com/addyosmani/agent-skills/tree/1401c8b8030e023baeebb31781a6653fe8e93026/skills/api-and-interface-design --skill api-and-interface-designCopying does not execute this command. It may retrieve a newer version than the reviewed source.
- Use the exact reviewed directory/revision and select the intended host/project scope in Skills CLI.
- Retain all supporting files; separately configure companion skills, runtimes and service credentials named in the definition.
- Review the resulting diff and use an isolated target before any migration, deployment, load test or warehouse operation.
Before you start
- A repository and explicit API compatibility requirements; framework-specific documentation for the implementation.
04 / FOLLOW THE EVIDENCE
The source trail.
Our notes are separate from the original resource.
Check upstream before adopting a new version.
- Skill definition ↗Checked
https://github.com/addyosmani/agent-skills/blob/1401c8b8030e023baeebb31781a6653fe8e93026/skills/api-and-interface-design/SKILL.md
Supports: summary, whySelected, limitations, access, review
- Repository licence ↗Checked
https://github.com/addyosmani/agent-skills/blob/1401c8b8030e023baeebb31781a6653fe8e93026/LICENSE
Supports: Redistribution terms
- Install instructions ↗Checked
https://github.com/addyosmani/agent-skills/blob/1401c8b8030e023baeebb31781a6653fe8e93026/README.md
Supports: Documented install command