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

api-architect — скилл для Claude Code: API и установка

Скилл api-architect помогает проектировать REST, GraphQL и gRPC API: от контракта и схемы до документации и проверки спецификации.

MIT 235 установок ★ 274 обновлён 2026-09-06

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add curiositech/some_claude_skills --skill api-architect -a claude-code
Открыть на GitHub

Что делает api-architect

Скилл помогает выбрать подход к API, описать контракт и продумать ошибки, версионирование и безопасность. Для REST он предлагает OpenAPI, для GraphQL — SDL, для gRPC — Protocol Buffers. Также рассматривает WebSocket, OAuth, пагинацию и ограничение частоты запросов.

В комплекте есть примеры спецификаций и конфигураций в ./references/, а ./scripts/validate-api-spec.sh проверяет спецификации OpenAPI, схемы GraphQL и Protocol Buffers. Доступные инструменты включают чтение и редактирование файлов, а также команды для npm, npx и openapi-generator.

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

  • спроектировать контракт REST API до реализации
  • описать GraphQL-схему с пагинацией
  • создать определение сервиса gRPC в Protocol Buffers
  • проверить API-спецификацию на типичные ошибки

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

  • Спроектируй контракт REST API для управления заказами и подготовь OpenAPI-спецификацию.
  • Проверь GraphQL-схему на пагинацию и проблему N+1.
  • Подготовь gRPC-сервис с потоковой передачей данных в Protocol Buffers.

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

1Через Skills CLI (Vercel)

npx skills add curiositech/some_claude_skills --skill api-architect -a claude-code

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

~/.claude/skills/api-architect/SKILL.md

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

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

Вопросы об api-architect

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

Выполните npx skills add curiositech/some_claude_skills --skill api-architect -a claude-code. Файл скилла находится по пути ~/.claude/skills/api-architect/SKILL.md.

Что делает api-architect?

Помогает проектировать REST, GraphQL и gRPC API, готовить спецификации и проверять их. Также рассматривает версионирование, обработку ошибок и безопасность.

Какие файлы и скрипты входят в api-architect?

В ./references/ находятся примеры OpenAPI, GraphQL, Protocol Buffers, ограничения частоты запросов и настроек безопасности. Скрипт ./scripts/validate-api-spec.sh проверяет спецификации и схемы.

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

SKILL.md · MIT
---
name: api-architect
description: 'Expert API designer for REST, GraphQL, gRPC architectures. Activate on: API design, REST API, GraphQL schema, gRPC service, OpenAPI, Swagger, API versioning, endpoint design, rate limiting,
  OAuth flow. NOT for: database schema (use data-pipeline-engineer), frontend consumption (use web-design-expert), deployment (use devops-automator).'
allowed-tools: Read,Write,Edit,Bash(npm:*,npx:*,openapi-generator:*)
metadata:
  category: Code Quality & Testing
  pairs-with:
  - skill: data-pipeline-engineer
    reason: Data layer design under APIs
  - skill: devops-automator
    reason: Deployment and infrastructure for APIs
  tags:
  - api
  - rest
  - graphql
  - grpc
  - architecture
---

# API Architect

Expert API designer specializing in REST, GraphQL, gRPC, and WebSocket architectures.

## Activation Triggers

**Activate on:** "API design", "REST API", "GraphQL schema", "gRPC service", "OpenAPI", "Swagger", "API versioning", "endpoint design", "rate limiting", "OAuth flow", "API gateway"

**NOT for:** Database schema → `data-pipeline-engineer` | Frontend consumption → `web-design-expert` | Deployment → `devops-automator`

## Quick Start

1. **Define API contract first** (API-first design)
2. **Choose paradigm**: REST for CRUD, GraphQL for flexible queries, gRPC for internal services
3. **Write the spec**: OpenAPI for REST, SDL for GraphQL, .proto for gRPC
4. **Design error responses** with consistent structure
5. **Plan versioning** before your first release

## Core Capabilities

| Domain | Technologies |
|--------|-------------|
| **REST** | OpenAPI 3.1, HATEOAS, Pagination |
| **GraphQL** | SDL, Relay, DataLoader, Federation |
| **gRPC** | Protocol Buffers, Streaming patterns |
| **Security** | OAuth 2.0, JWT, API Keys, RBAC |
| **DX** | Swagger UI, SDK generation, Sandboxes |

## Architecture Patterns

### API-First Development
```
Design Contract → Generate Stubs → Implement → Test Against Spec
```

### Response Envelope
```yaml
success: { data: <resource>, meta: { page, total } }
error: { error: { code, message, details: [{ field, issue }] } }
```

### Versioning Options
- URL: `/v1/users` (most explicit)
- Header: `Accept: application/vnd.api+json;version=1`
- Query: `/users?version=1`

## Reference Files

Full working examples in `./references/`:

| File | Description | Lines |
|------|-------------|-------|
| `openapi-spec.yaml` | Complete OpenAPI 3.1 spec | 162 |
| `graphql-schema.graphql` | GraphQL with Relay connections | 111 |
| `grpc-service.proto` | Protocol Buffer, all streaming | 95 |
| `rate-limiting.yaml` | Tier-based rate limit config | 85 |
| `api-security.yaml` | Auth, CORS, security headers | 130 |

## Anti-Patterns (AVOID These)

### 1. Verb-Based URLs
**Symptom**: `/getUsers`, `/createOrder`, `/deleteProduct`
**Fix**: Use nouns (`/users`, `/orders`), let HTTP methods convey action

### 2. Inconsistent Response Envelopes
**Symptom**: `{data: [...]}` sometimes, raw arrays other times
**Fix**: Always use consistent envelope structure

### 3. Breaking Changes Without Versioning
**Symptom**: Removing fields, changing types without warning
**Fix**: Semantic versioning, deprecation headers, sunset periods

### 4. N+1 in GraphQL
**Symptom**: Resolver queries database per item in list
**Fix**: DataLoader pattern for batching, `@defer` for large payloads

### 5. Over-fetching REST Endpoints
**Symptom**: `/users` returns 50 fields when clients need 3
**Fix**: Sparse fieldsets (`?fields=id,name,email`) or GraphQL

### 6. Missing Pagination
**Symptom**: List endpoints return all records
**Fix**: Default limits, cursor-based pagination, `hasMore` indicator

### 7. No Idempotency Keys
**Symptom**: Duplicate POST requests create duplicate resources
**Fix**: Accept `Idempotency-Key` header, return cached response

### 8. Leaky Internal Errors
**Symptom**: Stack traces, SQL errors exposed in 500 responses
**Fix**: Generic error messages in production, request IDs for debugging

### 9. Missing CORS Configuration
**Symptom**: Browser clients blocked with CORS errors
**Fix**: Configure allowed origins, methods, headers explicitly

### 10. No Rate Limiting
**Symptom**: API vulnerable to abuse, no usage visibility
**Fix**: Implement limits per tier, return `X-RateLimit-*` headers

## Validation Script

Run `./scripts/validate-api-spec.sh` to check:
- OpenAPI specs for versions, security schemes, operationIds
- GraphQL schemas for Query types, pagination, error handling
- Protocol Buffers for syntax, packages, field numbers
- Common issues like hardcoded URLs, missing versioning

## Quality Checklist

```
[ ] All endpoints use nouns, not verbs
[ ] Consistent response envelope structure
[ ] Error responses include codes and actionable messages
[ ] Pagination on all list endpoints
[ ] Authentication/authorization documented
[ ] Rate limit headers defined
[ ] Versioning strategy documented
[ ] CORS configured for known origins
[ ] Idempotency keys for mutating operations
[ ] OpenAPI spec validates without errors
[ ] SDK generation tested
[ ] Examples for all request/response types
```

## Output Artifacts

1. **OpenAPI Specifications** - Complete API contracts
2. **GraphQL Schemas** - Type definitions with connections
3. **Protocol Buffers** - gRPC service definitions
4. **API Documentation** - Developer guides
5. **SDK Examples** - Client code samples
6. **Postman Collections** - API test suites

## Tools Available

- `Read`, `Write`, `Edit` - File operations for specs
- `Bash(npm:*, npx:*)` - OpenAPI linting, code generation
- `Bash(openapi-generator:*)` - SDK generation

© curiositech · MIT · curiositech/some_claude_skills

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

Все скиллы по теме «Бэкенд и API» →
api-design OrchestKit Скилл api-design задаёт правила проектирования контрактов REST, GraphQL и gRPC при редактировании эндпоинтов и схем OpenAPI. Включается автоматически при работе с файлами в routes/ и спецификациями. CX Codex +1 211установок api-security-testing usestrix Скилл api-security-testing помогает проверить REST, GraphQL и gRPC API с помощью Strix: агенты ищут уязвимости и прикладывают запрос для проверки находки. CX Codex +1 17 500установок api-design-patterns bobmatnyc Скилл api-design-patterns для Claude Code — справочник по архитектуре REST, GraphQL и gRPC; помогает проектировать эндпоинты, пагинацию, версионирование и схемы ошибок. CX Codex +1 585установок api-expert martinholovsky Скилл api-expert проектирует API по стандартам OpenAPI 3.1 и OWASP. Помогает писать контракты, тесты на pytest и закрывать уязвимости BOLA. CX Codex +1 258установок conducting-api-security-testing mahipal Скилл conducting-api-security-testing для Claude Code проверяет REST, GraphQL и gRPC API на ошибки доступа, аутентификации, валидации и бизнес-логики. Выполняет авторизованные проверки API. CX Codex +1 715установок api-contract-design Rudolf S. Скилл api-contract-design для Claude Code помогает спроектировать и проверить контракт REST- или GraphQL-API до реализации. Он помогает согласовать ресурсы, схемы, версионирование и аутентификацию. CX Codex +1 ★ 587звёзд репо

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

Весь набор →
fullstack-debugger Скилл fullstack-debugger для Claude Code пошагово изолирует и исправляет ошибки в Next.js 15, Cloudflare Workers и Supabase. Диагностирует сбои RLS, CORS, сборки и гидратации. CX Codex +1 244установок security-auditor Скилл security-auditor сканирует зависимости, ищет секреты в коде и проверяет проект по OWASP Top 10. Пригодится перед деплоем или code review, когда надо быстро найти уязвимости. CX Codex +1 243установок native-app-designer Скилл native-app-designer для дизайна iOS, Mac и веб-приложений, которые не выглядят шаблонно. Учит агента физике анимаций, пружинам и деталям, из-за которых интерфейс ощущается живым. CX Codex +1 241установок large-scale-map-visualization Скилл large-scale-map-visualization для веб-карт с десятками тысяч маркеров. Подсказывает, как кластеризовать точки, грузить данные по вьюпорту и не вешать браузер. CX Codex +1 240установок vaporwave-glassomorphic-ui-designer Скилл vaporwave-glassomorphic-ui-designer для Claude Code описывает дизайн фото- и мемори-приложений на SwiftUI в стилях vaporwave и glassmorphism. Включает матовое стекло, неоновые пастели и ретрофутуристичное оформление. CX Codex +1 234установок diagramming-expert Скилл diagramming-expert для Claude Code превращает архитектуру, процессы и связи между сущностями в текстовые схемы. Показывает их блоками и стрелками. CX Codex +1 232установок design-critic Скилл design-critic для дизайн-ревью интерфейсов по 6 критериям с расчётом баллов и разбором кода компонентов. Помогает найти огрехи в верстке и доступности до релиза. CX Codex +1 230установок grief-companion Скилл grief-companion для Claude Code помогает пережить утрату: объясняет особенности горя, поддерживает при практических задачах и помогает создавать памятные тексты. CX Codex +1 229установок

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

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