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 synonyms and abbreviations users would naturally use. The domain is somewhat broad ('backend systems') which creates moderate conflict risk with other backend-related skills.
Suggestions
Add more specific concrete actions such as 'define bounded contexts, create port/adapter interfaces, structure dependency injection layers, organize code into domain/application/infrastructure layers'.
Expand trigger terms to include common variations users would say: 'DDD', 'ports and adapters', 'onion architecture', 'layered architecture', 'project structure', 'separation of concerns', 'dependency inversion'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names specific architecture 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, structure dependency 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 relevant terms like 'Clean Architecture', 'Hexagonal Architecture', 'Domain-Driven Design', 'backend systems', and 'refactoring', but misses common variations users might say such as 'ports and adapters', 'onion architecture', 'DDD', 'layered architecture', 'separation of concerns', or 'project structure'. | 2 / 3 |
Distinctiveness Conflict Risk | The focus on specific architecture patterns provides some distinctiveness, but 'backend systems' and 'refactoring' are broad enough to overlap with general backend development or code refactoring skills. Could conflict with a general backend development skill or a refactoring-focused skill. | 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.
This skill is essentially a textbook reference on architecture patterns rather than an actionable skill for Claude. While the code examples are high-quality and executable, the content is extremely verbose with extensive explanations of concepts Claude already knows, and it lacks any workflow guidance for actually applying these patterns to a real project. The skill would benefit greatly from being trimmed to just the code templates and directory structures, with a clear step-by-step process for implementation.
Suggestions
Remove the 'Core Concepts' section entirely—Claude already knows what Clean Architecture, Hexagonal Architecture, and DDD are. Jump straight to the directory structure and code templates.
Add a clear workflow: e.g., '1. Identify bounded contexts → 2. Define domain entities → 3. Create port interfaces → 4. Implement adapters → 5. Wire up dependency injection → 6. Verify dependency rule with import analysis'
Cut the 'When to Use This Skill' bullet list and the 'Best Practices'/'Common Pitfalls' sections—these are generic knowledge Claude already has. Replace with a brief decision matrix (e.g., 'Use Clean Architecture when X, use simple layered when Y').
Split the three pattern implementations into separate referenced files and keep SKILL.md as a concise overview with the directory structure template and a single minimal example.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~350+ lines. Extensively 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 pure padding—Claude doesn't need to be taught what DDD or hexagonal architecture are. The bullet-point definitions of entities, value objects, aggregates, etc. are textbook knowledge Claude already possesses. | 1 / 3 |
Actionability | The code examples are concrete, executable Python with real libraries (asyncpg, FastAPI, Stripe). The directory structure is specific and copy-paste ready. The implementation spans entities, repositories, use cases, controllers, and adapters with complete, runnable code. | 3 / 3 |
Workflow Clarity | There is no workflow or sequenced process for actually implementing these patterns. No steps like 'first define your domain entities, then create interfaces, then implement adapters.' No validation checkpoints for verifying architecture correctness. The content is a reference catalog of patterns, not a guided workflow for applying them. | 1 / 3 |
Progressive Disclosure | References to external files (references/clean-architecture-guide.md, assets/clean-architecture-template/, etc.) are listed but no bundle files are provided, so these are unverifiable. The main content is a monolithic wall of code examples that could benefit from being split into separate pattern files, with SKILL.md serving as a concise overview. | 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
b09ec7f
- 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.