architecture-patterns
Implement proven backend architecture patterns including Clean Architecture, Hexagonal Architecture, and Domain-Driven Design. Use this skill when designing clean architecture for a new microservice, when refactoring a monolith to use bounded contexts, when implementing hexagonal or onion architecture patterns, or when debugging dependency cycles between application layers.
80
75%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./plugins/backend-development/skills/architecture-patterns/SKILL.mdQuality
Discovery
100%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a strong skill description that clearly articulates specific architectural patterns and provides explicit trigger scenarios. It uses domain-appropriate terminology that developers would naturally use, and the 'Use this skill when...' clause covers multiple concrete use cases. The description is well-structured, concise, and distinctive enough to avoid conflicts with other skills.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete patterns: Clean Architecture, Hexagonal Architecture, Domain-Driven Design, and mentions specific actions like designing microservices, refactoring monoliths, implementing onion architecture, and debugging dependency cycles. | 3 / 3 |
Completeness | Clearly answers both 'what' (implement Clean Architecture, Hexagonal Architecture, DDD patterns) and 'when' with an explicit 'Use this skill when...' clause listing four specific trigger scenarios. | 3 / 3 |
Trigger Term Quality | Includes strong natural keywords users would say: 'clean architecture', 'microservice', 'monolith', 'bounded contexts', 'hexagonal', 'onion architecture', 'dependency cycles', 'application layers'. These are terms developers naturally use when seeking help with backend architecture. | 3 / 3 |
Distinctiveness Conflict Risk | Targets a clear niche of backend architecture patterns with highly specific terminology (bounded contexts, hexagonal architecture, onion architecture, dependency cycles between layers) that is unlikely to conflict with general coding or frontend skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
50%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill provides excellent, executable code examples demonstrating Clean Architecture, Hexagonal Architecture, and DDD patterns in Python, with a strong troubleshooting section. However, it is significantly over-verbose, spending many tokens explaining architectural concepts Claude already understands deeply, and lacks a clear step-by-step workflow for when to apply which pattern and in what sequence. The content would benefit greatly from cutting the conceptual explanations and restructuring around a concise decision-making workflow.
Suggestions
Remove or drastically reduce the 'Core Concepts' section — Claude already knows what Clean Architecture, Hexagonal Architecture, and DDD are. Replace with a brief decision matrix for when to use each pattern.
Add a clear step-by-step workflow with validation checkpoints, e.g., 'Step 1: Identify bounded contexts → Step 2: Define domain entities (verify: no framework imports) → Step 3: Define ports → Step 4: Implement use cases (verify: imports only from domain/) → Step 5: Implement adapters → Step 6: Run use case tests with in-memory adapters to validate layer isolation.'
Move the full code implementations (Clean Architecture core, Hexagonal example, DDD aggregates) into a referenced file like 'references/implementation-examples.md' and keep only minimal illustrative snippets inline.
Remove the 'When to Use This Skill' and 'Benefits' lists which restate information Claude can infer, freeing tokens for more actionable content like dependency validation scripts or import-checking commands.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is extremely verbose at ~400+ lines, explaining foundational concepts Claude already knows well (Clean Architecture layers, DDD strategic/tactical patterns, what value objects are, what hexagonal architecture is). The 'Core Concepts' section is essentially a textbook summary that adds no novel information for Claude. | 1 / 3 |
Actionability | The code examples are fully executable Python with complete implementations across all layers — entities, interfaces, use cases, adapters, controllers, and tests. The examples are copy-paste ready and demonstrate real patterns with real libraries (asyncpg, FastAPI, Stripe). | 3 / 3 |
Workflow Clarity | The skill presents patterns and code examples but lacks a clear step-by-step workflow for actually implementing an architecture. There's no sequenced process like 'Step 1: Define domain entities, Step 2: Define ports, Step 3: Implement use cases...' with validation checkpoints. The troubleshooting section partially compensates but doesn't constitute a workflow. | 2 / 3 |
Progressive Disclosure | There is a reference to 'references/advanced-patterns.md' and related skills at the end, which is good. However, the main file is monolithic with extensive inline code that could be split into separate reference files (e.g., full implementation examples in a separate file). The core concepts section could be eliminated entirely given Claude's existing knowledge. | 2 / 3 |
Total | 8 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- wshobson/agents
- Commit
27a7ed9
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.