Skip to content
Back to search

system-design-skills

A divide-and-conquer wiki of system-design skills for Claude Code — reason about scalable systems, don't memorize architectures.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/proyecto26--system-design-skills/badge.svg)](/listings/proyecto26--system-design-skills)

HTML

<a href="/listings/proyecto26--system-design-skills"><img src="/api/listings/proyecto26--system-design-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Installation

Option 1: CLI Install (Recommended)

Use [npx skills](https://github.com/vercel-labs/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

> **SSH errors?** The marketplace clones via SSH. If you don't have SSH keys on GitHub, force HTTPS: > ```bash > /plugin marketplace add https://github.com/proyecto26/system-design-skills.git > /plugin install system-design-skills > ```

Option 3: Clone and Copy

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

Option 4: Local / development

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

Option 5: 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/`.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 29 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "system-design-skills",
  3. "owner": {
  4. "name": "Proyecto 26",
  5. "email": "jd@proyecto26.com",
  6. "url": "https://github.com/proyecto26"
  7. },
  8. "metadata": {
  9. "description": "Proyecto 26's Claude Code skills marketplace.",
  10. "version": "0.1.0"
  11. },
  12. "plugins": [
  13. {
  14. "name": "system-design-skills",
  15. "source": "./",
  16. "description": "A divide-and-conquer wiki of system-design skills: reason about a design one part at a time (requirements, capacity, APIs, storage, caching, load balancing, messaging, consistency, resilience, delivery, scaling) with generic recipes, cloud-provider variants, explicit trade-offs, and failure-mode analysis. Includes a /design workflow command and an orchestrator agent.",
  17. "version": "0.1.0",
  18. "homepage": "https://github.com/proyecto26/system-design-skills",
  19. "keywords": [
  20. "system-design",
  21. "architecture",
  22. "distributed-systems",
  23. "scalability",
  24. "trade-offs",
  25. "interview"
  26. ]
  27. }
  28. ]
  29. }
README.md · README · 351 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # system-design-skills
  2. <p align="center">
  3. <a href="docs/hero.mp4"><img src="docs/hero.webp" alt="system-design-skills — a memorized diagram breaks under a real constraint; the reasoning loop (clarify, estimate, compose, trade-offs, stress-test) composes 20 building-block skills into an architecture" width="100%"></a>
  4. </p>
  5. <p align="center"><sub>Made in code with Remotion — the same scenes power the <a href="https://proyecto26.com/system-design-skills/">site</a>'s hero (<code>site/src/motion/</code>).</sub></p>
  6. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  7. [![Claude Code](https://img.shields.io/badge/Claude_Code-Plugin-blueviolet)](https://code.claude.com/docs/en/plugins)
  8. [![Skills](https://img.shields.io/badge/Building_Blocks-22_Skills-brightgreen)](#building-blocks)
  9. [![Self-contained](https://img.shields.io/badge/Runtime_deps-none-success)](#design-principle)
  10. [![Providers](https://img.shields.io/badge/Providers-AWS%20%C2%B7%20Azure%20%C2%B7%20GCP%20%C2%B7%20Temporal-blue)](#provider-modularity)
  11. **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.
  12. ---
  13. ## At a glance
  14. ```mermaid
  15. flowchart TB
  16. U["🧑 'design X' · system-design interview"]
  17. U --> ENTRY["/design command&nbsp;&nbsp;·&nbsp;&nbsp;system-design-orchestrator agent"]
  18. ENTRY --> LOOP
  19. subgraph LOOP["Reasoning loop — GUIDE-driven, iterative (reason, don't memorize)"]
  20. direction LR
  21. C["1· Clarify"] --> E["2· Estimate"] --> H["3· Design"] --> T["4· Trade-offs"] --> F["5· Failure modes"] --> I["6· Iterate"]
  22. I -.-> C
  23. end
  24. LOOP -->|"invoke the owning skill (Skill tool)"| BB
  25. subgraph BB["Building-block skills — bottom-up catalog · compose, justify every choice"]
  26. direction TB
  27. L0["L0 Frame &nbsp;· requirements-scoping · back-of-the-envelope"]
  28. L1["L1 Edge &nbsp;&nbsp;· dns · load-balancing · content-delivery"]
  29. L2["L2 Services · api-design · service-decomposition"]
  30. L3["L3 State &nbsp;· data-storage · caching · blob-store · sequencer · sharded-counters · distributed-search"]
  31. L4["L4 Async &nbsp;· messaging-streaming · task-scheduling"]
  32. L5["L5 Correctness · consistency-coordination"]
  33. L6["L6 Ops &nbsp;&nbsp;&nbsp;· resilience-failure · observability · distributed-logging"]
  34. L7["L7 Growth · scaling-evolution"]
  35. L0 --- L1 --- L2 --- L3 --- L4 --- L5 --- L6 --- L7
  36. end
  37. BB -->|"each carries: options · trade-offs · stress · provider variants"| DIAG["architecture-diagram&nbsp;· self-contained HTML+SVG"]
  38. LOOP --> OUT["📄 Scored design doc → docs/design/ + diagram"]
  39. DIAG --> OUT
  40. style U fill:#0b1220,stroke:#8aa8ff,color:#fff
  41. style ENTRY fill:#0b1220,stroke:#a78bfa,color:#fff
  42. style LOOP fill:#0b1220,stroke:#22d3ee,color:#fff
  43. style BB fill:#0b1220,stroke:#34d399,color:#fff
  44. style DIAG fill:#0b1220,stroke:#fbbf24,color:#fff
  45. style OUT fill:#0b1220,stroke:#4caf50,color:#fff
  46. ```
  47. 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.
  48. ---
  49. ## Quick Start
  50. ### Installation
  51. ### Standards
  52. This plugin follows the [Agent Plugins](https://agent-plugins.org/) v1.0.0 packaging standard (root [`plugin.json`](./plugin.json), validated against the official schema) and its skills follow the [Agent Skills](https://agentskills.io/) spec (`skills/<name>/SKILL.md`). One repository installs in several hosts:
  53. | Host | Reads | Gets |
  54. |------|-------|------|
  55. | Claude Code | `.claude-plugin/plugin.json` + `.claude-plugin/marketplace.json` | skills + `/design` command + orchestrator agent |
  56. | OpenAI Codex | `.codex-plugin/plugin.json` + `.agents/plugins/marketplace.json` | skills |
  57. | Cursor, Copilot CLI, other Agent Plugins clients | `plugin.json` (repo root) | skills |
  58. 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).
  59. #### Option 1: CLI Install (Recommended)
  60. Use [npx skills](https://github.com/vercel-labs/skills) to install the skills directly:
  61. ```bash
  62. npx skills add proyecto26/system-design-skills
  63. ```
  64. This installs into your `.claude/skills/` directory.
  65. #### Option 2: Claude Code Plugin
  66. ```bash
  67. # Add the marketplace
  68. /plugin marketplace add proyecto26/system-design-skills
  69. # Install the plugin (skills + the /design command + the orchestrator agent)
  70. /plugin install system-design-skills
  71. # or, in one step (Claude Code 2.1.275+)
  72. /plugin install system-design-skills --marketplace proyecto26/system-design-skills
  73. ```
  74. > **SSH errors?** The marketplace clones via SSH. If you don't have SSH keys on GitHub, force HTTPS:
  75. > ```bash
  76. > /plugin marketplace add https://github.com/proyecto26/system-design-skills.git
  77. > /plugin install system-design-skills
  78. > ```
  79. #### Option 3: OpenAI Codex
  80. ```bash
  81. codex plugin marketplace add proyecto26/system-design-skills
  82. codex plugin add system-design-skills@system-design-skills-marketplace
  83. ```
  84. 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 …"*.
  85. #### Option 4: Clone and Copy
  86. ```bash
  87. git clone https://github.com/proyecto26/system-design-skills.git
  88. cp -r system-design-skills/skills/* .claude/skills/
  89. ```
  90. #### Option 5: Local / development
  91. ```bash
  92. git clone https://github.com/proyecto26/system-design-skills.git
  93. claude --plugin-dir ./system-design-skills
  94. ```
  95. #### Option 6: Fork and Customize
  96. Fork the repo, add your own building blocks or provider files (follow `meta/SKILL-CONTRACT.md`), and point your projects at your fork.
  97. ### Your first design
  98. No configuration, API keys, or runtime dependencies — just describe what you want:
  99. > *"/design a URL shortener that handles billions of reads and 10k writes/sec"*
  100. 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/`.
  101. ---
  102. ## The three ways to use it
  103. 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.
  104. 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.
  105. > **Preparing for an interview?** [`docs/study-path.md`](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).
  106. 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.
  107. ---
  108. ## Building blocks
  109. 22 skills: an orchestrator, a diagram engine, and 20 building blocks arranged **bottom-up** so each layer depends only on the ones beneath it.
  110. | Layer | Blocks | What they decide |
  111. |:------|:-------|:-----------------|
  112. | **L0 Frame** | `requirements-scoping` · `back-of-the-envelope` | what to build, how big |
  113. | **L1 Edge** | `dns` · `load-balancing` · `content-delivery` | get traffic in, served close |
  114. | **L2 Services** | `api-design` · `service-decomposition` | the interface boundary + how the system is split into services |
  115. | **L3 State** | `data-storage` · `caching` · `blob-store` · `sequencer` · `sharded-counters` · `distributed-search` | store it, read it fast |
  116. | **L4 Async** | `messaging-streaming` · `task-scheduling` | decouple, schedule, absorb spikes |
  117. | **L5 Correctness** | `consistency-coordination` | CAP, ordering, consensus |
  118. | **L6 Ops** | `resilience-failure` · `observability` · `distributed-logging` | degrade, see, survive |
  119. | **L7 Growth** | `scaling-evolution` | what changes at 10×/100× |
  120. | **Render** | `architecture-diagram` | draw any of the above |
  121. 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.*
  122. ---
  123. ## Usage examples
  124. Just describe what you need — the right skill triggers automatically:
  125. **"/design a rate limiter for our API across 100 gateway nodes"**
  126. > Runs the full loop and composes `resilience-failure` (algorithm) + `sharded-counters` (hot-key counts) + `api-design` (429/Retry-After contract).
  127. **"SQL or NoSQL for a chat app, and how would I shard it?"**
  128. > `data-storage` — the SQL/NoSQL trade-off table, key design, and sharding strategy with their failure modes.
  129. **"What caching strategy for a read-heavy feed? I'm worried about stampedes."**
  130. > `caching` — read/write strategies, eviction, and the thundering-herd / hot-key mitigations.
  131. **"How many servers and how much storage for 100M DAU posting twice a day?"**
  132. > `back-of-the-envelope` — QPS, storage, bandwidth, server count (run `scripts/botec.py` for an exact check).
  133. **"We lost a region — what breaks and how do we degrade?"**
  134. > `resilience-failure` + `consistency-coordination` — SPOFs, failover, and the degradation story (stale beats error).
  135. **"Draw the architecture for what we just designed."**
  136. > `architecture-diagram` — a self-contained dark-theme HTML+SVG diagram (with PNG/PDF export).
  137. ---
  138. ## Provider modularity
  139. 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.
  140. ---
  141. ## How it works
  142. ```mermaid
  143. sequenceDiagram
  144. participant U as User
  145. participant C as Claude Code
  146. participant O as Orchestrator (agent/skill)
  147. participant B as Building-block skills
  148. participant D as architecture-diagram
  149. U->>C: "/design a URL shortener at scale"
  150. C->>O: Run the reasoning loop
  151. O->>B: requirements-scoping (clarify FR / NFR / scope)
  152. O->>B: back-of-the-envelope (peak QPS, storage, servers)
  153. Note over O,B: numbers force the architecture
  154. O->>B: api-design · data-storage · sequencer · caching
  155. B-->>O: options + trade-offs (solves / worsens / when-to-change)
  156. O->>B: resilience-failure (SPOF, degradation, recovery)
  157. U-->>O: curveball: "now 10× writes"
  158. O->>O: name the invalidated assumption, redesign the affected part
  159. O->>O: coverage sweep — media? IDs? SLOs? search?
  160. O->>D: render the stabilized design
  161. D-->>C: self-contained HTML+SVG
  162. O-->>C: scored design doc → docs/design/
  163. C-->>U: design + diagram + weakest-dimension call-out
  164. ```
  165. 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.
  166. ---
  167. ## Running the evals
  168. A realistic eval harness measures whether the skills make Claude design *better* (not just differently). Everything lives in `meta/evals/`.
  169. - **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.
  170. - **Trigger evals** — `meta/evals/trigger-evals.json`: ~20 should / should-not routing queries.
  171. - **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.
  172. - **Deterministic check** (the one objectively-scriptable surface):
  173. ```bash
  174. python3 skills/back-of-the-envelope/scripts/test_botec.py # asserts calculator == golden fixture
  175. ```
  176. See `meta/evals/README.md` for the full methodology (multi-turn delivery, broad coverage, variance, regression baselines).
  177. **With vs. without the plugin** — `evals/` is a [`claude plugin eval`](https://code.claude.com/docs/en/plugin-evals) suite (6 cases, each run with and without the plugin). Latest: url-shortener **+1.00**, over-decomposition **+0.27**, rate-limiter **+0.17** (targeted re-runs: +0.40 / +0.33); single-block, estimation and out-of-scope cases tie the baseline. Per-run detail and what it changed in the skills are in [`evals/README.md`](evals/README.md).
  178. ```bash
  179. claude plugin eval . --runs 1 # pilot, then drop --runs for the full suite
  180. ```
  181. ---
  182. ## Project structure
  183. ```
  184. system-design-skills/
  185. ├── plugin.json # Agent Plugins 1.0 manifest (Cursor, Copilot CLI, …)
  186. ├── .claude-plugin/
  187. │ ├── plugin.json # Claude Code plugin manifest
  188. │ └── marketplace.json # Claude Code marketplace metadata
  189. ├── .codex-plugin/
  190. │ └── plugin.json # OpenAI Codex plugin manifest
  191. ├── .agents/plugins/
  192. │ └── marketplace.json # Codex marketplace catalog
  193. ├── evals/ # `claude plugin eval` suite (with vs. without plugin)
  194. ├── agents/
  195. │ └── system-design-orchestrator.md # autonomous driver of the reasoning loop
  196. ├── commands/
  197. │ └── design.md # /design <system> — runs the workflow
  198. ├── skills/
  199. │ ├── system-design/ # ORCHESTRATOR — reasoning loop + routing + templates
  200. │ ├── <20 building blocks>/ # SKILL.md + references/ (+ providers/ for component blocks)
  201. │ └── architecture-diagram/ # DIAGRAM ENGINE — self-contained HTML+SVG
  202. ├── docs/ # shared, in-repo references (not skills)
  203. │ ├── GUIDE.md # the ten failure modes (source of the method)
  204. │ ├── study-path.md # interview-prep study path (links the pieces)
  205. │ ├── hero.webp / hero.mp4 # README hero film (rendered from site/src/motion/)
  206. │ └── hero.png # social-card image (Open Graph)
  207. ├── meta/ # maintainer docs + eval set (not skills)
  208. │ ├── SKILL-CONTRACT.md # the authoring contract every block follows
  209. │ ├── PLAN.md # creation plan + status
  210. │ └── evals/ # realistic eval set + results (evals.json, iteration-1/)
  211. ├── LICENSE
  212. └── README.md
  213. ```
  214. > 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`.
  215. ---
  216. ## Known limitations
  217. - **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.
  218. - **Provider numbers drift.** Managed-service quotas/limits change — provider files mark them "verify against current docs" and intentionally avoid being exhaustive service catalogs.
  219. - **Diagram export needs two CDN scripts.** The diagram *renders* fully offline; the PNG/PDF export buttons load two pinned, SRI-protected scripts.
  220. - **No live state.** The plugin has no runtime, server, or API keys — it's pure skills + one stdlib Python calculator.
  221. ---
  222. ## Design principle
  223. > Do not memorize architectures; learn the forces that shape them.
  224. 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.
  225. ---
  226. ## 👍 Credits
  227. Built on the shoulders of the best system-design resources:
  228. - [The System Design Primer](https://github.com/donnemartin/system-design-primer) — building blocks, CAP, and worked examples
  229. - [*System Design Interview*](https://bytebytego.com/) (Alex Xu / ByteByteGo) — the four-step process and back-of-the-envelope numbers
  230. - *Grokking Modern System Design* — the bottom-up building-block catalog
  231. - [*Designing Data-Intensive Applications*](https://dataintensive.net/) (Martin Kleppmann) — data-systems fundamentals
  232. - [`docs/GUIDE.md`](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`)
  233. ---
  234. ## 🌟 Star History
  235. [![Star History Chart](https://api.star-history.com/svg?repos=proyecto26/system-design-skills&type=Date)](https://star-history.com/#proyecto26/system-design-skills&Date)
  236. ## 💜 Sponsors
  237. This project is free and open source. Sponsors help keep it maintained and growing.
  238. [**Become a Sponsor**](https://github.com/sponsors/proyecto26) | [Sponsorship Program](https://proyecto26.com/sponsors/)
  239. ## 🤝 Contribution
  240. 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** ❤️.
  241. See the [contribution guide](https://github.com/proyecto26/.github/blob/master/CONTRIBUTING.md).
  242. ## ⚖️ License
  243. This repository is available under the [MIT License](./LICENSE).
  244. ## Happy vibe coding 💯
  245. Made with ❤️ by [Proyecto 26](https://proyecto26.com) — Changing the world with small contributions.
  246. One hand can accomplish great things, but many can take you into space and beyond! 🌌
  247. Together we do more, together we are more ❤️ <img width="150px" src="https://github.com/proyecto26/sherlock-ai-plugin/blob/main/images/claude-mascot-jumping-animated.svg" align="right">

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.