System Design Agent Skill

System Design (orchestrator)

Drive an open-ended design problem from a vague prompt to a justified,

stress-tested architecture — by reasoning, not by recalling a diagram. This

skill owns the *method* and the *routing*; the actual component recipes live in

focused building-block skills it pulls in as needed.

The single most important idea, from which everything here follows:

> Do not memorize architectures; learn the forces that shape them. There is no

> single correct solution — success depends on the assumptions you make explicit.

A design that works for 1,000 users may fail at 1,000,000. Treat every

architecture as a hypothesis that holds until a constraint changes, and be

ready to redraw it calmly when one does.

The reasoning loop

Work this loop out loud. It is a loop, not a checklist — late steps routinely

send you back to early ones, and that is the point.

• Clarify requirements — turn the vague prompt into functional

requirements, non-functional constraints, and an explicit *out of scope*.

Scope to a few core features; say so. → skill requirements-scoping

• Estimate scale — back-of-the-envelope QPS, storage, bandwidth, read/write

ratio. Numbers decide the design; "high traffic" does not. → skill

back-of-the-envelope

• Propose a high-level design — sketch the boxes and arrows (clients, LB,

services, stores, caches, queues, CDN) and the user-facing API. Get buy-in

before going deep. → skill api-design, plus the building blocks below.

• Evaluate trade-offs — for every major choice, state what it solves, what

it worsens, and what would make you change it. Never name a tool without

this. → reference tradeoff-framework.md

• Stress-test failure modes — find single points of failure, decide the

degradation story, plan recovery. Assume every component breaks. → skill

resilience-failure

• Iterate / deep-dive — pick the most interesting or fragile component and

go deep; let new constraints ("what if writes 10×?", "lose a region?") drive

a redesign of the affected part.

These six steps are the same four activities the GUIDE names —

**ask refining questions → handle the data → discuss components → discuss

trade-offs** — with estimation and failure-testing made explicit. See

references/reasoning-loop.md for the full walk-through and time budgeting.

Routing to building blocks

This plugin is a wiki of composable parts. As each concern comes up in the loop,

invoke the focused skill (via the Skill tool) rather than reconstructing its

recipe from memory — load it so the options, trade-off table, behavior under

stress, and cloud-provider variants come from the skill itself. That invocation

is how composition works at runtime: a bare skill name below is a skill to

*trigger*, not a file to read. Invoke each as its concern becomes active:

| When the problem turns to… | Use skill |

|---|---|

| What features / constraints / scope? | requirements-scoping |

| How many QPS, how much storage, how many servers? | back-of-the-envelope |

| Endpoints, request/response, pagination, idempotency | api-design |

| Monolith vs microservices, service boundaries, gateway, discovery | service-decomposition |

| SQL vs NoSQL, schema, indexing, sharding, replication | data-storage |

| What to cache, eviction, invalidation, hot keys | caching |

| Distributing traffic, L4/L7, health checks | load-balancing |

| Async work, queues vs streams, delivery guarantees | messaging-streaming |

| CAP, consistency models, quorum, consensus, hashing | consistency-coordination |

| Fault tolerance, circuit breakers, degradation, rate limiting | resilience-failure |

| Static/media delivery, edge, geo-routing | content-delivery |

| How the design evolves with 10×/100× growth | scaling-evolution |

| How clients resolve the service, geo/failover routing | dns |

| Unique IDs at scale (Snowflake/UUID/ticket) | sequencer |

| Storing large/unstructured objects (images, video, files) | blob-store |

| Metrics/logs/traces, health checks, SLOs, alerting | observability |

| High-volume log collection/shipping/retention | distributed-logging |

| Full-text search, inverted index, autocomplete | distributed-search |

| Background / scheduled / recurring jobs | task-scheduling |

| Counting likes/views at huge write rates | sharded-counters |

| Drawing/visualizing the architecture | architecture-diagram |

Full descriptions, the bottom-up layering, and "which block answers which

question" are in references/building-blocks-index.md (the canonical 21-block

catalog). Trigger a block directly when the user asks about just that part — the

orchestrator is not required for every question.

Guardrails: the ways designs fail

The GUIDE catalogs ten failure modes. They are not about wrong answers; they are

about wrong *signals*. Keep these reflexes (full list and antidotes in

references/failure-modes.md):

• Clarify before designing. Rushing to a solution signals memorization.
• Quantify before choosing. Convert "heavy traffic" into numbers first.
• Justify every component. Three questions per choice: solves / worsens /

when-to-change. "Industry standard" is not a justification.

• Open building blocks, don't name them. Know how a cache, queue, or DB

behaves under stress — not just what it is called.

• Design for failure. "Add more retries" usually amplifies an outage.
• Make interfaces concrete. If you can't write the request, response, and

primary key, the diagram is guesswork.

• Treat the architecture as a hypothesis. If a small constraint change

collapses the whole design, it was memorized, not reasoned.

Collaborate; do not present

A design discussion is a working session, not a lecture. Propose, invite the

critique, and adapt in real time. When a constraint changes, name which earlier

assumption it invalidates and redesign that part — defending a sunk design is a

worse signal than a flawed first idea. See references/collaboration-playbook.md

for how to narrate, handle curveballs, and pivot.

When requirements are genuinely ambiguous and the answer changes the design,

ask the user a clarifying question rather than guessing silently.

Producing the design

• Capture scope in assets/requirements-template.md (functional /

non-functional / out-of-scope / assumptions).

• Write up the design with assets/design-doc-template.md — it threads the

reasoning loop, so the trade-offs and failure story are first-class, not

footnotes.

• Diagram with the in-plugin architecture-diagram skill — a self-contained

dark-theme HTML+SVG generator that ships in this plugin (no external

dependency). A quick ASCII sketch is fine for early thinking; render properly

once the design is clear. See references/diagramming.md for what to draw at

each step and how to specify a diagram to that skill.

• Persist it so the work survives the conversation: write the requirements and

design doc to a file (suggest docs/design/<system>.md; ask the user where if

unsure). Keep trade-off exploration and constraint back-and-forth in the

conversation; commit the settled artifacts (scope, design, key decisions, data

model, diagram) to the file.

• Score & diagnose before wrapping: rate the design with the quality bar and

run the Quick Diagnostic in references/failure-modes.md, and state the weakest

dimension + what would raise it.

Answer contract

What the user reads must show the reasoning, not just contain it. Every design

answer (first pass or revision) includes, in the reply itself:

• A decisions table — one row per major choice (at least three for a full

design): Decision | Solves | Worsens | Change it when…. The last column is a

concrete trigger — a number or observable signal ("write QPS > 50k on one

shard", "a second team needs independent deploys"), never "if needed".

• A closing weakest-point line — the part of this design that breaks first

as load or requirements grow, and the move you would make then.

A pros/cons list, or trade-offs for only one choice, does not meet the bar.

Running it as a workflow

Two entry points drive this skill as a repeatable process:

• /design <system> — the slash command that runs the full loop on a problem.
• system-design-orchestrator — the agent the command dispatches to; it loads

this skill, then invokes the building-block skills as each concern arises.

Both compose the same blocks listed above — invoke a block skill when its concern

is active rather than reconstructing its recipe from memory.

References

• references/reasoning-loop.md — the six-step loop in depth, with the news-feed walk-through and 45-minute time budget. Read when running a full design.
• references/failure-modes.md — the ten failure modes and their antidotes. Read to self-check a design or diagnose why one isn't landing.
• references/tradeoff-framework.md — the solves/worsens/when-to-change method and common axis trade-offs (latency↔throughput, consistency↔availability, cost↔complexity). Read at step 4.
• references/building-blocks-index.md — the full wiki index: every block, what it answers, and how blocks combine. Read to route.
• references/collaboration-playbook.md — narrating, handling curveballs, pivoting on constraint changes. Read when the discussion gets adversarial.
• references/diagramming.md — what to draw at each loop step and how to specify a diagram to the architecture-diagram skill. Read when drawing.
• references/worked-example-news-feed.md — one end-to-end pass of the loop, shown as reasoning (not a template to memorize).

Assets

• assets/requirements-template.md — functional / non-functional / scope / assumptions capture.
• assets/design-doc-template.md — a design write-up structured around the reasoning loop.