architecture

anthropics/knowledge-work-plugins

Create or evaluate architecture decision records (ADRs) with structured trade-off analysis.

What is architecture?

The architecture skill helps you document technology choices and system design decisions using the ADR format. Use it when selecting between technologies, designing new components, or reviewing system proposals—it structures your thinking around context, options, trade-offs, and consequences.

Create Architecture Decision Records (ADRs) with standardized format and metadata
Compare multiple technology or design options side-by-side with pros/cons
Analyze trade-offs across dimensions like complexity, cost, scalability, and team familiarity
Document consequences and action items for implementation
Search prior ADRs and design docs if knowledge base is connected
Link decisions to project tracker epics and tickets if available

How to install architecture

npx skills add https://github.com/anthropics/knowledge-work-plugins --skill architecture

Claude Code

Cursor

Windsurf

Cline

How to use architecture

1.Run `/architecture` with your decision or system to design as the argument
2.Provide context about constraints (timeline, scale, budget, team expertise)
3.Name explicit options you want compared, even if you have a preference
4.Review the generated ADR format with Context, Decision, Options, Trade-offs, and Consequences sections
5.Iterate on the analysis by asking for deeper evaluation of specific dimensions
6.Connect to knowledge base or project tracker if available to link related docs and create implementation tasks

Use cases

Good for

Choosing between message brokers (e.g., Kafka vs SQS) for an event bus
Documenting microservices architecture proposals with trade-off reasoning
Designing a new system component from requirements and constraints
Reviewing and evaluating existing system design proposals
Recording technology decisions with context for future team reference

Who it's for

Software architects
Tech leads and engineering managers
Teams making technology selection decisions
System designers working on new components
Anyone documenting design decisions for team alignment

architecture FAQ

What's the difference between this skill and system-design?

The architecture skill focuses on creating and evaluating ADRs for specific decisions with trade-off analysis. The system-design skill provides detailed frameworks for requirements gathering, scalability analysis, and comprehensive design documentation.

Do I need to know all the options upfront?

No. You can start with a question like 'Should we use Kafka or SQS?' and the skill will help you identify and compare relevant options with structured analysis.

What if I'm just reviewing someone else's design?

Use the skill with 'Evaluate' or 'Review' mode—provide the proposal and the skill will analyze it against the ADR framework, identifying gaps, trade-offs, and consequences.

Can this connect to my project tracker?

Yes, if a project tracker connector is available, the skill can link decisions to related epics and tickets, and create implementation tasks from action items.

What should I include about constraints?

State upfront any hard constraints like timeline ('ship in 2 weeks'), scale ('handle 10K rps'), budget limits, team expertise, or compliance requirements—these shape which options are actually viable.

Full instructions (SKILL.md)

Source of truth, from anthropics/knowledge-work-plugins.

name: architecture description: Create or evaluate an architecture decision record (ADR). Use when choosing between technologies (e.g., Kafka vs SQS), documenting a design decision with trade-offs and consequences, reviewing a system design proposal, or designing a new component from requirements and constraints. argument-hint: "<decision or system to design>"

/architecture

If you see unfamiliar placeholders or need to check which tools are connected, see CONNECTORS.md.

Create an Architecture Decision Record (ADR) or evaluate a system design.

Usage

/architecture $ARGUMENTS

Modes

Create an ADR: "Should we use Kafka or SQS for our event bus?" Evaluate a design: "Review this microservices proposal" System design: "Design the notification system for our app"

See the system-design skill for detailed frameworks on requirements gathering, scalability analysis, and trade-off evaluation.

Output — ADR Format

# ADR-[number]: [Title]

**Status:** Proposed | Accepted | Deprecated | Superseded
**Date:** [Date]
**Deciders:** [Who needs to sign off]

## Context
[What is the situation? What forces are at play?]

## Decision
[What is the change we're proposing?]

## Options Considered

### Option A: [Name]
| Dimension | Assessment |
|-----------|------------|
| Complexity | [Low/Med/High] |
| Cost | [Assessment] |
| Scalability | [Assessment] |
| Team familiarity | [Assessment] |

**Pros:** [List]
**Cons:** [List]

### Option B: [Name]
[Same format]

## Trade-off Analysis
[Key trade-offs between options with clear reasoning]

## Consequences
- [What becomes easier]
- [What becomes harder]
- [What we'll need to revisit]

## Action Items
1. [ ] [Implementation step]
2. [ ] [Follow-up]

If Connectors Available

If ~~knowledge base is connected:

Search for prior ADRs and design docs
Find relevant technical context

If ~~project tracker is connected:

Link to related epics and tickets
Create implementation tasks

Tips

State constraints upfront — "We need to ship in 2 weeks" or "Must handle 10K rps" shapes the answer.
Name your options — Even if you're leaning one way, I'll give a more balanced analysis with explicit alternatives.
Include non-functional requirements — Latency, cost, team expertise, and maintenance burden matter as much as features.