system-design-skills

_{Made in code with Remotion — the same scenes power the site's hero (site/src/motion/).}

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:

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

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

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

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.

Running the evals

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

With vs. without the plugin — evals/ is a claude plugin eval suite (6 cases, each run with and without the plugin). Latest: url-shortener +1.00, over-decomposition +0.27–0.40, rate-limiter +0.17–0.33, focused single-block +0.33; details and what it changed in the skills are in evals/README.md.

claude plugin eval . --runs 1   # pilot, then drop --runs for the full suite

Project structure

system-design-skills/
├── plugin.json                      # Agent Plugins 1.0 manifest (Cursor, Copilot CLI, …)
├── .claude-plugin/
│   ├── plugin.json                  # Claude Code plugin manifest
│   └── marketplace.json             # Claude Code marketplace metadata
├── .codex-plugin/
│   └── plugin.json                  # OpenAI Codex plugin manifest
├── .agents/plugins/
│   └── marketplace.json             # Codex marketplace catalog
├── evals/                           # `claude plugin eval` suite (with vs. without plugin)
├── 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.webp / hero.mp4         #   README hero film (rendered from site/src/motion/)
│   └── hero.png                     #   social-card image (Open Graph)
├── 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-design skill's references/ (reasoning loop, failure modes, trade-off framework, building-blocks index). For the shared shape of every block, read meta/SKILL-CONTRACT.md.

Known limitations

• Reasoning is subjective, not deterministic. These are judgment skills; only back-of-the-envelope ships 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.

Design principle

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.

👍 Credits

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 in skills/system-design/references/failure-modes.md)

🌟 Star History

💜 Sponsors

This project is free and open source. Sponsors help keep it maintained and growing.

Become a Sponsor | Sponsorship Program

🤝 Contribution

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.

⚖️ License

This repository is available under the MIT License.

Happy vibe coding 💯

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 ❤️