К основному содержанию
скилл CX Codex

api-contract-design — скилл для Claude Code: проектирование API

Скилл api-contract-design для Claude Code помогает спроектировать и проверить контракт REST- или GraphQL-API до реализации. Он помогает согласовать ресурсы, схемы, версионирование и аутентификацию.

MIT ★ 587 обновлён 2026-10-26

Установить в Claude Code · Через маркетплейс плагинов Все способы и платформы ↓
/plugin marketplace add rsmdt/the-startup
/plugin install team@the-startup
Открыть на GitHub

Что делает api-contract-design

Скилл разбирает требования и потребителей API, предлагает стиль интерфейса и помогает описать контракт до реализации. Он охватывает REST, GraphQL и гибридный вариант, а также схемы запросов и ответов, ошибки, пагинацию, версионирование и аутентификацию. Решения сопровождаются обоснованием.

В процессе учитываются единые правила именования и ответов, обратная совместимость и изменения API. Для спецификаций OpenAPI предусмотрены отдельные справочные материалы; для REST и GraphQL тоже есть файлы с шаблонами проектирования. Скилл требует определить хотя бы основного потребителя API и не допускает GET-запросов с побочными эффектами.

Проверка контракта затрагивает формат дат ISO 8601, обработку ошибок и совместимость с существующими потребителями. Для небезопасных операций с побочными эффектами скилл требует ключи идемпотентности, а API предлагает использовать только HTTPS. Это важно учесть до того, как контракт перейдёт в реализацию.

Какие задачи решает

  • выбрать REST, GraphQL или гибридный стиль API
  • описать ресурсы и операции для конкретных сценариев
  • согласовать формат ошибок и пагинацию между эндпоинтами
  • проверить версионирование и обратную совместимость контракта

Примеры запросов агенту

  • Спроектируй REST API для управления заказами и сначала опиши контракт.
  • Проверь контракт GraphQL для мобильного приложения: найди проблемы со схемой и обработкой ошибок.
  • Подготовь спецификацию OpenAPI для этого набора эндпоинтов и проверь её на совместимость.

Как установить api-contract-design

1Через маркетплейс плагинов

/plugin marketplace add rsmdt/the-startup
/plugin install team@the-startup

Команда ставит плагин team целиком, со всеми его скиллами

2Через Skills CLI (Vercel)

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

3Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/api-contract-design/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об api-contract-design

Как установить api-contract-design в Claude Code?

Добавьте маркетплейс командой /plugin marketplace add rsmdt/the-startup, затем установите плагин командой /plugin install team@the-startup.

Что делает api-contract-design?

Помогает спроектировать контракт REST-, GraphQL- или гибридного API до реализации. Проверяет согласованность эндпоинтов, ошибок, пагинации и версионирования.

Какие требования скилл учитывает при проектировании API?

Он требует определить основного потребителя, использовать HTTPS и версионировать API. Для операций с побочными эффектами также предусматривает ключи идемпотентности.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Бэкенд и API» →
api-reference-documentation aj-geddes Скилл api-reference-documentation помогает агенту собрать справочник по API: эндпоинты, аутентификация, примеры запросов и ответов, спецификация OpenAPI. CX Codex +1 501установок api-documentation-generator davila7 Скилл api-documentation-generator сканирует роуты и схемы в кодовой базе и оформляет справочник к REST и GraphQL API. Готовит примеры вызовов, схемы ответов и кодов ошибок. CX Codex +1 235установок api-architect curiositech Скилл api-architect помогает проектировать REST, GraphQL и gRPC API: от контракта и схемы до документации и проверки спецификации. CX Codex +1 235установок doc-api davila7 Команда doc-api для Claude Code генерирует документацию API по кодовой базе проекта. Она находит маршруты, контроллеры и схемы данных, формируя спецификации OpenAPI или интерактивный Swagger UI. CX Codex +1 733установок api-integration-specialist Alysson Franklin Субагент api-integration-specialist проектирует и реализует внутренние API: от REST и GraphQL до документации и SDK. Вызывайте его при работе над API-инфраструктурой B2B-приложения. CX Codex ★ 1 013звёзд репо api-design Agent Skills Team Скилл api-design для Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI и OpenCode — проектирует или рефакторит контракты REST и GraphQL. Запускается, когда нужно зафиксировать форму API до начала реализации. CX Codex +1 390установок

Из того же набора50

Весь набор →
review-security Субагент review-security для Claude Code проверяет изменения кода и зависимостей на уязвимости и риски цепочки поставок. Автоматически подключается к PR с чувствительными к безопасности участками или манифестами зависимостей. CX Codex ★ 587звёзд репо platform-operations Скилл platform-operations помогает спроектировать выпуск приложения и его наблюдаемость как единую систему надёжности. Используйте его при настройке CI/CD, мониторинга или контроля релизов. CX Codex +1 ★ 587звёзд репо build-platform Субагент build-platform для Claude Code собирает платформу доставки: контейнеры, инфраструктуру как код и конвейеры развёртывания. CX Codex ★ 587звёзд репо document Скилл document координирует генерацию документации для кода, API и проектов через параллельных специализированных субагентов. CX Codex +1 ★ 587звёзд репо review-robustness Субагент review-robustness проверяет код на хрупкие места: лишние абстракции и небезопасную работу с общим состоянием в async-потоках. Пригодится на ревью PR и когда баг ловится только под нагрузкой. CX Codex ★ 587звёзд репо performance-analysis Скилл performance-analysis систематизирует профилирование и поиск узких мест в коде и инфраструктуре. Скилл запрещает предлагать оптимизации без метрик и предварительных замеров. CX Codex +1 ★ 587звёзд репо specify-meta Скилл specify-meta для Claude Code создаёт каталоги спецификаций и ведёт их через этапы требований, решений и плана. Отслеживает согласования и решения по задаче. CX Codex +1 ★ 587звёзд репо design-interaction design-interaction — субагент для Claude Code: проектирует навигацию, пользовательские потоки и информационную архитектуру. Включается при проблемах с onboarding и сложной структурой контента. CX Codex ★ 587звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой