Use before implementing or refactoring software when the task requires designing module boundaries, APIs, layers, abstractions, services, repositories, adapters, or architecture. Helps coding agents reduce total system complexity by creating deep modules, hiding implementation knowledge, avoiding leakage and pass-through APIs, comparing alternative designs, documenting interfaces before coding, and critiquing existing architecture.
90
90%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Quality
Discovery
92%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a strong description that clearly articulates both what the skill does and when to use it, with rich trigger terms covering software architecture concepts. The specificity of actions like 'creating deep modules', 'hiding implementation knowledge', and 'avoiding leakage and pass-through APIs' is excellent. The main weakness is moderate overlap risk with general coding or refactoring skills, though the pre-implementation design focus helps differentiate it.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: designing module boundaries, APIs, layers, abstractions, services, repositories, adapters; creating deep modules, hiding implementation knowledge, avoiding leakage and pass-through APIs, comparing alternative designs, documenting interfaces, critiquing existing architecture. | 3 / 3 |
Completeness | Clearly answers both 'what' (designing module boundaries, creating deep modules, hiding implementation knowledge, comparing alternative designs, documenting interfaces, critiquing architecture) and 'when' ('before implementing or refactoring software when the task requires designing module boundaries, APIs, layers, abstractions, services, repositories, adapters, or architecture'). | 3 / 3 |
Trigger Term Quality | Includes strong natural keywords users would say: 'module boundaries', 'APIs', 'layers', 'abstractions', 'services', 'repositories', 'adapters', 'architecture', 'refactoring', 'designing'. These cover a wide range of terms a developer would naturally use when needing architecture guidance. | 3 / 3 |
Distinctiveness Conflict Risk | While it targets software architecture specifically, terms like 'refactoring', 'APIs', 'services', and 'coding' could overlap with general coding or refactoring skills. The focus on design-before-coding and architecture critique helps distinguish it, but there's moderate overlap risk with broader development skills. | 2 / 3 |
Total | 11 / 12 Passed |
Implementation
85%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a strong, well-structured skill that provides clear architectural design guidance with concrete workflows, templates, and decision criteria. Its progressive disclosure is excellent, keeping the overview lean while referencing detailed materials. The main weakness is moderate redundancy between the design brief template, decision rules summary, and mandatory design gates, which could be tightened to save tokens.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is mostly efficient and avoids explaining basic concepts Claude already knows, but some sections are somewhat verbose—particularly the Decision Rules Summary which restates principles that overlap with the workflow and design gates sections. The design brief template and mandatory gates have significant overlap. | 2 / 3 |
Actionability | The skill provides highly concrete, actionable guidance: a specific design brief template, a numbered workflow with clear steps, explicit decision rules, mandatory design gates with specific questions, and clear instructions for when to stop and revise. While it lacks executable code (appropriate since this is an architecture/design skill, not a coding skill), the guidance is specific and directly usable. | 3 / 3 |
Workflow Clarity | The 8-step workflow is clearly sequenced with logical progression from goal-setting through implementation to reporting. It includes explicit validation checkpoints (step 5 audit, mandatory design gates, and the instruction to stop and revise during coding if pass-through APIs or leakage are detected). The feedback loop of 'if answers are weak, revise the design before coding' is explicit. | 3 / 3 |
Progressive Disclosure | The skill provides a clear overview with well-signaled one-level-deep references to detailed materials: `references/decision-rules.md`, `references/review-checklist.md`, `examples/module-design-examples.md`, `templates/design-brief.md`, and `templates/architecture-critique.md`. The main file stays at the right level of abstraction while pointing to specifics. | 3 / 3 |
Total | 11 / 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.
Reviewed
Table of Contents