System Design

Diagnose design problems and guide architecture decisions for solo developers

191 stars 24 forksSoftware Development

Install

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add jwynia/agent-skills --skill system-design
Manual install
git clone --depth 1 https://github.com/jwynia/agent-skills.git /tmp/agent-skills
mkdir -p ~/.claude/skills
cp -r /tmp/agent-skills/skills/tech/development/architecture/system-design ~/.claude/skills/system-design

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

# 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"
Read the full skill on GitHub

Details

Skill name
system-design
Path
skills/tech/development/architecture/system-design/SKILL.md
Repo updated
24 February 2026

FAQ

What does the System Design skill do?

Diagnose design problems and guide architecture decisions for solo developers

How do I install the System Design skill?

skills CLI (Claude Code, Cursor, Codex and more): npx skills add jwynia/agent-skills --skill system-design. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is System Design popular?

It lives in jwynia/agent-skills, which has 191 GitHub stars and 24 forks.

Related skills

Abstract Strategy

191

jwynia/agent-skills

Design abstract strategy games with perfect information, no randomness, and strategic depth. Use when designing a board game, exploring abstract strategy games, brainstorming game mechanics, or evaluating game balance. Keywords: board game, game design, strategy, mechanics, balance.

Other24

Adaptation Synthesis

191

jwynia/agent-skills

Synthesize new works from extracted functional DNA documents. Use when adapting a source work to a new context, when combining multiple source extractions, or when generating variations that preserve function while changing form.

Other24

Agent Bootstrap

191

jwynia/agent-skills

Bootstrap agentic development environment from agent.toml manifest

AI, LLMs & Agents24

Ts Google

228

pproenca/dot-skills

Google TypeScript style guide for writing clean, consistent, type-safe code. This skill should be used when writing, reviewing, or refactoring TypeScript code. Triggers on TypeScript files, type annotations, module imports, class design, and code style decisions.

Software Development19

Stripe Inspired API Design Rules

228

pproenca/dot-skills

JSON HTTP API design rules distilled from Stripe — resource modeling, identifier schemes, URL structure, request/response wire format, pagination, errors, idempotency, versioning, naming, webhooks, and authentication. Triggers on tasks involving OpenAPI specs, API design reviews, schema decisions, endpoint shaping, error envelope design, webhook delivery, or any "is this API well-designed" question. Apply when designing, reviewing, or refactoring a JSON HTTP API — even when the user doesn't mention Stripe by name, since the rules are general API-design principles distilled from the industry's

Software Development19

Typescript

228

pproenca/dot-skills

TypeScript performance, tsconfig, type errors, async patterns — triggered when the user asks to "optimize TypeScript performance", "speed up tsc compilation", "configure tsconfig.json", "fix type errors", "improve async patterns", or encounters TS errors (TS2322, TS2339, "is not assignable to"). Also triggers on .ts, .tsx, .d.ts file work involving type definitions, module organization, or memory management. Does NOT cover TypeScript basics, framework-specific patterns, or testing.

Software Development19

Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.