system-design-skills

system-design-skills is an open-source skill collection from Proyecto 26 that helps engineers design scalable systems by reasoning through requirements, numbers and trade-offs rather than recalling memorized diagrams. It ships 22 skills for Claude Code, OpenAI Codex and other Agent Plugins hosts, released under the MIT license.

What It Is

The project is a divide-and-conquer wiki of agent skills: one orchestrator, one diagram engine and 20 building-block skills, each covering one part of a system. Every block follows a shared contract covering when to use it, what to clarify first, options, trade-offs, behavior under stress, numbers that matter and cloud-provider variants (AWS, Azure, GCP, plus Temporal for durable execution). It needs no runtime, server or API keys; the only scripted component is a stdlib Python calculator for back-of-the-envelope estimates.

How the reasoning loop works

A design runs through clarify, estimate, design, trade-offs, failure modes and iterate. When a constraint changes, the loop re-enters at the affected phase and redesigns only that part. The /design <system> command or the orchestrator agent invokes the relevant building-block skills, renders a self-contained HTML+SVG architecture diagram, and writes a scored design document to docs/design/.

The building-block catalog

Blocks are arranged bottom-up in layers L0 to L7: frame (requirements-scoping, back-of-the-envelope), edge (dns, load-balancing, content-delivery), services (api-design, service-decomposition), state (data-storage, caching, blob-store, sequencer, sharded-counters, distributed-search), async (messaging-streaming, task-scheduling), correctness (consistency-coordination), ops (resilience-failure, observability, distributed-logging) and growth (scaling-evolution). Each layer depends only on those beneath it.

Ways to use it

Users can run the full /design workflow, start a conversational design through the system-design skill, or trigger a single block such as a caching or SQL-vs-NoSQL question. Install via npx skills add proyecto26/system-design-skills or as a Claude Code plugin; Codex loads the skills, while the /design command and orchestrator agent are Claude Code components. The README reports an eval of 30/30 with skills versus 20/30 baseline on a WhatsApp design exercise.

Known limitations

The README notes that the reasoning is judgment-based rather than deterministic, provider quotas may drift and should be verified against current docs, and the optional PNG/PDF diagram export relies on two CDN scripts.