system-design · anthropics — Claude Code skill: architecture and APIs
Walks you through designing services and systems: requirements, components, trade-offs. Useful when you need to decide how to split a service into parts.
npx skills add anthropics/knowledge-work-plugins --skill system-design -a claude-codeWhat system-design does
The skill runs an architecture discussion in five steps. First, requirements: what the system does, its limits on scale, latency, availability and cost, plus team size and timeline. Then a high-level design — components, data flow, API contracts, storage choices.
The deep dive covers the data model, endpoints (REST, GraphQL, gRPC), caching, queues and events, error handling with retries. A separate section handles scale and reliability: load estimation, horizontal versus vertical scaling, failover, monitoring. Every decision gets its trade-offs spelled out — complexity, cost, team familiarity, time to market, maintainability.
You get back a structured design document with diagrams (ASCII or described), explicit assumptions and the trade-off analysis. The skill also flags what you would revisit as the system grows. It is a thinking partner, not a code generator: it will not provision infrastructure or write the service for you.
What it helps with
- split a monolith into services and draw the boundaries
- pick between REST, GraphQL and gRPC for a new API
- design a data model and storage layout
- estimate load and decide how to scale
- surface the trade-offs of an architecture before you build it
Example prompts for the agent
- Design a system for payment intake under peak load and lay out the trade-offs
- How should we architect this monolith into services? Give me boundaries and contracts
- Sketch the API design for a notification service and propose a data model
How to install system-design
1Skills CLI (Vercel)
npx skills add anthropics/knowledge-work-plugins --skill system-design -a claude-code2Manually: put the files in place
~/.claude/skills/system-design/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/system-design/
1Skills CLI (Vercel)
npx skills add anthropics/knowledge-work-plugins --skill system-design -a codex2Manually: put the files in place
.agents/skills/system-design/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add anthropics/knowledge-work-plugins --skill system-design -a cursor2Manually: put the files in place
.cursor/skills/system-design/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install anthropics/knowledge-work-plugins system-design2Manually: put the files in place
.github/skills/system-design/SKILL.md1Skills CLI (Vercel)
npx skills add anthropics/knowledge-work-plugins --skill system-design -a gemini-cli2Platform CLI
gemini skills install https://github.com/anthropics/knowledge-work-plugins --path engineering/skills/system-designManually: put the files in place
.devin/skills/system-design/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add anthropics/knowledge-work-plugins --skill system-design -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about system-design
How do I install system-design in Claude Code?
Run npx skills add anthropics/knowledge-work-plugins --skill system-design -a claude-code. The skill lands at ~/.claude/skills/system-design/SKILL.md.
What does system-design do?
It works through a system design in stages: requirements, high-level design, a deep dive on data and APIs, scaling, and trade-off analysis. The output is a document with diagrams and explicit assumptions.
Which platforms does the skill support?
Besides Claude, it installs for Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode, each with its own -a flag on the npx skills add command.
Source text
SKILL.md · Apache-2.0
--- name: system-design description: Design systems, services, and architectures. Trigger with "design a system for", "how should we architect", "system design for", "what's the right architecture for", or when the user needs help with API design, data modeling, or service boundaries. --- # System Design Help design systems and evaluate architectural decisions. ## Framework ### 1. Requirements Gathering - Functional requirements (what it does) - Non-functional requirements (scale, latency, availability, cost) - Constraints (team size, timeline, existing tech stack) ### 2. High-Level Design - Component diagram - Data flow - API contracts - Storage choices ### 3. Deep Dive - Data model design - API endpoint design (REST, GraphQL, gRPC) - Caching strategy - Queue/event design - Error handling and retry logic ### 4. Scale and Reliability - Load estimation - Horizontal vs. vertical scaling - Failover and redundancy - Monitoring and alerting ### 5. Trade-off Analysis - Every decision has trade-offs. Make them explicit. - Consider: complexity, cost, team familiarity, time to market, maintainability ## Output Produce clear, structured design documents with diagrams (ASCII or described), explicit assumptions, and trade-off analysis. Always identify what you'd revisit as the system grows.
© anthropics · Apache-2.0 · anthropics/knowledge-work-plugins
