System Design Studio
OPEN-SOURCE AGENT SKILL • SPEC v3.2.0
TARGETS: CLAUDE CODE • CURSOR • CODEX • ANTIGRAVITY

Learn system design with the agent you already use.

A stateful, first-principles systems tutor for your AI coding agent. Delivers interactive HTML failure simulators, unpacks engineering jargon inline, commits atomic state in your repository file CURSOR.md, tracks progress live on localhost, and won't let you advance until you defend architectural trade-offs cold in chat.

Install Agent Skill Explore 50 Clusters 354 Topics Roadmapped • Dynamic Session Depth
STATE PARADIGM ZERO-CLOUD
100%
Repo-Native Tutoring

No remote database lock-in. Your living cursor, interactive simulators, verified invariants, and local progress tracker run strictly out of your project repository.

RESILIENT TO CHAT RESETS •••
memory Physical Reality
Interactive Simulators

Step through kernel socket buffers, LSM compactions, and Raft split-brains in your browser.

dashboard Localhost Studio
Visual Progress Tracker

Read-only localhost workbench in real-time sync with Git, featuring lesson player and styled notes.

history Reversibility
Atomic Git Checkpoints

Every sign-off records a tractable commit (sds(learn): ...) with one-command rollback safety.

translate Editorial Empathy
Inline Jargon Unpacking

Friendly essay prose with dedicated callouts for acronyms (HOL, LSM, WAL, 2PC) before referencing.

Operational Mechanism

How it works

Four phases turn your AI coding agent into a stateful systems tutor with unannounced defense gates that verify true mastery before advancing.

Phase 1 01 / SETUP

Repository Scaffolding

The scaffolding script installs the .system-design/ directory into your local repository. 100% local files; zero external cloud services or databases.

Target: .system-design/manifest.json
Phase 2 02 / STATE

Progress in Git

CURSOR.md records the active topic, verified prerequisites, hardware invariants, and previous analogies. When your AI context resets, progress is preserved.

Target: .system-design/CURSOR.md
Phase 3 03 / ARTIFACTS

Live Interactive Lessons

New topics are delivered strictly inside standalone interactive HTML artifacts with live simulators crafted per topic. Follow-up trade-off discussions happen inline in chat without lecture duplication.

Target: .system-design/lessons/*.html
Phase 4 04 / DEFENSE

The Sign-Off Gate

It won't let you move on until you can defend it. The interactive lesson explores mechanics but hides the tick-off scenario. Progress in CURSOR.md advances only after you defend real trade-offs in chat.

Rule: Unannounced Chat Defense
Schema Architecture

The four layers of CURSOR.md

File-backed state on disk outlasts ephemeral AI chat context windows.

Layer 01 • Execution Focus

1. activeFocus

Tracks topic ID, depth tier, and active mechanism group. Ensures the tutor stays on the active objective without hallucinating tangents.

topicId: topic.0.1.tcp-vs-udp • depthLevel: physical-mechanics
Layer 02 • Invariant Rules

2. causalAnchors

Records physical latency numbers and network boundaries verified during lessons so subsequent prompts reason from concrete bounds.

"Cold TCP + TLS 1.3 (no 0-RTT): 3 round trips before first byte"
Layer 03 • Analogy Registry

3. examplesTaken

Registry of system domains used (financial ledger, audio streaming) to maintain continuity without repeating outdated analogies.

['financial-ledger-wal', 'live-webrtc-audio']
Layer 04 • Tangent Buffer

4. deferredQueue

Tracks tangent questions for upcoming clusters without breaking current topic focus. Processed only when foundation phase closes.

['QUIC connection migration across cellular handoffs']
Quickstart Command

Install For Your Agent

Single 1-line setup: detects active coding agents and installs the verified skill ready to use in any chat.

Universal Shell Installer • Auto-Detects All Agents
Bash • Zsh Ready

# Step 1: Install skill globally and configure machine preferences (theme, HTML vs MD, notes opt-in):

curl -fsSL https://raw.githubusercontent.com/alph-a07/system-design-studio/main/install.sh | bash

# Step 2: Initialize a project learning instance with curated tracks or BYO syllabus:

~/.system-design-studio/bin/sds init

# Step 3: Update on-demand when notified via in-chat /sds-update alert (preserves all progress & notes):

curl -fsSL https://raw.githubusercontent.com/alph-a07/system-design-studio/main/update.sh | bash

# Clean Uninstall (safely removes skill only from agents; strictly preserves projects, progress & notes):

curl -fsSL https://raw.githubusercontent.com/alph-a07/system-design-studio/main/uninstall.sh | bash
Separated Installation: Install once globally; scaffold instances per project in default or custom paths.
Two Scripts, Then Pure Chat: Run scripts only for install & init; everything else is 100% skill-command driven.
Project-Scoped Notes: Synthesizes chat defense and invariants into 4 customizable note structures.
Zero-Risk Reversibility: Uninstaller eliminates the skill only; your projects, cursors, and notes are 100% kept.
02

The "Two Scripts, Then Pure Chat" Lifecycle

Ergonomic Workflow
PHASE 01

Global Setup

Run install.sh once. The onboarding wizard configures your visual theme, HTML vs. Markdown output mode, and auto-notes opt-in at ~/.system-design-studio/.

install.sh --theme slate-clean
Links all detected agent skill registries.
PHASE 02

Initialize Project

Scaffold a project instance in default projects/<name> or any repo. Select a curated goal track or import BYO markdown:

  • › Interview Sprint (15 clusters / 114 topics)
  • › Distributed Systems (23 clusters / 171 topics)
  • › Staff+ System Defense (25 clusters / 184 topics)
  • › Full 50-Cluster Mastery (354 topics)
Auto-registered in multi-project registry.
PHASE 03

Pure Chat Commands

Never touch a terminal again. Interact exclusively through chat commands across Antigravity, Claude Code, Cursor, and Codex:

  • › /sds-teach [topic] (deliver)
  • › /sds-discuss (defend cold)
  • › /sds-complete (sign off)
  • › /sds-projects (switch/list)
  • › /sds-delete <id> (safe delete)
Agents execute scripts silently under the hood.
PHASE 04

Synthesized Notes

Topic sign-offs automatically compile comprehensive study notes combining physical invariants, your cold chat defense, edge cases, and trade-off formulas:

/sds-notes ➔ Open project notes
4 modes: per-topic, per-cluster, per-tier, single-file.
Project Directory Support: Projects can live in the default studio repository (~/.system-design-studio/projects/<name>) or in any dedicated workspace or Git repository on your machine. All projects and their notes are tracked in the central multi-project registry.
In-Chat Skill Commands • Universal Across All Agents

Command Your Agent in Chat

Zero terminal commands during learning. Talk naturally to Claude Code, Cursor, Codex, or Antigravity—or use structured slash commands. The agent handles engine scripts silently under the hood.

TIP

Natural Language Fluency: You don't have to memorize slash syntax! Say "Teach me topic 0.1" or "Launch progress tracker on localhost" and your agent will execute the exact same state transitions.

12 COMMANDS • THE HYBRID WORKFLOW
school

Core Pedagogy & Defense

PHASES 1 & 2

Controls the causal teaching loop, interactive simulators, Socratic stress-testing, and defense-gated advancement.

/sds-teach [topic] Deliver Simulator

Renders interactive HTML simulator or Markdown diagram artifact with mandatory jargon unpacking. Prompts for your initial intuition or working hypothesis before exposing physical mechanics.

Natural: "Teach topic 0.1" "Next topic" ➔ render-lesson.py
/sds-discuss Socratic Dialectic

Stress-tests your hypothesis. For seniors, probes cold failure modes and latency bounds. For juniors, provides Socratic scaffolding questions without spoiling the unannounced gate.

Natural: "Here is my trade-off defense..." ➔ Dialectic Engine
/sds-complete [evidence] Sign-Off & Git Commit

Verifies cold trade-off defense against hidden gate in CURRICULUM.md. Ticks topic, logs ADR in DECISIONS.md, advances CURSOR.md, compiles study notes (if auto-notes enabled), and commits atomic state to Git.

Natural: "Mark complete" "Sign off topic" ➔ advance-cursor.py
/sds-status Progress & State

Inspects active topic, verified prerequisites, completion percentage, cognitive anchors, and deferred questions directly from disk.

Natural: "Show progress" "Where are we?" ➔ sync-status.py
folder_shared

Visual Workbench & Safety

PHASES 3 & 4

Localhost visual progress tracker, atomic Git rollback, project-scoped notes, and multi-workspace management.

/sds-dashboard Localhost Workbench

Launches read-only curriculum tracker on http://localhost:8420 in real-time sync with Git. Browse 50-cluster roadmap, test interactive HTML simulators, and read styled Markdown notes.

Natural: "Open dashboard" "Show progress tracker on localhost" ➔ serve-dashboard.py
/sds-rollback Reversible Undo

100% reversible safety net. Undo accidental topic completions or curriculum changes with atomic Git revert and local snapshot restoration (sds rollback --steps N).

Natural: "Undo topic sign-off" "Roll back last topic" ➔ git-checkpoint.py rollback
/sds-notes [topic] Study Notes

Lists active-learning study notes with clickable file:/// links. Auto-compiled on topic completion when enabled, or compiled on-demand when auto-notes is disabled.

Natural: "Show my notes" "Open notes" ➔ manage-projects.py notes
/sds-projects /sds-open <id> /sds-delete <id>

Multi-project instances on one machine. /sds-projects lists all registered instances and track progress. /sds-open <id> switches active context. /sds-delete <id> safely deletes a project instance without touching code.

Natural: "List projects" "Switch to project interview-sprint" ➔ manage-projects.py
/sds-curriculum /sds-config /sds-update

/sds-curriculum mutates syllabus scoped to your project without losing completed progress. /sds-config sets visual themes, output formats, or auto-notes. /sds-update checks for new releases on-demand.

Natural: "Customize syllabus" "Switch theme to slate-clean" ➔ configure-curriculum.py
Aesthetic Engine • settings.json

Five visual styles • Dual Output

Delivered strictly inside standalone interactive HTML simulators across 5 selectable themes, or zero-JS clean Markdown with Mermaid sequence & ASCII state charts.

DEFAULT • DARK

Modern Slate

Deep slate-900 canvas with vibrant blue & indigo accents. Modern developer IDE feel.

slate-clean #0f172a
HIGH READABILITY • LIGHT

Clean Editorial

Warm off-white paper canvas with sharp charcoal typography and crisp ink accents.

editorial-paper #fbfbfa
HIGH CONTRAST • DARK

Cyber Obsidian

Pitch black obsidian canvas with electric cyan and mint neon highlights. Futuristic HUD.

midnight-neon #05070c
POLAR CALM • DARK

Nordic Frost

Subdued arctic cool night palette with frosty teal and snow-storm text. Zero eye strain.

nordic-frost #2e3440
ESPRESSO GLOW • DARK

Warm Amber

Deep espresso stone with rich amber and copper embers designed for nighttime study.

warm-amber #1c1917
Strictly Artifact-First Delivery Protocol

Zero Redundant Chat Lectures • Interactive-First Learning

When entering a new topic, the entire lesson, physical constraints, packet simulator, and reality check are bundled exclusively into the HTML artifact. The chat stays clean with a direct link and discussion hook. All subsequent follow-ups, Q&A, and code traces happen inline directly in chat.

.system-design/settings.json
Custom Save Directories: Configure paths.cursorDir & paths.lessonsDir in settings.json to save cursor state and lessons wherever your repo requires.
Fully Configurable
Curriculum Topology

Five tiers of systems engineering

From network transport and object modeling to distributed systems and mobile client sync across 354 topics.

Tier 0 • 5 Clusters PREREQUISITE

HLD Building Blocks

APIs and transport foundations, database fundamentals, caching patterns, queues and quantitative estimation.

Clusters 0.1 - 0.5 37 Topics
Tier 1 • 14 Clusters OBJECT MODELING

Low-Level Design & Modeling

Entity invariants, LRU/LFU cache evictions, connection poolers, rate limiting algorithms and thread executors.

Clusters 1.1 - 1.14 94 Topics
Tier 2 • 18 Clusters DISTRIBUTED

HLD & Distributed Infra

Consistent hashing, write amplification (B-Tree vs LSM), consensus quorums, event sourcing, CDC and partition rebalancing.

Clusters 2.1 - 2.18 134 Topics
Tier 3 • 11 Clusters CLIENT SYNC

Mobile Systems & Offline Sync

Battery limits, offline mutation queues, optimistic UI reconciliation, SQLite caching, push notification delivery and telemetry.

Clusters 3.1 - 3.11 76 Topics
Tier 4 • 2 Clusters PRODUCTION

ADRs, Reviews & Spaced Gaps

Architecture Decision Records (ADRs), production trade-off defense, mock design reviews and spaced review loops.

Clusters 4.1 - 4.2 13 Topics
Full Syllabus

Explore 50 Clusters

Browse the complete hierarchical syllabus grid, learning paths, and prerequisite graphs.

Browse Full Syllabus
Beyond Standard Syllabus

Engineered for Teams & Portfolios

Bring your company's internal tech stack or graduate with an interview-ready proof-of-work portfolio.

Team Onboarding BYO CURRICULUM

Bring Your Own Curriculum

Onboarding new engineers to a complex proprietary stack? Replace or extend CURRICULUM.md with your team's internal services, event brokers, storage layers, and architectural standards.

The AI tutor guides new hires through your company's exact topology topic by topic, verifying architectural principles with the same defense gates before they push to production.

Format: Standard Markdown Syllabus Zero Schema Migration
Interview Proof-of-Work DECISIONS.MD

Your Built-In ADR Portfolio

Every time you defend a design trade-off at the sign-off gate, the studio logs your architectural reasoning into DECISIONS.md as formal Architectural Decision Records.

Instead of abstract claims on your resume, you graduate with a Git-committed proof-of-work portfolio demonstrating deep trade-off evaluation under real latency, cost, and consistency constraints.

Output: Production-Grade ADRs Interview-Ready Artifact
Design Contrast

Comparison

How persistent file-based tutoring compares to a plain conversational chat.

Dimension A Plain AI Chat System Design Studio
Advancement Gate Nod-along agreement with no verification; advances whenever asked. The Sign-Off Gate: Lesson hides tick-off scenario; won't advance until you defend trade-offs in chat.
State Across Sessions Kept in conversational context window; lost when thread resets or model changes. Saved to CURSOR.md in Git; preserved across sessions and model switches.
Teaching Approach Text summaries and definitions generated per prompt. Step-by-step topic curriculum anchored in hardware latency numbers.
Delivery Artifacts Markdown codeblocks and text replies in chat. Standalone interactive HTML files with state and packet simulators in .system-design/lessons/.
Decision Records Ephemeral reasoning lost when context window rolls over. Logs your defenses into DECISIONS.md as an interview-ready ADR portfolio.
Example Tracking No record of previous analogies or examples across sessions. Logged in examplesTaken within CURSOR.md to avoid repeating scenarios.
Curriculum Scope & Teams Ad-hoc question answering with no shared curriculum across team members. Indexed 50 clusters in CURRICULUM.md; supports custom company stacks for onboarding.
Ready to turn your agent into a tutor?

Initialize your studio in 30 seconds.

Zero dependencies besides Git and Bash. Free and open source under MIT.

Community Powered • Zero Venture Capital

Support the Project

If System Design Studio untangled a tricky concept or made your prep a little easier, consider buying me a coffee ☕ or sponsoring my work.

⭐ Not in a coffee mood? No worries! A free Star on GitHub costs nothing but makes my day.

Happy designing, and thanks for being here!