{"id":"7c1e73f9-2f9c-47e8-9099-76278624816f","slug":"design-software-systems","kind":"skill","name":"design-software-systems","summary":"Portable Agent Skill for system design, architecture review, and safe evolution: capacity, invariants, failures, and trade-offs.","owner":"woodencatjskim","repoUrl":"https://github.com/woodencatjskim/design-software-systems","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-10-22T02:54:44.000Z","addedAt":"2026-11-01T02:04:30.710Z","logoUrl":"https://avatars.githubusercontent.com/u/46584580?u=8d3e41207f7343b7e8acc57f08371528159769fc&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["design-media","developer-tools"],"tags":["ai-agents","architecture-review","claude-code","codex","cursor","distributed-systems","software-architecture","system-design"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-11-01T02:19:39.513Z","sample":false,"url":"https://conduits.dev/tools/design-software-systems","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Design Software Systems\n\n[한국어](README.ko.md) · [Skill instructions](skills/design-software-systems/SKILL.md) · [Evaluation](evals/README.md) · [Sources](docs/sources.md)\n\nAn open Agent Skill for **system design, architecture review, and evolving existing software**. Turn requirements into a proportionate design with capacity estimates, data/API contracts, explicit trade-offs, and concrete correctness checks.\n\nUse it to answer questions such as:\n\n- What is the smallest architecture that meets our workload and operating constraints?\n- Can two users reserve the last available room?\n- What happens if a server crashes immediately after acknowledging a message?\n- How can we change a schema while older clients are still running?\n\n## Install\n\n```bash\nnpx skills add woodencatjskim/design-software-systems --skill design-software-systems\n```\n\nChoose your agent in the installer. For a specific target:\n\n```bash\nnpx skills add woodencatjskim/design-software-systems --skill design-software-systems -a codex\nnpx skills add woodencatjskim/design-software-systems --skill design-software-systems -a claude-code\nnpx skills add woodencatjskim/design-software-systems --skill design-software-systems -a cursor\n```\n\nThe Skills CLI requires Node.js; use the version required by its [current installation documentation](https://github.com/vercel-labs/skills). The installed skill itself is Markdown and YAML: no Python, Node.js, API key, MCP server, or renderer is required to read and follow it.\n\nFor manual installation, copy the **entire** `skills/design-software-systems/` directory into your agent's documented skill location. Copying only `SKILL.md` loses the references. See [compatibility and what was actually tested](docs/compatibility.md).\n\nThe [releases page](https://github.com/woodencatjskim/design-software-systems/releases) also provides a standalone skill ZIP with a SHA-256 checksum for manual installation.\n\n## Use\n\nSelect `design-software-systems` using your agent's skill mechanism, then describe the problem. In Codex, explicitly invoke it with `$design-software-systems`. Other agents have their own invocation conventions.\n\n```text\nUse design-software-systems to design a private file-sharing service for\n5,000 employees. We already use PostgreSQL and object storage. Explain\ntenant authorization, upload failure recovery, and when a CDN would help.\n```\n\n```text\nReview this booking design with design-software-systems. Check simultaneous\nreservations, duplicate requests, expired holds, and delayed payment results.\n```\n\n```text\nUse design-software-systems to plan this API change from the current repository.\nPreserve older clients and explain the rollout, backfill, and rollback limits.\n```\n\nInstructions are in English; answers follow the user's language. Important missing requirements are surfaced, and assumptions remain explicit.\n\n## What you get\n\n| Task | Result |\n|---|---|\n| New system | Scope, estimates, data/API contracts, minimal architecture, critical flows, verification plan |\n| Existing system | Evidence from relevant code and docs, targeted change, compatibility and migration plan |\n| Architecture review | Prioritized findings with evidence, failure scenarios, remedies, and unknowns |\n| Small decision | A concise recommendation and a condition for revisiting it |\n\nThe workflow connects requirements → invariants and workload → data/contracts and components → failure behavior → decisions and verification. It adds components only when a requirement or evidence justifies them. It does not require a microservices stack or a lengthy document for every question.\n\nDomain references cover [content delivery](skills/design-software-systems/references/content-delivery.md), [transactional inventory](skills/design-software-systems/references/transactional-inventory.md), and [realtime messaging](skills/design-software-systems/references/realtime-messaging.md). They are loaded only when relevant.\n\nFor repository reviews, the [review procedure](skills/design-software-systems/references/repository-review.md) traces other writers and observable outputs, constructs a concrete failure sequence, and checks whether existing safeguards disprove it. Findings distinguish demonstrated defects, conditional risks, and unresolved evidence. The [security reference](skills/design-software-systems/references/security-and-trust-boundaries.md) covers relevant identity, tenant, derived-data, and revocation boundaries. A protected path can correctly produce no finding.\n\n## Examples\n\n- [Small document catalog](examples/small-document-catalog.md): a deliberately simple architecture.\n- [Hotel booking](examples/hotel-booking.md): atomic allocation and uncertain payments.\n- [Messaging review](examples/messaging-review.md): durability and latency contradictions.\n\nThese are illustrative design notes, not deployed systems or measured performance claims. Outputs normally use Markdown and optional Mermaid/text diagrams. No HTML renderer or additional skill is needed.\n\n## Quality and limits\n\nThe repository includes a package validator, regression tests, eight behavioral prompts, and a recorded comparison with an ordinary agent and Anthropic's basic system-design guidance. See [the evaluation record](evals/README.md) for actual results and limitations. Static checks do not prove architectural correctness, and a small model-assisted evaluation does not establish general superiority.\n\nThe [repository review suite](evals/repository-review/README.md) adds three matched defect/protected pairs and one missing-evidence case. Executable controls establish what the supplied SQLite fixtures actually do; model responses are evaluated separately. These are development fixtures, not an unseen benchmark or a production reliability test.\n\nThe skill does not deploy infrastructure or guarantee throughput, availability, security, or recovery. Those promises require implementation, measurement, and review. Product-specific guarantees should be checked against the deployed version's official documentation.\n\n## Development\n\nPython 3.11+ is needed only for repository validation:\n\n```bash\npython -m pip install -r requirements-dev.txt\npython scripts/validate.py\npython -m unittest discover -s tests -v\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for making a focused change and recording behavioral evidence.\n\n## Inspiration and attribution\n\nDeveloped with reference to **[Design Software Systems Like a Senior Engineer – Complete Course](https://www.youtube.com/watch?v=soTfFFIQQ8U)** by **Hayk Simonyan**, published on **freeCodeCamp.org**. The course informed the design workflow and the music, booking, and messaging problem families. Technical qualifications and additional failure-handling guidance are our own analysis, linked to primary documentation.\n\nWe also studied existing public architecture skills to improve evidence handling, scope control, and decision records. [Sources and design influences](docs/sources.md) describe what informed this work. This is an independent project, not an official course companion or an endorsement by the instructor, freeCodeCamp, or the benchmark authors. No full transcript or video assets are redistributed.\n\n## License\n\n[MIT](LICENSE) for this repository's original materials. Linked external materials retain their own licenses.\n"}