architecture-patterns
Implement proven backend architecture patterns including Clean Architecture, Hexagonal Architecture, and Domain-Driven Design. Use when architecting complex backend systems or refactoring existing applications for better maintainability.
68
52%
Does it follow best practices?
Impact
97%
0.98xAverage score across 3 eval scenarios
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./tests/ext_conformance/artifacts/agents-wshobson/backend-development/skills/architecture-patterns/SKILL.mdQuality
Discovery
67%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description has a solid structure with an explicit 'Use when' clause and names specific architecture patterns, which is good. However, it lacks concrete action verbs beyond 'implement' and 'refactoring', and the trigger terms could be expanded to include common abbreviations and related concepts. The description is reasonably distinctive but could overlap with general backend or refactoring skills.
Suggestions
Add more concrete actions such as 'define bounded contexts, create port/adapter interfaces, separate domain from infrastructure layers, establish dependency inversion boundaries'.
Expand trigger terms to include common variations like 'DDD', 'ports and adapters', 'onion architecture', 'layered architecture', 'separation of concerns', 'dependency inversion'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (backend architecture) and some specific patterns (Clean Architecture, Hexagonal Architecture, DDD), but doesn't list concrete actions beyond 'implement' and 'refactoring'. Lacks specifics like 'define bounded contexts, create port/adapter interfaces, separate domain from infrastructure layers'. | 2 / 3 |
Completeness | Clearly answers both 'what' (implement Clean Architecture, Hexagonal Architecture, DDD patterns) and 'when' (when architecting complex backend systems or refactoring existing applications for better maintainability) with an explicit 'Use when' clause. | 3 / 3 |
Trigger Term Quality | Includes some relevant keywords like 'Clean Architecture', 'Hexagonal Architecture', 'Domain-Driven Design', 'backend systems', and 'refactoring'. However, it misses common user variations like 'ports and adapters', 'onion architecture', 'DDD', 'layered architecture', 'separation of concerns', or 'dependency inversion'. | 2 / 3 |
Distinctiveness Conflict Risk | The focus on specific architecture patterns (Clean, Hexagonal, DDD) provides some distinctiveness, but 'backend systems' and 'refactoring' are broad enough to potentially overlap with general backend development skills or code refactoring skills. | 2 / 3 |
Total | 9 / 12 Passed |
Implementation
37%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill provides high-quality, executable code examples for three major architecture patterns, which is its primary strength. However, it is excessively verbose, spending significant tokens explaining concepts Claude already knows (DDD definitions, Clean Architecture layer descriptions) and lacks any workflow guidance for actually applying these patterns during system design or refactoring. The content reads more like a reference document than an actionable skill.
Suggestions
Remove the 'Core Concepts' section entirely—Claude already knows what Clean Architecture, Hexagonal Architecture, and DDD are. Jump straight to the implementation patterns.
Add a sequenced workflow for applying these patterns, e.g., '1. Identify bounded contexts → 2. Define domain entities → 3. Create port interfaces → 4. Implement adapters → 5. Verify dependency direction with import analysis'.
Move the three detailed implementation examples into separate referenced files (e.g., references/clean-architecture-guide.md) and keep SKILL.md as a concise overview with decision guidance on which pattern to use when.
Remove the 'When to Use This Skill' bullet list—this is metadata that belongs in frontmatter or is self-evident from the skill description.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~400+ lines. Explains concepts Claude already knows well (Clean Architecture layers, DDD tactical patterns, what value objects are, what entities are). The 'When to Use This Skill' and 'Core Concepts' sections are entirely redundant given Claude's training knowledge. The bullet-point definitions of DDD patterns (Entities, Value Objects, Aggregates, etc.) add no novel information. | 1 / 3 |
Actionability | The code examples are fully executable Python with concrete implementations across all three architecture patterns. The directory structure, entity definitions, repository implementations, use case orchestration, and controller wiring are all copy-paste ready with real libraries (asyncpg, FastAPI, Stripe). | 3 / 3 |
Workflow Clarity | There is no sequenced workflow for actually implementing or refactoring toward these architectures. The skill presents patterns as reference material but never guides through a multi-step process (e.g., 'start here, then do this, validate that'). For a skill about architecting or refactoring systems, the absence of any step-by-step process with validation checkpoints is a significant gap. | 1 / 3 |
Progressive Disclosure | References to external files exist in the Resources section (references/clean-architecture-guide.md, assets/clean-architecture-template/, etc.), which is good. However, the main file is a monolithic wall of code that could benefit from splitting the three architecture patterns into separate referenced files, keeping SKILL.md as a concise overview with navigation. | 2 / 3 |
Total | 7 / 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
- Dicklesworthstone/pi_agent_rust
- Commit
47823e3
- 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.