Design scalable systems the way strong engineers actually do — by reasoning, not by memorizing diagrams. A divide-and-conquer wiki of composable building-block skills for Claude Code: clarify requirements, size with numbers, compose the right components, justify every trade-off, and stress-test for failure — then score and persist the design. Works in Claude Code, and any agent that can run skills.
flowchart TB
U["🧑 "design X" · system-design interview"]
U --> ENTRY["/design command · system-design-orchestrator agent"]
ENTRY --> LOOP
subgraph LOOP["Reasoning loop — GUIDE-driven, iterative (reason, don't memorize)"]
direction LR
C["1· Clarify"] --> E["2· Estimate"] --> H["3· Design"] --> T["4· Trade-offs"] --> F["5· Failure modes"] --> I["6· Iterate"]
I -.-> C
end
LOOP -->|"invoke the owning skill (Skill tool)"| BB
subgraph BB["Building-block skills — bottom-up catalog · compose, justify every choice"]
direction TB
L0["L0 Frame · requirements-scoping · back-of-the-envelope"]
L1["L1 Edge · dns · load-balancing · content-delivery"]
L2["L2 Services · api-design · service-decomposition"]
L3["L3 State · data-storage · caching · blob-store · sequencer · sharded-counters · distributed-search"]
L4["L4 Async · messaging-streaming · task-scheduling"]
L5["L5 Correctness · consistency-coordination"]
L6["L6 Ops · resilience-failure · observability · distributed-logging"]
L7["L7 Growth · scaling-evolution"]
L0 --- L1 --- L2 --- L3 --- L4 --- L5 --- L6 --- L7
end
BB -->|"each carries: options · trade-offs · stress · provider variants"| DIAG["architecture-diagram · self-contained HTML+SVG"]
LOOP --> OUT["📄 Scored design doc → docs/design/ + diagram"]
DIAG --> OUT
style U fill:#0b1220,stroke:#8aa8ff,color:#fff
style ENTRY fill:#0b1220,stroke:#a78bfa,color:#fff
style LOOP fill:#0b1220,stroke:#22d3ee,color:#fff
style BB fill:#0b1220,stroke:#34d399,color:#fff
style DIAG fill:#0b1220,stroke:#fbbf24,color:#fff
style OUT fill:#0b1220,stroke:#4caf50,color:#fff
Most system-design material teaches you to memorize finished architectures. That is exactly the trap that makes strong engineers fail design discussions: the moment a constraint changes, a memorized diagram falls apart and there is no reasoning underneath to rebuild it. This plugin ships building blocks — one skill per part of a system, each a reusable recipe with explicit trade-offs, behavior under stress, the numbers that matter, and cloud-provider variants — that you compose to fit the problem in front of you.
Use npx skills to install the skills directly:
npx skills add proyecto26/system-design-skillsThis installs into your .claude/skills/ directory.
# Add the marketplace
/plugin marketplace add proyecto26/system-design-skills
# Install the plugin (skills + the /design command + the orchestrator agent)
/plugin install system-design-skillsSSH errors? The marketplace clones via SSH. If you don't have SSH keys on GitHub, force HTTPS:
/plugin marketplace add https://github.com/proyecto26/system-design-skills.git /plugin install system-design-skills
git clone https://github.com/proyecto26/system-design-skills.git
cp -r system-design-skills/skills/* .claude/skills/git clone https://github.com/proyecto26/system-design-skills.git
claude --plugin-dir ./system-design-skillsFork the repo, add your own building blocks or provider files (follow meta/SKILL-CONTRACT.md), and point your projects at your fork.
No configuration, API keys, or runtime dependencies — just describe what you want:
"/design a URL shortener that handles billions of reads and 10k writes/sec"
Claude runs the full loop — clarifies scope, sizes it with back-of-the-envelope numbers, composes the building blocks, weighs trade-offs, stress-tests failure modes, scores the design, and writes it to docs/design/.
- Run the workflow.
/design <system>runs the whole process (or dispatches to thesystem-design-orchestratoragent). Best for full designs and interview practice — it scores the result against the GUIDE quality bar and persists the design doc. - Start a design conversationally. Trigger the system-design orchestrator skill ("design WhatsApp-scale messaging"); it runs the same loop and routes to the blocks.
Preparing for an interview?
docs/study-path.mdsequences the plugin into a learn → drill → self-test path (method, numbers, building-block syllabus, mistakes checklist, and the practice bank).
- Reason about one part. Trigger a building block directly ("what caching strategy here?", "SQL or NoSQL for this?", "how do I shard this table?") — the recipe, trade-offs, and provider variants for just that part.
22 skills: an orchestrator, a diagram engine, and 20 building blocks arranged bottom-up so each layer depends only on the ones beneath it.
| Layer | Blocks | What they decide |
|---|---|---|
| L0 Frame | requirements-scoping · back-of-the-envelope |
what to build, how big |
| L1 Edge | dns · load-balancing · content-delivery |
get traffic in, served close |
| L2 Services | api-design · service-decomposition |
the interface boundary + how the system is split into services |
| L3 State | data-storage · caching · blob-store · sequencer · sharded-counters · distributed-search |
store it, read it fast |
| L4 Async | messaging-streaming · task-scheduling |
decouple, schedule, absorb spikes |
| L5 Correctness | consistency-coordination |
CAP, ordering, consensus |
| L6 Ops | resilience-failure · observability · distributed-logging |
degrade, see, survive |
| L7 Growth | scaling-evolution |
what changes at 10×/100× |
| Render | architecture-diagram |
draw any of the above |
Every block follows one contract (meta/SKILL-CONTRACT.md): When to reach for it · Clarify first · Options · Trade-offs (solves / worsens / when-to-change) · Behavior under stress · How to apply · Dos & Don'ts · Numbers that matter · Choosing a provider · Related blocks.
Just describe what you need — the right skill triggers automatically:
"/design a rate limiter for our API across 100 gateway nodes"
Runs the full loop and composes
resilience-failure(algorithm) +sharded-counters(hot-key counts) +api-design(429/Retry-After contract).
"SQL or NoSQL for a chat app, and how would I shard it?"
data-storage— the SQL/NoSQL trade-off table, key design, and sharding strategy with their failure modes.
"What caching strategy for a read-heavy feed? I'm worried about stampedes."
caching— read/write strategies, eviction, and the thundering-herd / hot-key mitigations.
"How many servers and how much storage for 100M DAU posting twice a day?"
back-of-the-envelope— QPS, storage, bandwidth, server count (runscripts/botec.pyfor an exact check).
"We lost a region — what breaks and how do we degrade?"
resilience-failure+consistency-coordination— SPOFs, failover, and the degradation story (stale beats error).
"Draw the architecture for what we just designed."
architecture-diagram— a self-contained dark-theme HTML+SVG diagram (with PNG/PDF export).
Every building block defaults to a generic, vendor-neutral recipe. When a cloud is named, the skill reads references/providers/<provider>.md for the concrete managed-service mapping, quotas/limits, and provider-specific trade-offs (AWS · Azure · GCP, plus Temporal for durable execution). If no provider file exists for a request, the generic recipe is the answer — by design, never an invented service.
sequenceDiagram
participant U as User
participant C as Claude Code
participant O as Orchestrator (agent/skill)
participant B as Building-block skills
participant D as architecture-diagram
U->>C: "/design a URL shortener at scale"
C->>O: Run the reasoning loop
O->>B: requirements-scoping (clarify FR / NFR / scope)
O->>B: back-of-the-envelope (peak QPS, storage, servers)
Note over O,B: numbers force the architecture
O->>B: api-design · data-storage · sequencer · caching
B-->>O: options + trade-offs (solves / worsens / when-to-change)
O->>B: resilience-failure (SPOF, degradation, recovery)
U-->>O: curveball: "now 10× writes"
O->>O: name the invalidated assumption, redesign the affected part
O->>O: coverage sweep — media? IDs? SLOs? search?
O->>D: render the stabilized design
D-->>C: self-contained HTML+SVG
O-->>C: scored design doc → docs/design/
C-->>U: design + diagram + weakest-dimension call-out
The diagram engine is self-contained: one HTML file with inline SVG, a system monospace font (no web-font fetch), no Mermaid. The only external calls are two pinned, SRI-protected CDN scripts that power the optional PNG/PDF export — omit them and the diagram still renders.
A realistic eval harness measures whether the skills make Claude design better (not just differently). Everything lives in meta/evals/.
- Eval set —
meta/evals/evals.json: multi-turn exercises (URL shortener, rate limiter, news feed, observability pipeline, typeahead, WhatsApp) that each lead with different blocks. Scored on 6 GUIDE behaviors (clarify / quantify / trade-offs / failure / pivot / concrete-API) + a composition check. - Trigger evals —
meta/evals/trigger-evals.json: ~20 should / should-not routing queries. - Run a comparison (with-skill vs baseline, then a judge) — the method is in
meta/evals/README.md; run it with whatever orchestration you have. The first run (meta/evals/iteration-1/) scored with-skill 30/30 vs baseline 20/30 with composition confirmed real. - Deterministic check (the one objectively-scriptable surface):
python3 skills/back-of-the-envelope/scripts/test_botec.py # asserts calculator == golden fixture
See meta/evals/README.md for the full methodology (multi-turn delivery, broad coverage, variance, regression baselines).
system-design-skills/
├── .claude-plugin/
│ ├── plugin.json # plugin manifest
│ └── marketplace.json # marketplace metadata
├── agents/
│ └── system-design-orchestrator.md # autonomous driver of the reasoning loop
├── commands/
│ └── design.md # /design <system> — runs the workflow
├── skills/
│ ├── system-design/ # ORCHESTRATOR — reasoning loop + routing + templates
│ ├── <20 building blocks>/ # SKILL.md + references/ (+ providers/ for component blocks)
│ └── architecture-diagram/ # DIAGRAM ENGINE — self-contained HTML+SVG
├── docs/ # shared, in-repo references (not skills)
│ ├── GUIDE.md # the ten failure modes (source of the method)
│ ├── study-path.md # interview-prep study path (links the pieces)
│ └── hero.png # README banner
├── meta/ # maintainer docs + eval set (not skills)
│ ├── SKILL-CONTRACT.md # the authoring contract every block follows
│ ├── PLAN.md # creation plan + status
│ └── evals/ # realistic eval set + results (evals.json, iteration-1/)
├── LICENSE
└── README.md
For the method, read the
system-designskill'sreferences/(reasoning loop, failure modes, trade-off framework, building-blocks index). For the shared shape of every block, readmeta/SKILL-CONTRACT.md.
- Reasoning is subjective, not deterministic. These are judgment skills; only
back-of-the-envelopeships a scriptable calculator + golden fixture. The eval grades behaviors, not a single "right" answer. - Provider numbers drift. Managed-service quotas/limits change — provider files mark them "verify against current docs" and intentionally avoid being exhaustive service catalogs.
- Diagram export needs two CDN scripts. The diagram renders fully offline; the PNG/PDF export buttons load two pinned, SRI-protected scripts.
- No live state. The plugin has no runtime, server, or API keys — it's pure skills + one stdlib Python calculator.
Do not memorize architectures; learn the forces that shape them.
There is no single correct design — success depends on the assumptions you make explicit. Treat every architecture as a hypothesis that holds until a constraint changes, and be ready to redraw it calmly when one does.
Built on the shoulders of the best system-design resources:
- The System Design Primer — building blocks, CAP, and worked examples
- System Design Interview (Alex Xu / ByteByteGo) — the four-step process and back-of-the-envelope numbers
- Grokking Modern System Design — the bottom-up building-block catalog
- Designing Data-Intensive Applications (Martin Kleppmann) — data-systems fundamentals
docs/GUIDE.md— the ten system-design failure modes that shape the reasoning loop (condensed, runtime version embedded inskills/system-design/references/failure-modes.md)
This project is free and open source. Sponsors help keep it maintained and growing.
Become a Sponsor | Sponsorship Program
When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change. Any contributions you make are greatly appreciated ❤️.
See the contribution guide.
This repository is available under the MIT License.
Made with ❤️ by Proyecto 26 — Changing the world with small contributions.
One hand can accomplish great things, but many can take you into space and beyond! 🌌
Together we do more, together we are more ❤️ 