Skip to main content
skill CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add rsmdt/the-startup
/plugin install team@the-startup
Open on GitHub

What 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-startup

This installs the whole team plugin with all its skills

2Skills CLI (Vercel)

npx skills add rsmdt/the-startup --skill api-contract-design -a claude-code

3Manually: put the files in place

~/.claude/skills/api-contract-design/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/api-contract-design/

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

Similar skills

All skills for Backend and APIs →

From the same set50

The whole set →
review-security review-security is a Claude Code subagent that checks code and dependency changes for vulnerabilities and supply-chain risks. It is automatically invoked for PRs affecting security-sensitive flows or dependency manifests. CX Codex ★ 587repo stars platform-operations This skill turns release and monitoring requirements into a platform operations plan. Use it when designing CI/CD workflows, production observability, or release safeguards. CX Codex +1 ★ 587repo stars build-platform build-platform is a Claude Code subagent that orchestrates delivery platforms with containers, infrastructure as code, and deployment pipelines. It supports reproducible environments and rollback-safe releases. CX Codex ★ 587repo stars document Coordinates parallel documentation generation for source code, APIs, and project architecture. CX Codex +1 ★ 587repo stars review-robustness review-robustness flags fragile code before merge: abstraction layers nothing needs yet, and shared state handled carelessly in async flows. Useful on PR review and for bugs that surface only under load. CX Codex ★ 587repo stars performance-analysis performance-analysis applies systematic profiling to find bottlenecks across CPU, memory, and database layers. It enforces measuring baselines before proposing optimizations. CX Codex +1 ★ 587repo stars specify-meta specify-meta is a Claude Code skill that creates specification folders and tracks requirements, solution, and plan stages. It records approvals and decisions for a task. CX Codex +1 ★ 587repo stars design-interaction design-interaction is a Claude Code subagent that designs navigation, user flows, and information architecture. Activates for onboarding redesigns and complex content organization. CX Codex ★ 587repo stars

Project sponsors

Companies that keep this analytics open