system-design-skills

system-design-skills

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.

---

At a glance

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.

---

Quick Start

Installation

Standards

This plugin follows the Agent Plugins v1.0.0 packaging standard (root plugin.json, validated against the official schema) and its skills follow the Agent Skills spec (skills/<name>/SKILL.md). One repository installs in several hosts:

Host	Reads	Gets
Claude Code	.claude-plugin/plugin.json + .claude-plugin/marketplace.json	skills + /design command + orchestrator agent
OpenAI Codex	.codex-plugin/plugin.json + .agents/plugins/marketplace.json	skills
Cursor, Copilot CLI, other Agent Plugins clients	plugin.json (repo root)	skills

The manifests are kept in lockstep by python3 meta/evals/run_checks.py (same name / version / description everywhere; the root plugin.json stays inside the closed Agent Plugins schema).

Option 1: CLI Install (Recommended)

Use npx skills to install the skills directly:

npx skills add proyecto26/system-design-skills

This installs into your .claude/skills/ directory.

Option 2: Claude Code Plugin

# Add the marketplace
/plugin marketplace add proyecto26/system-design-skills

# Install the plugin (skills + the /design command + the orchestrator agent)
/plugin install system-design-skills

# or, in one step (Claude Code 2.1.275+)
/plugin install system-design-skills --marketplace proyecto26/system-design-skills

SSH 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

Option 3: OpenAI Codex

codex plugin marketplace add proyecto26/system-design-skills
codex plugin add system-design-skills@system-design-skills-marketplace

Codex loads the skills; the /design command and the orchestrator agent are Claude Code components, so in Codex start with "use the system-design skill to design …".

Option 4: Clone and Copy

git clone https://github.com/proyecto26/system-design-skills.git
cp -r system-design-skills/skills/* .claude/skills/

Option 5: Local / development

git clone https://github.com/proyecto26/system-design-skills.git
claude --plugin-dir ./system-design-skills

Option 6: Fork and Customize

Fork the repo, add your own building blocks or provider files (follow meta/SKILL-CONTRACT.md), and point your projects at your fork.

Your first design

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/.

---

The three ways to use it

1. Run the workflow. /design <system> runs the whole process (or dispatches to the system-design-orchestrator agent). Best for full designs and interview practice — it scores the result against the GUIDE quality bar and persists the design doc.
2. 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.md sequences the plugin into a learn → drill → self-test path (method, numbers, building-block syllabus, mistakes checklist, and the practice bank).

3. 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.

---

Building blocks

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.

---

Usage examples

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 (run scripts/botec.py for 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).

---

Provider modularity

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.

---

How it works

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