Contract-first design for HTTP APIs, GraphQL, CLI surfaces, and library module boundaries. Complements secure-api-design (security) and agent-tool-contracts (LLM tools) with general interface ergonomics and evolution rules.
When to use
New public or cross-team API
Breaking-change review
Designing pagination, filtering, idempotency, or error shapes
1---2name: api-and-interface-design-23description: API and Interface Design4---56# API and Interface Design78Contract-first design for HTTP APIs, GraphQL, CLI surfaces, and library module boundaries. Complements `secure-api-design` (security) and `agent-tool-contracts` (LLM tools) with general interface ergonomics and evolution rules.910## When to use1112- New public or cross-team API13- Breaking-change review14- Designing pagination, filtering, idempotency, or error shapes1516## When not to use1718- Internal refactor with no boundary change19- Security-only audit (use `secure-api-design`)20- Agent tool schema only (use `agent-tool-contracts`)2122## Design checklist2324### Contract2526- Resource naming consistent (nouns, plural collections)27- Versioning strategy documented (URL prefix, header, or additive-only)28- Request/response schemas with examples for happy path + common errors29- Idempotency keys for mutating operations where retries matter3031### Errors3233- Stable machine-readable codes separate from human messages34- HTTP/status mapping documented; no stack traces in client responses35- Validation errors: field-level detail when safe (no PII leakage)3637### Pagination and lists3839- Cursor-based preferred for large/live datasets; offset only when bounded40- Default and max page size documented41- Sort/filter params explicit; reject unknown params predictably4243### Compatibility4445- Additive changes only in minor versions46- Deprecation headers or sunset dates for removals47- Consumer migration notes in changelog4849### Observability5051- Correlation/request IDs in responses or logs52- Rate-limit headers where applicable5354## Workflow55561. Draft resource model and primary use cases572. Write example requests/responses (including errors)583. Run `doubt-driven-review` or `secure-api-design` for high-risk surfaces594. Implement with tests locked to contract examples6061## Output6263- Short design note or OpenAPI/GraphQL schema sketch64- Compatibility and deprecation table if evolving an existing API6566## Related skills6768- `secure-api-design` — authn/z, input validation, secrets69- `agent-tool-contracts` — LLM-facing tool schemas70- `deprecation-and-migration` — sunsetting old interfaces7172*Adapted from [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) (MIT).*
Run npx skillmds@latest add charlieviettq/api-and-interface-design-2 in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
API and Interface Design It is listed under Integrations & APIs on SkillMD.
This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
charlieviettq (@charlieviettq) published this skill. Their other Agent Skills are listed on their SkillMD profile.
charlieviettq