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.

0.98x

Quality

52%

Does it follow best practices?

Impact

97%

0.98x

Average score across 3 eval scenarios

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/architecture-patterns/SKILL.md

The canonical home for this skill is architecture-patterns in wshobson/agents

Quality

Content

37%Scale 1-3

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The skill provides thorough, 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 in practice. 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 decision workflow: 'When to use Clean Architecture vs Hexagonal vs DDD' with concrete criteria, and a step-by-step process for implementing the chosen pattern in an existing or new codebase.

Move the lengthy code examples into referenced bundle files (e.g., references/clean-architecture-guide.md) and keep SKILL.md as a concise overview with one minimal example per pattern.

Add validation checkpoints for architecture implementation (e.g., 'verify dependency direction with import analysis', 'confirm domain layer has zero framework imports').

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 largely redundant with Claude's existing knowledge. The bullet-point definitions of DDD patterns (Entities, Value Objects, Aggregates, etc.) add no value.	1 / 3
Actionability	The code examples are concrete, executable Python with real libraries (asyncpg, FastAPI, Stripe). Complete implementations are provided for entities, repositories, use cases, controllers, and adapters with proper async patterns and realistic database queries.	3 / 3
Workflow Clarity	There is no clear workflow or sequenced process for actually implementing these patterns. The skill presents code examples but lacks steps like 'start here, then do this, validate that.' For an architecture skill involving refactoring or greenfield design, there are no validation checkpoints, no decision trees for choosing patterns, and no sequenced implementation guide.	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 dead references. The main content is a monolithic wall of code examples that could benefit from being split into separate reference files, with the SKILL.md serving as a concise overview.	2 / 3
	Total	7 / 12 Passed

Description

67%Scale 1-3

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. 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, organize dependency injection layers, separate domain from infrastructure concerns'.

Expand trigger terms to include common variations like 'DDD', 'ports and adapters', 'onion architecture', 'layered architecture', 'separation of concerns', 'project structure', '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, organize 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

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: alpacapurpura/ap_sales_agent
Path: .agents/skills/architecture-patterns/SKILL.md
Commit: d31f7bc

Reviewed: ~19 hours 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.