Skip to main content
skill CX Codex

api-architect — Claude Code skill for API design and setup

api-architect is a Claude Code skill that guides REST, GraphQL, and gRPC API design, from contracts and schemas to documentation and specification checks.

MIT 235 installs ★ 274 updated 2026-09-06

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add curiositech/some_claude_skills --skill api-architect -a claude-code
Open on GitHub

What api-architect does

This skill helps shape an API contract before implementation and covers error formats, versioning, and security. It uses OpenAPI for REST, SDL for GraphQL, and Protocol Buffers for gRPC. Its design guidance also touches WebSocket, OAuth, pagination, and rate limits.

The ./references/ directory contains sample specifications and configurations. Run ./scripts/validate-api-spec.sh to check OpenAPI specs, GraphQL schemas, and Protocol Buffers. The available tools include file reading and editing, plus commands for npm, npx, and openapi-generator. This skill does not cover database schema design, frontend consumption, or deployment, so those tasks need a different specialist skill.

What it helps with

  • draft an API contract before implementation
  • define a paginated GraphQL schema
  • write a gRPC service definition in Protocol Buffers
  • check API specs for common design issues

Example prompts for the agent

  • Design a REST API contract for order management and write an OpenAPI spec.
  • Review this GraphQL schema for pagination and N+1 queries.
  • Create a streaming gRPC service definition in Protocol Buffers.

How to install api-architect

1Skills CLI (Vercel)

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

2Manually: put the files in place

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

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

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about api-architect

How do I install api-architect in Claude Code?

Run npx skills add curiositech/some_claude_skills --skill api-architect -a claude-code. The skill file is at ~/.claude/skills/api-architect/SKILL.md.

What does api-architect do?

It guides REST, GraphQL, and gRPC API design, including contracts, specs, versioning, error handling, and security.

What examples and checks come with api-architect?

The ./references/ directory has examples for OpenAPI, GraphQL, Protocol Buffers, rate limits, and API security. ./scripts/validate-api-spec.sh checks the specs and schemas.

Source text

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

Similar skills

All skills for Backend and APIs →

From the same set180

The whole set →
fullstack-debugger fullstack-debugger troubleshoots Next.js 15, Cloudflare Workers, and Supabase apps layer by layer. Fixes auth errors, broken RLS policies, CORS, and build failures. CX Codex +1 244installs security-auditor security-auditor runs dependency checks, finds hardcoded secrets, and flags injection or XSS risks in source code. Useful before shipping or when reviewing a pull request. CX Codex +1 243installs native-app-designer native-app-designer — a skill for iOS, Mac and web app design that skips the generic AI look. It steers the agent toward spring physics, motion timing and details that make an interface feel human. CX Codex +1 241installs large-scale-map-visualization large-scale-map-visualization — a skill for web maps carrying tens of thousands of markers. It picks clustering libraries, viewport loading, and rendering tricks that keep the browser responsive. CX Codex +1 240installs vaporwave-glassomorphic-ui-designer vaporwave-glassomorphic-ui-designer — a skill for designing photo and memory apps with vaporwave and glassmorphic looks. Use it when you need SwiftUI interfaces with frosted glass, neon pastels, and a retro-futuristic feel. CX Codex +1 234installs diagramming-expert The diagramming-expert skill turns architectures, processes, and relationships into text diagrams. Use it when a system is easier to explain with boxes, lines, and arrows. CX Codex +1 232installs design-critic design-critic evaluates UI and component code across 6 weighted aesthetic dimensions. Generates structured review scores and actionable remix suggestions. CX Codex +1 230installs grief-companion grief-companion is a Claude Code skill for grief education, memorial writing, and practical tasks after a loss. It responds to requests about bereavement, remembrance, or handling affairs after a death. CX Codex +1 229installs

Project sponsors

Companies that keep this analytics open