System Design Mentor

Agent skill for structured System Design practice: mock architecture interviews, trade-off debates, failure analysis, quick-fire drills, flawed architecture reviews, and capacity estimation.

Works with Cursor, Claude Code, and Codex.

Quick start

Requires Node.js 18+ (node -v).

Use a personal practice folder — not a shared team codebase — so your progress files stay separate from work projects.

mkdir my-system-design-practice && cd my-system-design-practice
npx system-design-mentor init

The installer asks which agent to use, copies the skill, and creates profile.md and progress.md if they do not exist.

After install

Start a session right away with one of the prompts below — the mentor uses sensible defaults until you share your target role, stack, or language in chat. Reload the IDE or start a new Codex session if the skill does not appear.

Install targets

Use --target for non-interactive installs:

| Agent | Target | Skill path | | ----------- | ------------------------- | -------------------------------------- | | Cursor | cursor-project | .cursor/skills/system-design-mentor/ | | Claude Code | claude-project | .claude/skills/system-design-mentor/ | | Codex | codex-project | .agents/skills/system-design-mentor/ |

npx system-design-mentor init --target cursor-project

Update the skill

Updates only the installed skill files. Your profile.md and progress.md are not changed.

npx system-design-mentor@latest update

Your practice folder

After init, the layout looks like this:

my-system-design-practice/
  .cursor/skills/system-design-mentor/   # or .claude/skills/... / .agents/skills/...
  profile.md          # mentee profile (agent updates from chat)
  progress.md         # session log (agent updates after sessions)
  tasks/              # mock interviews; one NN-slug.md per new System Design Task session

Example prompts

Cursor — invoke explicitly:

/system-design-mentor Run a Staff-level mock architecture interview.

Codex — invoke explicitly:

$system-design-mentor Run a Staff-level mock architecture interview.

Or ask naturally in any supported agent:

Let's do capacity estimation for a realtime chat system.

Run a failure analysis drill for a Kafka consumer lag incident.

Review my architecture and push back like a Staff/Architect interviewer.

Advanced: Git submodule

Only if you already use Git and prefer submodules over npx copies:

mkdir -p .cursor/skills
git submodule add https://github.com/evsamsonov/system-design-mentor.git .cursor/skills/system-design-mentor

Use the same target paths for Claude Code or Codex from the table above. Update later with git submodule update --remote.

License

MIT. See LICENSE.