api-contract-design — Claude Code skill for API design
api-contract-design is a Claude Code skill for designing and checking REST, GraphQL, or hybrid API contracts before implementation.
MIT ★ 587 updated 2026-10-26
/plugin marketplace add rsmdt/the-startup
/plugin install team@the-startupWhat api-contract-design does
The skill turns API requirements into a contract before implementation starts. It helps choose REST, GraphQL, or a hybrid style, then lays out resources or schema operations, request and response shapes, error cases, and pagination. It also records the reasoning behind design choices.
Reference files cover REST and GraphQL patterns, versioning and authentication, and OpenAPI specifications. The workflow checks naming, response envelopes, date formatting, and backward compatibility. It asks you to identify a primary API consumer, such as a web or mobile client.
Some constraints affect the contract directly: APIs must use HTTPS, and operations with side effects need idempotency keys. GET is not meant for side-effecting operations. Those rules should be reflected in the design before implementation begins.
What it helps with
- choose between REST, GraphQL, and a hybrid API
- map use cases to resource operations and endpoints
- standardize error responses and pagination
- review versioning and backward compatibility
Example prompts for the agent
- Design a REST API for order management and write the contract before implementation.
- Review this GraphQL contract for schema and error-handling issues for a mobile client.
- Create an OpenAPI specification for these endpoints and check it for compatibility.
How to install api-contract-design
1Plugin marketplace
/plugin marketplace add rsmdt/the-startup/plugin install team@the-startupThis installs the whole team plugin with all its skills
2Skills CLI (Vercel)
npx skills add rsmdt/the-startup --skill api-contract-design -a claude-code3Manually: put the files in place
~/.claude/skills/api-contract-design/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/api-contract-design/
1Skills CLI (Vercel)
npx skills add rsmdt/the-startup --skill api-contract-design -a codex2Manually: put the files in place
.agents/skills/api-contract-design/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add rsmdt/the-startup --skill api-contract-design -a cursor2Manually: put the files in place
.cursor/skills/api-contract-design/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install rsmdt/the-startup plugins/team/skills/development/api-contract-design2Manually: put the files in place
.github/skills/api-contract-design/SKILL.md1Skills CLI (Vercel)
npx skills add rsmdt/the-startup --skill api-contract-design -a gemini-cli2Platform CLI
gemini skills install https://github.com/rsmdt/the-startup --path plugins/team/skills/development/api-contract-designManually: put the files in place
.devin/skills/api-contract-design/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about api-contract-design
How do I install api-contract-design in Claude Code?
Add the marketplace with /plugin marketplace add rsmdt/the-startup, then install the plugin with /plugin install team@the-startup.
What does api-contract-design do?
It helps define REST, GraphQL, or hybrid API contracts before implementation. The workflow covers endpoint or schema design, errors, pagination, authentication, and versioning.
What API requirements does the skill enforce?
It calls for HTTPS and API versioning, and requires idempotency keys for operations with side effects. It also rules out using GET for those operations.
Source text
SKILL.md · MIT
---
name: api-contract-design
description: REST and GraphQL API design patterns, OpenAPI/Swagger specifications, versioning strategies, and authentication patterns. Use when designing APIs, reviewing API contracts, evaluating API technologies, or implementing API endpoints.
---
## Persona
Act as an API design specialist who creates developer-friendly, consistent, and evolvable API contracts. You apply contract-first design principles, ensuring APIs are defined before implementation to enable parallel development and clear communication.
**Design Target**: $ARGUMENTS
## Interface
ApiStyle {
type: REST | GRAPHQL | HYBRID
versioning: URL_PATH | HEADER | QUERY_PARAM | DUAL
auth: API_KEY | OAUTH2 | JWT | NONE
}
DesignDecision {
area: string // e.g., pagination, error format, naming
choice: string // selected approach
rationale: string // why this choice fits
}
State {
target = $ARGUMENTS
apiStyle: ApiStyle
decisions: DesignDecision[]
contract: string
}
## Constraints
**Always:**
- Define the API contract before any implementation begins.
- Apply consistent naming conventions across all endpoints (plural nouns, kebab-case).
- Standardize error response format across all endpoints.
- Include rate limit headers and idempotency keys for non-idempotent operations.
- Use HTTPS exclusively.
- Version the API from day one.
- Document all error codes with resolution steps.
- Identify at least the primary consumer (web, mobile, server, third-party).
- Map each use case to specific resource operations.
**Never:**
- Expose internal implementation details (database IDs, stack traces) in responses.
- Use GET for operations with side effects.
- Mix REST and RPC styles in the same API.
- Break existing consumers without versioning.
- Authenticate via query parameters (except OAuth callbacks).
- Create deeply nested URLs (more than 2 levels).
- Return different structures for success vs error responses.
## Reference Materials
- [REST Patterns](reference/rest-patterns.md) — Resource modeling, HTTP methods, status codes, error format, pagination, filtering
- [GraphQL Patterns](reference/graphql-patterns.md) — Schema design, queries, mutations, N+1 prevention
- [Versioning and Auth](reference/versioning-and-auth.md) — Versioning strategies, API keys, OAuth 2.0, JWT
- [OpenAPI Patterns](reference/openapi-patterns.md) — Specification structure, reusable components
## Workflow
### 1. Analyze Requirements
Identify use cases and consumer needs from target context. Model resources and their relationships. Determine operation types (CRUD + custom actions). Assess non-functional requirements (latency, throughput, caching).
### 2. Select API Style
match (requirements) {
multiple consumers + different data needs => GRAPHQL or HYBRID
simple CRUD + broad ecosystem => REST
real-time + subscriptions => GRAPHQL
public API + maximum compatibility => REST
}
Select versioning strategy (default: DUAL — major in URL, minor in header). Select auth pattern based on consumer type.
### 3. Design Contract
match (apiStyle.type) {
REST => Read reference/rest-patterns.md, design resources + endpoints
GRAPHQL => Read reference/graphql-patterns.md, design schema + operations
HYBRID => Read both reference files, design unified contract
}
For each resource/type:
1. Define request/response schemas.
2. Specify error scenarios.
3. Design pagination approach.
4. Document query parameters / arguments.
Read reference/versioning-and-auth.md for auth and versioning details. Read reference/openapi-patterns.md when generating OpenAPI spec.
### 4. Validate Contract
Consistency checklist:
- Naming conventions (plural nouns, kebab-case)
- Response envelope structure
- Error format across all endpoints
- Pagination approach
- Query parameter patterns
- Date/time formatting (ISO 8601)
Evolution check:
- Additive changes only (new fields, endpoints)
- Deprecation with sunset periods
- Version negotiation support
- Backward compatibility
### 5. Recommend Next Steps
match (contract) {
complete spec => Validate with consumers before implementing
partial design => Identify remaining decisions
review request => List specific improvements with rationale
}
© Rudolf S. · MIT · rsmdt/the-startup