architecture-selection — Claude Code skill: architecture and install
architecture-selection is a Claude Code skill that compares architecture patterns against project needs and documents a recommendation. It supports system planning, scalability reviews, and technology choices.
MIT ★ 587 updated 2026-10-26
/plugin marketplace add rsmdt/the-startup
/plugin install team@the-startupWhat architecture-selection does
The skill gathers project criteria such as domain complexity, scaling needs, operational maturity, and delivery timelines. It then scores at least two architecture patterns and records the trade-offs. Team capabilities matter alongside technical fit, so a recommendation accounts for who will operate the system.
Technology choices use a weighted matrix covering fit, maturity, team skills, performance, operations, and cost. The decision is written as an ADR with context, consequences, and alternatives. The skill points to reference material on architecture patterns, C4 diagrams, and scalability; it also advises measuring bottlenecks before scaling.
What it helps with
- compare monolith and microservices for a project
- weigh operational maturity against architecture choices
- write an ADR with alternatives and consequences
- outline an incremental architecture migration
Example prompts for the agent
- Compare a monolith with microservices for this project and explain the trade-offs.
- Draft an ADR for an event-driven architecture and outline a migration path.
How to install architecture-selection
1Plugin marketplace
/plugin marketplace add rsmdt/the-startup/plugin install team@the-startupThis installs the whole team plugin with all its skills
2Skills CLI (Vercel)
npx skills add rsmdt/the-startup --skill architecture-selection -a claude-code3Manually: put the files in place
~/.claude/skills/architecture-selection/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/architecture-selection/
1Skills CLI (Vercel)
npx skills add rsmdt/the-startup --skill architecture-selection -a codex2Manually: put the files in place
.agents/skills/architecture-selection/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add rsmdt/the-startup --skill architecture-selection -a cursor2Manually: put the files in place
.cursor/skills/architecture-selection/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install rsmdt/the-startup plugins/team/skills/development/architecture-selection2Manually: put the files in place
.github/skills/architecture-selection/SKILL.md1Skills CLI (Vercel)
npx skills add rsmdt/the-startup --skill architecture-selection -a gemini-cli2Platform CLI
gemini skills install https://github.com/rsmdt/the-startup --path plugins/team/skills/development/architecture-selectionManually: put the files in place
.devin/skills/architecture-selection/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about architecture-selection
How do I install architecture-selection in Claude Code?
Add the marketplace with /plugin marketplace add rsmdt/the-startup, then install the plugin with /plugin install team@the-startup.
What does architecture-selection do?
It evaluates architecture patterns and technologies against project requirements, team capabilities, and operational needs. It can structure the decision as an ADR and describe a migration path.
How are technology options scored?
The weighted matrix assigns 25% to fit, 15% to maturity, 20% to team skills, 15% each to performance and operations, and 10% to cost.
Source text
SKILL.md · MIT
---
name: architecture-selection
description: System architecture patterns including monolith, microservices, event-driven, and serverless, with C4 modeling, scalability strategies, and technology selection criteria. Use when designing system architectures, evaluating patterns, or planning scalability.
---
## Persona
Act as a system architecture advisor who guides teams in selecting and implementing architecture patterns matched to their requirements, team capabilities, and scalability needs. You balance pragmatism with forward-thinking design.
**Architecture Target**: $ARGUMENTS
## Interface
EvaluationCriteria {
teamSize: string // e.g., "< 10", "> 20"
domainComplexity: SIMPLE | MEDIUM | COMPLEX
scalingNeeds: UNIFORM | VARIED | ASYNC | UNPREDICTABLE
opsMaturity: LOW | MEDIUM | HIGH
timeToMarket: FAST | MEDIUM | SLOW
}
ArchitectureRecommendation {
pattern: MONOLITH | MICROSERVICES | EVENT_DRIVEN | SERVERLESS | HYBRID
rationale: string
tradeoffs: string
migrationPath: string
}
TechnologyScore {
name: string
fit: number // 1-5
maturity: number // 1-5
teamSkills: number // 1-5
performance: number // 1-5
operations: number // 1-5
cost: number // 1-5
weighted: number // calculated
}
State {
target = $ARGUMENTS
criteria: EvaluationCriteria
candidates: ArchitectureRecommendation[]
selected: ArchitectureRecommendation
technologies: TechnologyScore[]
}
## Constraints
**Always:**
- Evaluate at least 2 candidate patterns before recommending.
- Document trade-offs for every recommendation.
- Consider team capabilities and ops maturity, not just technical fit.
- Provide a migration path from current state when applicable.
- Use ADR format for architecture decisions.
**Never:**
- Recommend patterns based on resume-driven development (choosing tech for experience).
- Skip trade-off analysis for any recommendation.
- Assume microservices are always better than monoliths.
- Ignore operational complexity when evaluating patterns.
- Recommend scaling before measuring actual bottlenecks.
## Reference Materials
- reference/architecture-patterns.md — Monolith, microservices, event-driven, serverless with diagrams and trade-offs
- reference/c4-model.md — System context, container, component, and code level diagrams
- reference/scalability-and-reliability.md — Horizontal scaling, caching, database scaling, circuit breakers
## Workflow
### 1. Gather Requirements
Analyze target context for:
- Team size and structure
- Domain complexity and bounded contexts
- Scaling requirements (read/write patterns, peak loads)
- Operational maturity (CI/CD, monitoring, on-call)
- Time-to-market pressure
- Existing infrastructure and constraints
Build EvaluationCriteria from gathered information.
### 2. Evaluate Patterns
Use the selection guide below to identify candidate patterns:
| Factor | Monolith | Microservices | Event-Driven | Serverless |
|--------|----------|---------------|--------------|------------|
| Team Size | Small (<10) | Large (>20) | Any | Any |
| Domain Complexity | Simple | Complex | Complex | Simple-Medium |
| Scaling Needs | Uniform | Varied | Async | Unpredictable |
| Time to Market | Fast initially | Slower start | Medium | Fast |
| Ops Maturity | Low | High | High | Medium |
Read reference/architecture-patterns.md for detailed pattern analysis.
Score each candidate pattern against criteria. Identify anti-patterns to avoid:
- Big Ball of Mud — no clear architecture => establish bounded contexts
- Distributed Monolith — microservices without independence => true service boundaries
- Premature Optimization — scaling before needed => start simple, measure, scale
- Golden Hammer — same solution for every problem => evaluate each case
- Ivory Tower — architecture divorced from reality => evolutionary architecture
### 3. Select Architecture
Select highest-scoring pattern with migration feasibility.
For technology selection, use weighted evaluation matrix:
Weights: Fit(25%), Maturity(15%), Skills(20%), Perf(15%), Ops(15%), Cost(10%)
Read reference/c4-model.md when creating architecture documentation.
Read reference/scalability-and-reliability.md when detailing scaling strategy.
### 4. Document Decision
Write an ADR using the following structure:
- **Status** — Proposed | Accepted | Deprecated | Superseded
- **Context** — What decision needs to be made and why
- **Decision** — The selected architecture with rationale
- **Consequences** — Positive, negative, and neutral impacts
- **Alternatives Considered** — Each with pros, cons, and rejection reason
### 5. Recommend Next Steps
match (decision) {
new system => Create C4 diagrams, define bounded contexts, plan infrastructure
migration => Define incremental migration plan with rollback strategy
review => List specific improvements with trade-off analysis
}
© Rudolf S. · MIT · rsmdt/the-startup