An open Agent Skill that generates Principal-Engineer-grade system design interview preparation documents. Works with Cursor, Codex CLI, Claude Code, Gemini CLI, GitHub Copilot, and any SKILL.md-compatible AI agent.
Say "design a URL shortener" (or any system design problem) to your AI agent. The skill produces 11 artifacts through a rigorous 6-phase generate-evaluate-fix loop plus an independent Interviewer/Research depth review:
| File | Content |
|---|---|
01-requirements.md |
Functional requirements, capacity estimation, scope |
02-non-functional-requirements.md |
Latency budgets, error budgets, consistency model, runbooks |
03-entities.md |
Domain objects, relationships, state machines |
04-api-design.md |
Concrete REST/gRPC contracts with request/response shapes |
05-schema.md |
Storage schema, indexes, sharding strategy |
06-high-level-design.md |
Architecture with write/read/failure/deploy flows |
06-high-level-design.excalidraw |
Visual companion diagram |
07-deep-dives.md |
4-6 component deep dives with tiered solutions |
08-bottlenecks-and-tradeoffs.md |
Failure matrix, anti-patterns, evolution roadmap |
09-eval-report.md |
Machine-verified PASS/FAIL quality report |
10-interview-transcript.md |
Blind Interviewer critique, conditional Research findings, revision log |
Every design is validated against 27 gate criteria, 5 cross-file consistency checks, a 10-dimension PE rubric (avg >= 4.5, no dimension < 4), and a stricter technical-depth eval that checks L0-L3 algorithm/protocol depth, numeric breaking points, bottleneck authenticity, and conditional Research quality.
The Interviewer agent reviews the design blind to self-scores after the HLD, deep dives, and bottlenecks. The Research agent runs only for Major or Critical findings, using local reference packs plus web research to bring back industry-standard DE/PE/Senior Staff solutions.
Install the skill once, then paste any prompt below into your agent. The skill activates automatically — no slash command required.
Start with any system design problem:
Design a distributed rate limiter
Design an in-memory cache with LRU eviction
Design a URL shortener
Tailor the design to an interview target:
System design for Google — design a news feed
System design for Amazon — design an order fulfillment system
System design for Databricks — design a top-K trending articles system
Ask for Principal-Engineer-grade depth and rubric scoring:
Prepare a chat system for PE interview
Prepare a distributed cache for PE interview at Meta
System design interview — design a payment gateway
Reverse-engineer or decompose a real product:
Break down how Slack handles real-time messaging
Break down the architecture of a ride-sharing dispatch system
Break down a notification system like Firebase Cloud Messaging
Combine any pattern:
| Pattern | Example |
|---|---|
Design a [system] |
Design a rate limiter |
System design for [company] — design a [system] |
System design for Google — design a news feed |
Prepare [system] for PE interview |
Prepare a URL shortener for PE interview |
Break down [system or product] |
Break down a chat system |
System design interview — design a [system] |
System design interview — design a search autocomplete |
Output: 11 files in system-design/<problem-name>/ under your project root.
Works with Cursor, Claude Code, Codex, Gemini CLI, GitHub Copilot, and any Agent Skills-compatible agent. Pick either method:
# Option A — open skills ecosystem (Node.js required)
npx skills add iamurali/system-design-skill --all -g -y
# Option B — zero dependencies (bash + git/curl)
curl -fsSL https://raw.githubusercontent.com/iamurali/system-design-skill/main/install.sh | bashBoth install system-design-interview and excalidraw-diagram to
~/.agents/skills/ — the vendor-neutral path recognized by all major agents.
npx skills add iamurali/system-design-skill --all -y
# or
curl -fsSL https://raw.githubusercontent.com/iamurali/system-design-skill/main/install.sh | bash -s -- --projectnpx skills update
# or
curl -fsSL https://raw.githubusercontent.com/iamurali/system-design-skill/main/install.sh | bash -s -- --updatePNG rendering for Excalidraw diagrams requires uv and Playwright. Run once after install:
curl -fsSL https://raw.githubusercontent.com/iamurali/system-design-skill/main/install.sh | bash -s -- --excalidrawOr manually:
cd ~/.agents/skills/excalidraw-diagram/references && uv sync && uv run playwright install chromiumYou can also install from the Cursor Marketplace
or add a remote rule (https://github.com/iamurali/system-design-skill) — no
terminal required.
flowchart TB
subgraph trigger [Trigger]
User["User prompt\nDesign a URL shortener"]
Agent["Any SKILL.md agent\nCursor / Claude / Codex / Gemini / Copilot"]
end
subgraph entry [Progressive disclosure]
Meta["SKILL.md metadata ~100 tokens"]
Skill["Full SKILL.md + orchestrator.md"]
end
subgraph phases [6-Phase inner loop]
P1["1 Requirements"]
P2["2 NFRs"]
P3["3 Entities / API / Schema"]
CP["Context checkpoint"]
P4["4 HLD + Excalidraw"]
P5["5 Deep dives"]
P6["6 Bottlenecks / tradeoffs"]
P1 --> P2 --> P3 --> CP --> P4 --> P5 --> P6
end
subgraph depth [Interviewer-Research checkpoints]
IV["Interviewer blind review\nafter phases 4, 5, 6"]
RS["Research agent\nMajor/Critical findings only"]
IV --> RS
end
subgraph outer [Outer quality loops]
CF["Cross-file consistency\n5 checks"]
PE["PE rubric\n10 dims avg >= 4.5"]
VAL["Python validator\n27 gates + depth eval"]
end
subgraph out [Output]
Files["11 artifacts in\nsystem-design/problem-name/"]
end
User --> Agent --> Meta --> Skill --> phases
P4 --> IV
P5 --> IV
P6 --> IV
phases --> CF --> PE --> VAL --> Files
skills/
system-design-interview/
SKILL.md # Entry point (Agent Skills standard)
references/
orchestrator.md # 6-phase generate-evaluate-fix loop
interviewer-protocol.md # Blind adversarial depth review
research-protocol.md # Conditional major/critical gap research
reasoning-engine.md # Design methodology + failure modes
principal-engineer-bar.md # 10-dimension PE rubric
building-blocks-index.md # L0-L7 component catalog
company-profiles.md # Interview formats by company
problem-bank.md # 30+ curated problems
tradeoff-framework.md # 3-question trade-off method
numbers-to-know.md # Latency, QPS, storage references
scripts/
validator/ # Python CLI (stdlib only, zero deps)
assets/
exemplars/ # Calibration examples
excalidraw-diagram/
SKILL.md # Companion skill for visual diagrams
references/ # Color palette, templates, render pipeline
The skill uses progressive disclosure to manage context efficiently:
- Agent reads only skill metadata at startup (~100 tokens)
- Full SKILL.md loads when a system design task is detected
- Reference files load just-in-time per phase (never all 7 at once)
- Interviewer/Research protocols load only at configured checkpoints
- Context checkpoint after Phase 3 compresses prior work to ~20 lines
The included Python validator produces machine-verified eval reports. It uses stdlib only (no external dependencies).
cd skills/system-design-interview/scripts
python3 -m validator validate /path/to/system-design/your-problem/The validator now reports four layers: structural gates, cross-file consistency,
quality signals, and technical-depth eval. 10-interview-transcript.md is
validated for blind review, independent scores, conditional Research triggers,
and revision logging.
This skill is calibrated for PE-level interviews. PE is not "Staff but more" -- it is a qualitatively different signal:
- Reframes before solving. Questions the problem itself.
- Sees the full solution space. 2-3 architectures with forces that pick.
- Brings production war stories. Failure modes at real scale.
- Thinks organizationally. Team ownership, blast radius, oncall burden.
- Anticipates the 3-5 year arc. What breaks at 10x, 100x, 1000x.
- Teaches the interviewer something. Novel, non-obvious insights.
- YAGNI at scale. Cheapest design that meets constraints.
| Platform | Status | Install method |
|---|---|---|
| Cursor | Supported | npx skills / install.sh / Marketplace |
| Claude Code | Supported | npx skills / install.sh |
| Codex CLI | Supported | npx skills / install.sh |
| Gemini CLI | Supported | npx skills / install.sh |
| GitHub Copilot | Supported | npx skills / install.sh |
| Any SKILL.md agent | Supported | ~/.agents/skills/ |
Requirements: Python 3.10+ (for validator only). Excalidraw rendering requires uv + Playwright (optional).
MIT