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 somewhat generic in its framing of backend systems, which could cause overlap with other backend-related skills.
Suggestions
Add more concrete actions such as 'define bounded contexts, create port/adapter interfaces, separate domain logic from infrastructure, structure dependency inversion layers'.
Expand trigger terms to include common variations like 'DDD', 'ports and adapters', 'onion architecture', 'layered architecture', 'separation of concerns', 'bounded contexts'.
| 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, separate domain from infrastructure layers'. | 2 / 3 |
Completeness | Clearly answers both 'what' (implement Clean Architecture, Hexagonal Architecture, DDD patterns) and '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 'dependency inversion'. | 2 / 3 |
Distinctiveness Conflict Risk | The focus on specific architecture patterns provides some distinctiveness, but terms like '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 reads more like a textbook reference on architecture patterns than an actionable skill for Claude. While the code examples are high quality and executable, the content is bloated with conceptual explanations Claude already knows, and critically lacks any workflow for actually applying these patterns when architecting or refactoring a system. The skill would benefit enormously from being restructured as a concise decision guide with the detailed code moved to referenced files.
Suggestions
Remove the 'Core Concepts' section entirely—Claude already knows Clean Architecture, Hexagonal Architecture, and DDD fundamentals. Replace with a brief decision matrix for when to use which pattern.
Add a clear workflow: e.g., 1) Identify domain boundaries, 2) Define entities and value objects, 3) Create port interfaces, 4) Implement adapters, 5) Validate dependency direction (with a concrete check like 'grep for framework imports in domain/').
Move the large code examples into the referenced files (references/clean-architecture-guide.md, etc.) and keep only a minimal example in the main skill body showing the key pattern in ~30 lines.
Remove the 'When to Use This Skill' bullet list—this is metadata that belongs in the frontmatter description, not the skill body.
| 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 entities are). The 'When to Use This Skill' and 'Core Concepts' sections are largely unnecessary preamble. The bullet-point definitions of well-known patterns add no value for Claude. | 1 / 3 |
Actionability | The code examples are concrete, executable Python with real implementations including dataclasses, async/await patterns, FastAPI controllers, and PostgreSQL adapters. The directory structure and full implementation chain from entity to repository to controller is copy-paste ready. | 3 / 3 |
Workflow Clarity | There is no workflow or sequenced process for actually implementing these patterns. The skill presents reference material and code examples but never guides Claude through steps like 'first identify bounded contexts, then define entities, then create interfaces, then implement adapters.' There are no validation checkpoints for architectural decisions. | 1 / 3 |
Progressive Disclosure | The Resources section references external files (references/*.md, assets/*) which is good progressive disclosure, but the main body contains massive inline code blocks that could be split into those referenced files. The core concepts section duplicates what would presumably be in the reference guides. | 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
6e3d68c
- 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.