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.

Quality

41%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Advisory

Suggest reviewing before use

Optimize this skill with Tessl

npx tessl skill review --optimize ./plugins/architecture-patterns/skills/architecture-patterns/SKILL.md

Quality

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 competent but could be more distinctive and specific about what concrete outputs or transformations it produces.

Suggestions

Add more concrete actions such as 'define bounded contexts, create port/adapter interfaces, separate domain logic from infrastructure, 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 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	Reasonably specific to backend architecture patterns, but could overlap with general code refactoring skills, software design skills, or backend development skills. The mention of specific architecture patterns helps, but 'complex backend systems' and 'refactoring' are broad enough to cause some conflict.	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 chapter on architecture patterns than an actionable skill for Claude. It spends significant tokens explaining concepts Claude already knows (Clean Architecture layers, DDD building blocks, hexagonal architecture benefits) while lacking a clear workflow for actually applying these patterns. The code examples are moderately useful but incomplete, and the monolithic structure with no progressive disclosure makes it inefficient as a context-window resource.

Suggestions

Remove the 'Core Concepts' and 'When to Use This Skill' sections entirely - Claude already knows what Clean Architecture, Hexagonal Architecture, and DDD are. Focus only on project-specific conventions and decisions.

Add a clear workflow for applying these patterns: e.g., '1. Identify bounded contexts → 2. Define domain entities → 3. Create port interfaces → 4. Implement adapters → 5. Validate dependency direction with import analysis'

Split into SKILL.md (overview + when to pick which pattern + workflow) with references to separate files like CLEAN_ARCH_EXAMPLE.md, HEXAGONAL_EXAMPLE.md, and DDD_EXAMPLE.md for the detailed code

Fix incomplete code examples: define CreateUserResponse, add find_by_email to the interface, complete the StripePaymentAdapter implementation, and ensure all examples are self-contained and executable

Dimension	Reasoning	Score
Conciseness	Extremely verbose - explains fundamental architecture concepts (Clean Architecture layers, DDD strategic/tactical patterns, hexagonal architecture components) that Claude already knows well. The 'Core Concepts' section is entirely redundant with Claude's existing knowledge. The 'When to Use This Skill' bullet list and 'Benefits' sections add no actionable value. Much of this reads like a textbook summary rather than a skill instruction.	1 / 3
Actionability	The code examples are fairly concrete and near-executable (Python dataclasses, repository pattern, use cases), but several are incomplete - CreateUserResponse is referenced but never defined, find_by_email is called but only find_by_id is defined in the interface, adapter implementations have placeholder comments like '# Implementation'. The examples demonstrate patterns but aren't fully copy-paste ready.	2 / 3
Workflow Clarity	There is no workflow or sequenced process for actually implementing these patterns. The skill presents concepts and code snippets but never guides through a multi-step process of architecting or refactoring a system. For a skill about 'architecting complex backend systems or refactoring existing applications,' the absence of any step-by-step workflow with validation checkpoints is a significant gap.	1 / 3
Progressive Disclosure	This is a monolithic wall of text at ~250 lines with no references to external files. The three architecture patterns, DDD tactical patterns, best practices, and pitfalls are all inlined. Content would benefit greatly from splitting detailed implementations into separate reference files while keeping SKILL.md as a concise overview with navigation links.	1 / 3
	Total	5 / 12 Passed

Validation

100%

Warnings & errors only

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: 88da5ff

Reviewed: 17 days ago

Table of Contents

Discovery Implementation Validation

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.