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.
41
41%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./plugins/architecture-patterns/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-focused skills.
Suggestions
Add more specific concrete actions, e.g., 'define bounded contexts, create port/adapter interfaces, separate domain logic from infrastructure, structure dependency inversion layers'.
Expand trigger terms to include common variations users would say: 'DDD', 'ports and adapters', 'onion architecture', 'layered architecture', 'separation of concerns', 'dependency injection'.
| 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 'maintainability', 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 refactoring skills. Could conflict with a general 'backend development' or 'code refactoring' skill. | 2 / 3 |
Total | 9 / 12 Passed |
Implementation
14%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 summary of architecture patterns than actionable guidance for Claude. It extensively explains concepts Claude already knows (Clean Architecture layers, DDD building blocks, hexagonal architecture), resulting in poor token efficiency. The code examples are the strongest element but suffer from incomplete definitions and missing imports, while the complete absence of a workflow or decision-making process means Claude gets no guidance on *how* to apply these patterns in practice.
Suggestions
Remove all conceptual explanations (Core Concepts section, Best Practices, Common Pitfalls) that Claude already knows, and focus exclusively on project-specific conventions, decision criteria, or non-obvious implementation details.
Add a concrete workflow: e.g., 'When asked to architect a new service: 1. Identify bounded contexts → 2. Define ports/interfaces → 3. Implement domain entities → 4. Add adapters → 5. Verify dependency direction with import analysis'.
Fix incomplete code examples: define CreateUserResponse, add find_by_email to IUserRepository interface, define the Port interfaces used in the hexagonal example, and implement _to_entity.
Split content into separate referenced files per pattern (e.g., CLEAN_ARCHITECTURE.md, HEXAGONAL.md, DDD.md) with SKILL.md serving as a concise overview with decision criteria for choosing between them.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extensively explains concepts Claude already knows well—Clean Architecture layers, DDD tactical patterns, hexagonal architecture benefits. The 'Core Concepts' section is essentially a textbook summary that adds no novel information. The 'When to Use This Skill' list and 'Best Practices' / 'Common Pitfalls' sections are generic knowledge Claude possesses. The entire document could be reduced to the code examples with minimal framing. | 1 / 3 |
Actionability | The code examples are fairly concrete and near-executable (Python dataclasses, repository pattern, use cases), but several have incomplete references (e.g., CreateUserResponse is used but never defined, find_by_email is called but not in the interface, OrderRepositoryPort/PaymentGatewayPort/NotificationPort are referenced but undefined, _to_entity is called but not shown). The Stripe adapter has a comment placeholder instead of implementation. These gaps prevent copy-paste readiness. | 2 / 3 |
Workflow Clarity | There is no workflow or sequenced process for actually implementing these patterns. The skill describes what the patterns are and shows code snippets, but never guides through a multi-step process of architecting or refactoring a system. There are no validation checkpoints, no decision trees for choosing between patterns, and no feedback loops for verifying the architecture is correctly implemented. | 1 / 3 |
Progressive Disclosure | The content is a monolithic wall of text with no references to external files and no layered structure. All three architecture patterns plus DDD concepts, best practices, and pitfalls are dumped into a single file with no navigation aids or separation of concerns. For a skill of this complexity, content should be split across referenced files (e.g., separate files per pattern). | 1 / 3 |
Total | 5 / 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
- secondsky/claude-skills
- Commit
5e92b71
- 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.