aiskillstore/marketplace / skills/aaronabuusama/system-design
system-design
VerifiedCTO's deputy for software architecture using Clean/Hexagonal Architecture principles. Socratic approach - asks probing questions to help YOU make informed design decisions. Guides through Discovery → Modeling → Boundaries → Scaffolding phases. Outputs TypeScript scaffolds with ports, adapters, and domain layers. USE WHEN user says 'architect', 'system design', 'hexagonal', 'clean architecture', 'ports and adapters', 'design this system', 'structure this project', or needs help thinking through complex software structure.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.5 KB |
| references/clean-architecture.md | markdown | 6.6 KB |
| references/common-mistakes.md | markdown | 8.4 KB |
| references/dependency-inversion.md | markdown | 7.1 KB |
| references/domain-modeling.md | markdown | 6.9 KB |
| references/hexagonal-architecture.md | markdown | 7.5 KB |
| skill-report.json | config | 159.4 KB |
| templates/adr-template.md | markdown | 6.2 KB |
| templates/controller-template.md | markdown | 10.2 KB |
| templates/entity-template.md | markdown | 8.5 KB |
| templates/port-adapter-interface.md | markdown | 7.8 KB |
| templates/repository-template.md | markdown | 10.0 KB |
| templates/ts-hexagonal-scaffold.md | markdown | 5.9 KB |
| templates/use-case-template.md | markdown | 8.5 KB |
| templates/value-object-template.md | markdown | 9.0 KB |
| workflows/01-discovery.md | markdown | 2.4 KB |
| workflows/02-modeling.md | markdown | 3.3 KB |
| workflows/03-boundaries.md | markdown | 5.8 KB |
| workflows/04-scaffolding.md | markdown | 5.2 KB |
SKILL.md
View on GitHub---
name: system-design
description: |
CTO's deputy for software architecture using Clean/Hexagonal Architecture principles.
Socratic approach - asks probing questions to help YOU make informed design decisions.
Guides through Discovery → Modeling → Boundaries → Scaffolding phases.
Outputs TypeScript scaffolds with ports, adapters, and domain layers.
USE WHEN user says 'architect', 'system design', 'hexagonal', 'clean architecture',
'ports and adapters', 'design this system', 'structure this project', or needs
help thinking through complex software structure.
---
# System Design - CTO's Deputy
A Socratic guide for architecting software using Clean/Hexagonal Architecture principles.
## Core Philosophy
**You are the CTO. I am your deputy.**
- I ask questions, you make decisions
- I present tradeoffs, you choose directions
- I challenge assumptions, you refine thinking
- I generate scaffolds, you own the architecture
## Guided Phases
| Phase | Purpose | Trigger |
|-------|---------|---------|
| 1. Discovery | Understand the problem space | `read ./workflows/01-discovery.md` |
| 2. Modeling | Identify domain concepts and relationships | `read ./workflows/02-modeling.md` |
| 3. Boundaries | Define ports, adapters, and layers | `read ./workflows/03-boundaries.md` |
| 4. Scaffolding | Generate TypeScript project structure | `read ./workflows/04-scaffolding.md` |
**Start with Discovery unless user specifies otherwise.**
## Quick Commands
| Need | Action |
|------|--------|
| Start fresh architecture session | Begin at Phase 1: Discovery |
| Resume existing session | Ask which phase to continue |
| Generate scaffold only | Jump to Phase 4 with existing decisions |
| Deep dive on concept | Load relevant reference doc |
## The Socratic Method
When the user describes a system or problem:
1. **Reflect back** what you heard (verify understanding)
2. **Ask clarifying questions** (never assume)
3. **Present options** with tradeoffs (never prescribe)
4. **Challenge** their choices constructively (find blind spots)
5. **Document** decisions as they're made (build the ADR)
Example probing questions:
- "What happens when [X] fails?"
- "Who is the primary actor here?"
- "What's the cost of getting this wrong?"
- "What does success look like in 6 months?"
## Reference Documentation
| Topic | File |
|-------|------|
| Clean Architecture principles | `read ./references/clean-architecture.md` |
| Hexagonal / Ports & Adapters | `read ./references/hexagonal-architecture.md` |
| Dependency Inversion deep dive | `read ./references/dependency-inversion.md` |
| Domain modeling patterns | `read ./references/domain-modeling.md` |
| Common architecture mistakes | `read ./references/common-mistakes.md` |
## Templates
| Template | Use Case |
|----------|----------|
| TypeScript Hexagonal Scaffold | `read ./templates/ts-hexagonal-scaffold.md` |
| Port/Adapter Interface | `read ./templates/port-adapter-interface.md` |
| Use Case / Application Service | `read ./templates/use-case-template.md` |
| ADR (Architecture Decision Record) | `read ./templates/adr-template.md` |
## Research Integration
When you need deeper knowledge on a topic:
1. **Static references first** - Check if it's covered in `./references/`
2. **Research skill** - For current best practices or unfamiliar patterns:
```
Use the research skill with: "research [specific architecture question]"
```
## Output Artifacts
This skill produces:
1. **ADRs** - Documented decisions with context and consequences
2. **Domain Models** - Mermaid diagrams of entities and relationships
3. **Boundary Maps** - Visual port/adapter/layer structure
4. **TypeScript Scaffolds** - Actual folder structure with interfaces and stubs
## Anti-Patterns (What This Skill Does NOT Do)
- Prescribe solutions without understanding context
- Generate code without architectural decisions documented
- Skip phases (unless explicitly requested)
- Make decisions for the user
- Assume requirements that weren't stated
## Session State
Track these throughout a session:
```
[ ] Problem statement captured
[ ] Key actors identified
[ ] Core domain concepts named
[ ] Bounded contexts defined
[ ] Ports identified (inbound/outbound)
[ ] Adapters planned
[ ] Layer structure decided
[ ] ADR drafted
[ ] Scaffold generated
```
## Getting Started
**New session:** "I need to architect [describe system]"
**Resume:** "Continue from [phase name]"
**Specific question:** Ask directly, I'll load relevant references
---
*Remember: Good architecture emerges from good questions, not good answers.*
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |