From system-design
Practice system design interviews with four modes: mock (Claude as strict interviewer), learn (Claude as staff-level candidate), postmortem (diagnose past interviews), and generate (create questions with rubrics).
How this skill is triggered — by the user, by Claude, or both
Slash command
/system-design:system-design <mock|learn|postmortem|generate> [problem-or-topic] [--flags]<mock|learn|postmortem|generate> [problem-or-topic] [--flags]The summary Claude sees in its skill listing — used to decide when to auto-load this skill
A practice harness for system design interviews. Each invocation dispatches on the first positional argument.
A practice harness for system design interviews. Each invocation dispatches on the first positional argument.
Invocation differs by harness: Claude Code uses
/system-design ..., Codex uses$system-design .... The rest of this document writes commands without a prefix — use whichever your harness expects.
$1 | Description | Reference |
|---|---|---|
mock [problem] | Claude = strict interviewer. Phases enforced, scored debrief at end. | reference/mock.md |
learn [problem] [--auto] | User = interviewer, Claude = staff candidate. --auto runs both via sub-agents while user observes. | reference/learn.md |
postmortem [--file=<path>] | Diagnose a real interview the user already took. | reference/postmortem.md |
generate [topic] | Author a new question + rubric. Writes 4 markdown files to ./system-design-questions/<slug>/. | reference/generate.md |
$1 is mode-specific (problem text, flags).Run before loading the reference file.
| Step | Action |
|---|---|
| Read level | Load ~/.system-design/state/level.md. If absent, default to staff. --level=<value> overrides for this invocation. |
| Read state | Load runs.md and weaknesses.md from the state dir. Missing files = empty; that's fine. |
| Parse flags | See flags table. Invalid --level value → ask, don't guess. |
Both mock and postmortem score across these. For each: 1–5 with a one-line justification grounded in something the candidate actually said.
Location: ~/.system-design/state/. Create the directory on first write; absent = empty.
| File | Format | Written by |
|---|---|---|
runs.md | One row per scored session: `YYYY-MM-DD | <slug> | <mode> | <level> | <direction> | <s1>,<s2>,<s3>,<s4>,<s5> | <next>`. Scores are the 5 dimensions in order: scoping, structure, depth, tradeoffs, comms. <next> is one short sentence — the single most actionable drill before next session — or blank if nothing specific emerges. | mock (debrief), postmortem (diagnosis) |
weaknesses.md | One row per weak dimension (score ≤3): `YYYY-MM-DD | <slug> | <dimension> | <one-line context>` | mock (debrief), postmortem (diagnosis) |
level.md | Single token: junior / senior / staff / principal | User-managed; skill reads only |
runs.md is the primary tracker — slug, level, direction, and the five scores are all there. weaknesses.md annotates the recurring gaps with a one-line context quote per weak dimension. Project the slug column of runs.md for "already practiced" checks.
Before phase 1 of mock (and before diagnosis in postmortem), if runs.md has ≥2 prior rows at the resolved level, surface a preamble to the user (3 or 4 lines depending on the last row's <next> field):
<level> matches the resolved level).<next> field, surface it as last action item: <text>. Omit the line if blank or if the row is in the legacy 6-column format.If fewer than 2 rows exist at this level, skip the preamble silently — it has nothing useful to say yet. Rows in the legacy 6-column format (no trailing <next>) are read as <next> = empty.
| Flag | Modes | Default |
|---|---|---|
--level=<junior|senior|staff|principal> | all | from level.md, else staff |
--direction=<general|distributed-systems|ml-infra|llm> | generate, mock, learn --auto | general |
--diagram-style=<ascii|mermaid> | learn, postmortem | ascii |
--file=<path> | postmortem | — |
--auto | learn | off |
--exchanges=<N> | learn --auto | 30 |
--direction biases topic and deep-dive selection toward a specific subdomain. Applies only when the user does not supply an explicit $2+ problem (an explicit problem always wins). Invalid value → ask, don't guess.
| Value | Includes (use this list when picking topics and shaping deep-dive probes) |
|---|---|
general | (default) Any common interview topic: feeds, chat, ride-share, URL shortener, rate limiter, payments, search autocomplete. |
distributed-systems | Replication, consensus, sharding, message queues, CDN/edge cache, leader election, hot partitions, geo-distribution, eventual vs strong consistency, observability for distributed traces. |
ml-infra | Feature stores (online/offline parity), training pipelines, model registries, model serving (batch + realtime), A/B test infra, label pipelines, vector DBs, embedding stores, drift detection. |
llm | LLM inference serving, prompt routing, RAG pipelines (chunking, retrieval, reranking), agent orchestration, eval & safety pipelines, KV-cache management, multi-model fallback, structured-output validation. |
When --direction != general, mode reference files should also shape the rubric and deep-dive probes toward that domain's canonical components.
--diagram-style controls how Claude renders diagrams in modes that draw them (learn, postmortem). Pick once at the start of a session; don't mix styles mid-flow.
| Value | Renders in | Use when |
|---|---|---|
ascii (default) | Any terminal, Codex CLI, plain Markdown, code-review diffs, Slack | Default — works everywhere |
mermaid | Claude Code, GitHub, Markdown viewers with Mermaid support | User is reading in a rendered surface and asks for it explicitly |
Templates for both styles live in reference/diagrams.md. The mode files honor the flag — don't draw in the wrong style.
These are reference files modes consult when relevant. Don't load them on every invocation; load when the rule below fires.
| File | Load when |
|---|---|
| reference/primitives.md — cited cheatsheet of latency, capacity, BOE templates, named patterns | mock debrief when scoring tradeoff reasoning or deep-dive depth ≤ 3 (cite the relevant section); postmortem when diagnosis includes "missed numbers" or "no BOE"; learn when the candidate-side agent needs to ground a number. |
| reference/topics.md — vetted topic catalog with difficulty + slugs | mock or learn invoked without a topic (suggest from the catalog filtered by level.md and --direction); generate invoked without a topic (pick from modern or staff+). |
| reference/diagrams.md — Mermaid cheatsheet with system-design templates | learn whenever Claude is in the candidate role (default mode always; --auto candidate sub-agent only — never the interviewer sub-agent); postmortem when illustrating a structural gap in "what stronger would have done." Never loaded by mock (interviewer doesn't draw) or generate (questions are prose only). |
mock. Coaching belongs in the debrief.pause is the only valid out.generate. Suffix -2, -3. Never overwrite.runs.md or weaknesses.md from generate or learn --auto. Only mock and postmortem count as user practice.Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub ftvision/system-design-skill --plugin system-design