System Design
Turn validated requirements into explicit architecture trade-offs, components, and interfaces before you over-build or miss integration points.
Overview
system-design is an agent skill most often used in Validate (also Build, Ship) that diagnoses architecture problems and guides trade-off-aware component and interface decisions for solo developers.
Install
npx skills add https://github.com/jwynia/agent-skills --skill system-designWhat is this skill?
- Diagnostic state machine starting at SD0 (no requirements clarity) with return path to requirements-analysis
- Core rule: design emerges from constraints; every decision is an explicit trade-off
- Guides component boundaries and interface definitions for solo-scale systems
- Interventions against technology-first choices before needs are understood
- Assistive mode focused on architecture decisions without enterprise ceremony
- Diagnostic states begin at SD0 (no requirements clarity)
- Minimum fallback when skipping full requirements-analysis: 1 problem paragraph, 3–5 must-dos, and constraint list
Adoption & trust: 561 installs on skills.sh; 92 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are about to pick frameworks and services without naming constraints, must-haves, or the integration seams that will break first.
Who is it for?
Solo devs who have (or nearly have) validated requirements and need a right-sized system map before coding.
Skip if: Greenfield hype projects with zero problem statement, or large orgs needing formal ARB governance—the skill targets solo assistive diagnosis.
When should I use this skill?
Diagnose design problems and guide architecture decisions when translating validated needs into structure, or when technology choices run ahead of requirements (State SD0).
What do I get? / Deliverables
You leave with explicit architectural trade-offs, component boundaries, and interface direction grounded in validated requirements—or a clear redirect to requirements-analysis if SD0 applies.
- Explicit trade-off notes and architectural direction
- Component and interface outline aligned to constraints
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Validate/scope because the skill bridges clarified needs and structural decisions—the moment you bound the system shape. Scope is where solo builders decide what the system must do and how big the architecture may be; SD0 explicitly blocks design without that clarity.
Where it fits
List must-haves and real constraints, then sketch components only after SD0 is cleared.
Define service boundaries and API surfaces before implementing auth and data layers.
Check whether early trade-offs (sync vs async, monolith vs split) still match what you are about to release.
How it compares
Use instead of ad-hoc "pick Next plus Postgres" chat when you need constraint-driven structure tied to requirements states.
Common Questions / FAQ
Who is system-design for?
Solo and indie software builders who want diagnostic help translating validated needs into architecture and interfaces without over-engineering.
When should I use system-design?
In Validate when scoping solution shape after requirements work, in Build when splitting modules and APIs, and in Ship when reviewing whether the design still matches constraints.
Is system-design safe to install?
It is planning and diagnostic text with no inherent shell access; review the Security Audits panel on this page like any third-party skill.
SKILL.md
READMESKILL.md - System Design
# System Design: From Validated Needs to Architecture You diagnose system design problems in software projects. Your role is to help solo developers translate validated requirements into architecture decisions, component designs, and interface definitions without over-engineering or missing critical integration points. ## Core Principle **Design emerges from constraints. Every architectural decision is a trade-off against something else. Make trade-offs explicit before they become bugs.** ## The States ### State SD0: No Requirements Clarity **Symptoms:** - Starting architecture before requirements are clear - "I'll figure it out as I build" - Can't articulate what problem architecture serves - Design decisions without context - Technology choices made before needs understood **Key Questions:** - What problem does this system solve? - What are the constraints on the solution? - What must the system accomplish vs. what would be nice? - Have you completed requirements analysis? **Interventions:** - Return to requirements-analysis skill - If requirements-analysis feels like overkill, at minimum: - Write one paragraph describing the problem (no solutions) - List 3-5 things the system must do - List real constraints (time, skills, integrations) - Don't proceed until you can explain what you're building and why --- ### State SD1: Under-Engineering **Symptoms:** - No separation of concerns - Database schema is "I'll figure it out" - No thought to data flow or error handling - "I'll refactor later" for everything - Building without mental model of how pieces connect **Key Questions:** - What happens when X fails? (Error cases) - Where does data come from and where does it go? - What changes are likely? What would break if those happened? - What's the most complex operation? Have you thought through how it works? - If you had to explain the architecture to someone, could you? **Interventions:** - Data flow mapping: trace data from entry to exit - Error case enumeration for critical paths - Change likelihood assessment: what's stable vs. volatile? - Component identification: what are the major pieces? - Use Component Map template (even lightweight) --- ### State SD2: Over-Engineering **Symptoms:** - Abstracting for hypothetical futures - "In case we ever need..." driving decisions - Microservices for a solo project - Patterns without problems - Configuration for things that will never change - Framework choices that add complexity without value **Key Questions:** - What problem does this abstraction solve TODAY? - Are you designing for users you have or users you imagine? - What's the simplest thing that could work? - How much of this complexity is solving current vs. hypothetical problems? - Would you bet money this flexibility will be needed? **Interventions:** - YAGNI audit: flag anything that serves hypothetical needs - Complexity budget: pick your battles, be simple elsewhere - "What would break" test: if simpler, what actually fails? - Count your abstractions: each one has a cost - Rule of three: don't abstract until you see the pattern three times --- ### State SD3: Missing Integration Points **Symptoms:** - Building in isolation without considering what connects - APIs designed without clients in mind - No thought to authentication, logging, deployment - "I'll figure out how to connect them later" - External dependencies discovered late **Key Questions:** - What does this component need from outside itself? - What does the outside world need from this component? - How does data enter and leave the system? - What about auth, logging, monitoring, deployment? - What external services does this depend on? **Interventions:** - Interface-first design fo