# system-design-skills

> A set of 22 composable system-design skills for Claude Code, Codex and Agent Plugins hosts that guide reasoning-based architecture design.

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.

## Features
- 22 composable skills: orchestrator, diagram engine and 20 building blocks
- /design command and system-design-orchestrator agent
- Clarify, estimate, design, trade-offs, failure modes, iterate loop
- Back-of-the-envelope calculator script
- Self-contained HTML+SVG architecture diagrams with optional PNG/PDF export
- Scored design docs saved to docs/design/
- Cloud provider variants for AWS, Azure, GCP and Temporal
- Eval harness and interview study path
- No runtime, server or API keys required

## Integrations
Claude Code, OpenAI Codex, Cursor, Copilot CLI, Agent Plugins, AWS, Azure, GCP, Temporal

## Platforms
ANDROID, IOS, WEB, API, CLI

## Pricing
Open Source

## Links
- Website: https://proyecto26.com/system-design-skills/
- Documentation: https://proyecto26.github.io/system-design-skills/
- Repository: https://github.com/proyecto26/system-design-skills
- EveryDev.ai: https://www.everydev.ai/tools/system-design-skills