system-design-interview

Turn any codebase into a Staff-level system design interview problem.

One command. Works in Claude Code, Cursor, Copilot, Codex, Gemini CLI and 30+ other AI coding tools.

Install

npx github:swaaap-nil/system-design-skill

That's it. It detects which AI tools you use, drops the skill where each of them looks, and adds an AGENTS.md pointer for the rest. No MCP server, no backend, no config file.

curl -fsSL https://raw.githubusercontent.com/swaaap-nil/system-design-skill/main/install.sh | sh

npx github:swaaap-nil/system-design-skill --global

Use

Open your AI tool in any repository and run:

/system-design-interview

Or just ask for it in plain language — the skill auto-triggers on "turn this into a system design question", "how would this scale", "what breaks first", "where are the bottlenecks".

Modes

Effort

Before it starts reading, the skill sizes the repo and asks how much you want to spend. Combine a tier with any mode — quick scan, thorough, interview standard.

The file and tool-call caps are hard, and they're what actually gets enforced — an agent can't observe its own token usage, so the token column is an estimate. If a cap is reached before recon finishes, the brief says so rather than quietly shipping a shallow answer.

What it produces

Seven sections, in this order:

1. The Question — a realistic prompt, phrased the way an interviewer says it, naming the real-world analogue and containing the crux of the problem
2. Core Requirements — 3–4 functional requirements, each cited to the code that proves it exists
3. Below the Line — what's explicitly out of scope, and why
4. Non-Functional Requirements — assumed scale with its evidence trail, latency budgets, throughput, the consistency-vs-availability call, and back-of-envelope math only where a number changes a decision
5. High-Level Architecture — core entities, the API surface, a target design where every component is annotated with the requirement that forces it, the as-built reality, and a delta table between them
6. Data Models — real schemas with real field names, shard-key candidates, hot fields, and an access-pattern table for the hot path
7. Deep Dive / Bottlenecks — exactly two, each with where → failure math → blast radius → named fix → trade-off accepted → how you'd verify

Why it isn't generic slop

Three rules the skill enforces on itself:

• Cite or don't claim. Every statement about your code carries a path/to/file.ts:42 reference. If it can't cite it, it isn't allowed to assert it.
• Tag every assumption. Scale, SLAs and business context aren't in your repo. They come out marked [Assumed] with a justification, never disguised as observations.
• Justify every box. No component appears in the architecture diagram unless a numbered requirement forces it. Kafka does not get added because Kafka is interesting.

It also checks what kind of repository it's looking at before framing anything. A data pipeline has no hot endpoint — its crux is backfill, idempotency or late-arriving data, and the architecture section becomes a DAG rather than a request path. An IaC repo gets read as the answer and reversed into the question. A docs repo gets a one-paragraph refusal instead of an invented system.

There's also a specificity check in the quality gate: would this brief read differently for a different repo in the same language? If not, the skill goes back and reads the hot path properly.

And the citation rule is machine-checked, not just promised. The skill bundles a verifier that resolves every path:line it produced against your actual files:

✓ 23 citations resolved
✗ studios/serializers.py:48 — file has 31 lines
✗ §7 bottleneck 2 contains no failure math — a bottleneck without a number is an opinion

It runs automatically after save and contribute, and on every library PR in CI. A second scanner checks written files for credentials before they can reach a commit — the skill is also told never to open .env, key files or state files in the first place, because redacting output is the wrong layer to catch a secret.

From the worked example:

Bottleneck 1 — SMTP call inside the booking transaction

Where. bookings/services.py:88-124. The transaction.atomic block takes select_for_update on the occurrence row, inserts the booking, and then calls send_confirmation_email() at line 118 — before commit.

Why it breaks. The row lock is held for the duration of an external SMTP call. At a normal 50 ms SMTP round trip, one occurrence row serialises at 20 bookings/sec. Against the projected ~500 concurrent bookings/sec on a class release, the queue depth on that single row grows to 25× the service rate […]

Trade-off accepted. Confirmation emails become eventually delivered, typically within a second. The outbox and relay are new components to monitor, and delivery is at-least-once, so the email task needs a dedupe key.

The library

library/ is a growing set of system design problems generated from real codebases by the people who work in them, then redacted so they can be published. Because each one started from working code, the bottlenecks are ones that actually bit someone rather than ones that read well.

Contribute yours with /system-design-interview contribute — it runs an eligibility check and redacts the output. Then one command does the rest:

node scripts/contribute.mjs docs/system-design/<slug>.shared.md

Fork, copy, reindex, run the check suite, push a branch, and open the PR form in your browser with the full diff — without submitting it. It refuses outright if the credential scan finds anything or the structural check fails.

The stop at the PR form is deliberate. Automated redaction catches patterns; it can't know that your unusual pricing model identifies your employer. You reading that diff is the safety mechanism, so it's placed where GitHub itself enforces it.

Entries can also record how they were made — effort tier, files read, agent, model, tokens, wall-clock time — which shows up in the index's Made with column. The agent fills in only what it can genuinely count; tokens and duration come from your tool's own reporting, or get left out. A missing metric is fine, an invented one isn't, and the validator enforces that.

If it's your employer's code, read the eligibility section in CONTRIBUTING.md first. A generated brief is an architecture document with a list of exploitable weaknesses attached. There's a synthetic route for exactly this case: keep the shape of the problem, rebuild it against an invented product, contribute something just as useful with none of the risk.

Compatibility

The skill follows the Agent Skills open standard — a SKILL.md file with YAML frontmatter — so it works anywhere that standard is supported. The installer writes to whichever of these paths apply:

Tools without native skill support still work — they read the AGENTS.md block and follow the pointer. For a pre-skills version of Cursor, add --cursor-rule to also generate .cursor/rules/system-design-interview.mdc.

Installer flags

-g, --global        install for all projects instead of this repo
-a, --all           install into every known tool directory
    --minimal       only .agents/skills (the cross-tool standard path)
    --tools <list>  universal,claude,codex,copilot,cursor,gemini,opencode
    --dir <path>    target a specific project directory
    --cursor-rule   also write .cursor/rules/*.mdc for pre-skills Cursor
    --no-agents-md  skip the AGENTS.md pointer
-n, --dry-run       print what would happen, change nothing
-f, --force         reinstall over an existing copy

What's inside

skills/system-design-interview/
├── SKILL.md                      # recon protocol + the 7-section output contract
└── references/                   # loaded on demand, not upfront
    ├── recon.md                  # per-stack patterns: routes, models, infra, queues
    ├── bottlenecks.md            # 14 detectable anti-patterns, ranked, with fixes
    ├── numbers.md                # latency, throughput, capacity and cost constants
    ├── rubric.md                 # the Staff bar, anti-signals, interview-mode scoring
    ├── publishing.md             # eligibility check + redaction rules for `contribute`
    └── example-output.md         # a complete worked brief
    scripts/verify-brief.mjs      # resolves citations, checks the structural contract
    scripts/scan-secrets.mjs      # blocks credentials from reaching a written file

library/                          # community-contributed problems, indexed by frontmatter
scripts/check-skill.mjs           # Agent Skills spec validator
scripts/build-index.mjs           # regenerates library/README.md

SKILL.md stays lean and the references load only when a phase needs them — that's the progressive disclosure the spec asks for, and it keeps the context cost near zero until you actually invoke it.

Grounding

The methodology is drawn from the sources practitioners actually use:

• Hello Interview — Delivery Framework (requirements → core entities → API → high-level → deep dives, with time budgets)
• Hello Interview — 5 Keys to Staff-Level System Design (find the crux, cut complexity ruthlessly, show instincts not option lists)
• Hello Interview — Core Concepts and Key Technologies
• The System Design Primer (the four-step framework and the scalability catalogue)

This project is not affiliated with or endorsed by any of them.

Contributing

Two paths, both in CONTRIBUTING.md:

Add a problem to the library — run /system-design-interview contribute on a codebase you know and PR the result. Read the eligibility section first.

Improve the skill — the highest-leverage contribution is a new detection rule in references/bottlenecks.md, in the existing detect → breaks-at → fix → trade-off → verify format. Stack coverage in references/recon.md is the other easy win; each stack is one table row.

License

MIT © Swapnil S