API Designer
Use when designing REST or GraphQL APIs. Creates consistent schemas, naming conventions, versioning strategy, and error contracts. API design, endpoint design, REST API, GraphQL schema.
Claude Code Skills for Architecture & Design
Every codebase eventually hits a wall where adding features gets slower instead of faster. That's an architecture problem. These skills help you think through API design, component boundaries, data flow patterns, and system-level decisions before they calcify into technical debt. Whether you're designing a GraphQL schema, planning a migration, or deciding how to handle auth flows, the goal is the same: make the next six months of development easier, not harder.
Published by ClaudeVaultLast updated 10 skills
Key takeaway
ClaudeVault's architecture and design skills give Claude Code structured workflows for system design, API contracts, and monorepo boundaries — GraphQL schemas with Relay pagination, REST endpoints with versioning discipline, OAuth and OIDC auth flows, WebSocket lifecycles, and Turborepo-scoped CLAUDE.md hierarchies. They turn Claude into a staff-level design partner that proposes trade-offs instead of picking the first plausible pattern.
At a glance
- 10 skills spanning API design, schema modeling, auth flow architecture, and monorepo boundary decisions
- Covers GraphQL with Apollo, Relay cursor pagination, and DataLoader, plus REST with OpenAPI conventions
- Handles OAuth 2.0 and OIDC auth flow design, including JWT, session cookies, and token refresh strategies
- Designs rate limiters using token bucket and sliding window patterns for high-throughput public APIs
- The largest topic in the Code Structure & Quality bundle by skill count
When you reach for these skills
When a new service needs API and data boundaries locked before any code is written, not after
When a monorepo has grown beyond a single CLAUDE.md and different packages need their own architectural context
When migrating from REST to GraphQL and every endpoint decision affects the client contract for the next year
When auth flows, rate limits, or WebSocket lifecycles are next on the roadmap and the team has no senior architect to anchor the decisions
How these skills work together
A typical Claude Code architecture workflow layers these skills from system-wide decisions down to interface contracts, so trade-offs made early don't reappear as refactors six months later.
- 1
Set the system-level constraints first
Start with the architecture advisor. Claude reviews the existing system, identifies the boundaries that actually need to move, and outputs a constraint sheet — coupling rules, data ownership, fault domains — before any API surface is redrawn.
- 2
Design the REST or GraphQL contract
Use the API designer to shape REST endpoints with OpenAPI conventions, or hand off to the GraphQL schema designer for schema-first work. Claude enforces pagination, versioning, and error envelope patterns that match your existing clients instead of inventing new ones.
- 3
Model the GraphQL schema with pagination baked in
For GraphQL work, the schema designer generates typed schemas with Relay-style cursor pagination and DataLoader-aware resolvers so Claude doesn't accidentally author N+1 paths into the contract.
- 4
Design the auth flow before routes depend on it
The auth flow designer produces OAuth 2.0 or OIDC flows with explicit token lifetimes, refresh semantics, and cookie boundaries. Claude writes down the threat model assumptions alongside the flow so the next security review has something concrete to argue with.
- 5
Plan the migration path to the new architecture
Finally, the migration planner turns the new architecture into a reversible rollout — strangler fig patterns, feature flags, data backfills — so the team can ship incrementally instead of cutting over in a single weekend.
Outcome
A documented system design, typed API contracts, an explicit auth model, and a migration plan the team can execute in phases — not a whiteboard photo nobody reads again.
Compare the skills
| Skill | Best for | Complexity | Primary use case |
|---|---|---|---|
| Architecture Advisor | System-level redesigns and greenfield services | Advanced | Setting boundaries, coupling rules, and fault domains |
| API Designer | REST APIs that need consistency across endpoints | Intermediate | OpenAPI contracts, versioning, and error envelopes |
| GraphQL Schema Designer | GraphQL-first teams and Relay clients | Advanced | Type-safe schemas with cursor pagination and DataLoader |
| Component Architecture Advisor | Frontend codebases past 100 components | Intermediate | Component boundaries, prop contracts, and shared state |
| Type System Designer | TypeScript codebases where types are drifting | Advanced | Discriminated unions, branded types, and inference traps |
| Auth Flow Designer | New products without a production auth story | Advanced | OAuth 2.0 and OIDC flows with refresh semantics |
| WebSocket Architect | Real-time chat, presence, and live dashboard features | Advanced | Connection lifecycle, backpressure, and reconnection |
| Rate Limiter Designer | Public APIs under abusive or bursty traffic | Intermediate | Token bucket and sliding window policies |
| Pagination Designer | List endpoints returning more than 100 items | Beginner | Cursor vs offset pagination trade-offs |
| Migration Planner | Large refactors and platform migrations | Advanced | Strangler-fig rollouts with reversible checkpoints |
Skills in this topic
Architecture Advisor
Provides trade-off analysis, component diagrams, and technology selection rationale for system design decisions. Use when choosing between monolith vs. microservices, selecting databases, designing data flows, or planning system boundaries. System architecture, system design, trade-off analysis.
Every architecture involves trade-offs. Surface them clearly so the user makes an informed choice, not an accidental one. **Step 1: Clarify Requirements** Before designing anything, establish: 1.
Auth Flow Designer
Designs authentication and authorization systems with secure defaults and implementation guidance. Use when building login flows, API authentication, role-based access control, or multi-tenant authorization. OAuth 2.0, JWT, session management, RBAC, API keys.
Design authentication (who are you?) and authorization (what can you do?) as separate concerns.
Component Architecture Advisor
Use when designing component hierarchies, deciding on prop interfaces, choosing composition patterns, or optimizing render performance in React/Vue/Svelte applications. Component architecture, frontend composition, prop design, render optimization.
Designs component hierarchies that remain maintainable as features grow.
Type System Designer
Designs TypeScript type architectures that prevent bugs at compile time by making invalid states unrepresentable. Use when designing domain model type hierarchies, taming unwieldy generics, or building type-safe API boundaries. Discriminated unions, branded types, generic inference, mapped types.
Designs types that enforce correctness through the compiler — not types that merely document code, but types that make wrong code fail to compile. If a type allows an invalid state, it is incomplete.
GraphQL Schema Designer
Use when designing a GraphQL schema, reviewing an existing schema for anti-patterns, or migrating from REST to GraphQL. Designs types, resolvers, pagination, error handling, and authorization patterns. GraphQL API, schema design, Relay specification.
Designs GraphQL schemas that serve client needs without exposing implementation details, creating N+1 query nightmares, or enabling abusive queries.
Migration Planner
Plans safe, reversible production migrations for databases, APIs, and service replacements. Use when moving from state A to state B without downtime. Phased rollout, rollback strategy, expand-contract, strangler fig.
Creates migration plans that are safe, reversible, and executable without downtime.
Rate Limiter Designer
Designs rate limiting that protects services from abuse without degrading legitimate user experience. Use when adding rate limits to APIs, protecting auth flows from brute force, or designing tiered API limits. Token bucket, sliding window, Redis rate limiting.
Designs rate limiting with two goals: protect the service from overload and enforce fair usage.
WebSocket Architect
Designs WebSocket-based real-time features that handle reconnection, message ordering, scaling, and graceful degradation. Use when building chat, live dashboards, collaborative editing, or notifications. WebSocket, SSE, real-time architecture, Socket.IO.
Designs real-time architectures that solve the hard problems: reconnection after network loss, message ordering across distributed servers, scaling beyond a single server, and graceful degradation whe
Pagination Designer
Selects and implements the pagination strategy matching data characteristics, access patterns, and UI requirements. Use when building list endpoints, feed views, or data tables over large datasets. Cursor pagination, offset pagination, keyset pagination.
No single pagination approach wins on UX, query performance, and data consistency simultaneously — match the approach to the use case.
Frequently asked questions
Can Claude Code design software architecture?
Yes, with the right skills. Claude Code's architecture advisor walks existing codebases, identifies coupling hotspots, and proposes boundary changes with trade-off analysis. It suggests patterns and discusses risks, but humans still own irreversible calls like auth model or database choice.
How does Claude Code handle monorepo architecture?
Claude Code walks the directory tree loading every CLAUDE.md file it hits and lazy-loads the ones it needs. In Turborepo or pnpm workspaces, nest a scoped CLAUDE.md inside each package so Claude gets the right architectural context without pulling framework-specific rules from the root.
Does Claude Code design GraphQL schemas?
Yes. The GraphQL schema designer generates type definitions with Relay-style cursor pagination, DataLoader-aware resolvers, and field-level authorization comments. It flags N+1 query paths before they ship and writes the schema with the naming conventions your existing client already uses.
What is the difference between Claude Code and Cursor for system design?
Claude Code is execution-autonomous — it reads, edits, and runs code in agent loops, which fits longer architecture work. Cursor is editor-embedded with human-in-the-loop tab completion, which fits line-level refactoring. For decisions that span multiple files and directories, Claude Code holds context longer.
Can Claude Code design OAuth and OIDC auth flows?
Yes. The auth flow designer skill produces OAuth 2.0 and OIDC flows with explicit token lifetimes, refresh mechanics, cookie boundaries, and a written threat model. Claude documents the trust assumptions so the next security review has a concrete artifact to argue with.
How does Claude Code plan large architecture migrations?
The migration planner produces strangler-fig rollouts — feature-flagged, reversible, broken into phases the team can ship independently. Claude writes down the rollback path for each phase, so a bad increment can be unwound without a weekend war room.