tdg-personal/hexagonal-architecture
Design, implement, and refactor Ports & Adapters systems with clear domain boundaries, dependency inversion, and testable use-case orchestration across TypeScript, Java, Kotlin, and Go services.
72
72%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Advisory
Suggest reviewing before use
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 is strong on specificity and distinctiveness, clearly naming the architectural pattern and concrete actions across specific languages. However, it lacks an explicit 'Use when...' clause, which caps completeness, and it misses common synonyms like 'hexagonal architecture' that users would naturally use when requesting this kind of help.
Suggestions
Add a 'Use when...' clause such as 'Use when the user asks about hexagonal architecture, ports and adapters, clean architecture boundaries, or structuring services with dependency inversion.'
Include common synonyms and trigger terms like 'hexagonal architecture', 'clean architecture', 'onion architecture', 'adapter pattern', and 'domain-driven design boundaries' to improve discoverability.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'Design, implement, and refactor Ports & Adapters systems' with further specifics about 'clear domain boundaries, dependency inversion, and testable use-case orchestration' across named languages. | 3 / 3 |
Completeness | Clearly answers 'what does this do' (design, implement, refactor Ports & Adapters systems), but there is no explicit 'Use when...' clause or equivalent trigger guidance explaining when Claude should select this skill. | 2 / 3 |
Trigger Term Quality | Includes some relevant terms like 'Ports & Adapters', 'dependency inversion', 'domain boundaries', and specific languages, but misses common synonyms users might say such as 'hexagonal architecture', 'clean architecture', 'port and adapter pattern', or 'onion architecture'. The terms are somewhat technical-jargon heavy. | 2 / 3 |
Distinctiveness Conflict Risk | The focus on 'Ports & Adapters' architecture pattern with specific languages (TypeScript, Java, Kotlin, Go) creates a clear niche that is unlikely to conflict with general coding skills or other architecture-focused skills. | 3 / 3 |
Total | 10 / 12 Passed |
Implementation
64%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a comprehensive and actionable skill with strong executable TypeScript examples and good multi-language coverage. Its main weaknesses are verbosity (explaining architectural concepts Claude already understands well) and being monolithic rather than using progressive disclosure to split detailed sections into referenced files. The migration and refactoring workflows would benefit from explicit validation checkpoints.
Suggestions
Trim the 'Core Concepts' section significantly—Claude already understands hexagonal architecture terminology. Focus on project-specific conventions and decisions rather than textbook definitions.
Add explicit validation/verification checkpoints to the migration playbook (e.g., 'Run characterization tests before proceeding to next step', 'Verify port contract tests pass before wiring new adapter').
Split detailed sections (multi-language mapping, testing guidance, migration playbook) into separate referenced files, keeping SKILL.md as a concise overview with links.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is generally well-structured but includes some content Claude already knows well (e.g., 'Core Concepts' section explaining what domain models, use cases, and adapters are). The 'When to Use' section and some of the anti-patterns are things Claude could infer. However, the concrete examples and multi-language mapping add genuine value. | 2 / 3 |
Actionability | The TypeScript examples are fully executable and copy-paste ready, covering port definitions, use case implementation, outbound adapter, and composition root. The module layout is concrete, the migration playbook gives specific steps, and the multi-language mapping provides actionable package/wiring conventions per ecosystem. | 3 / 3 |
Workflow Clarity | The 6-step 'How It Works' sequence and 7-step migration playbook are clearly ordered, but neither includes explicit validation checkpoints or feedback loops. For a skill involving refactoring and architectural migration (which can be destructive), the absence of verification steps (e.g., 'run tests before proceeding to next slice') caps this at 2. | 2 / 3 |
Progressive Disclosure | The content is well-organized with clear headers and logical sections, but it's a monolithic document (~250 lines) with no references to external files. The multi-language mapping, testing guidance, and migration playbook could each be separate referenced documents, keeping the SKILL.md as a concise overview. | 2 / 3 |
Total | 9 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
Reviewed
Table of Contents