Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.
60
68%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./plugins/agentic-engineering/skills/improve-codebase-architecture/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 does well in completeness by providing both a 'what' and an explicit 'Use when' clause. However, the core concept of 'deepening opportunities' is domain-specific jargon that may not resonate with typical user queries, and the trigger terms miss common natural language variations like 'technical debt' or 'code quality'. The specificity of actions could be improved by listing concrete outputs or steps the skill performs.
Suggestions
Add more natural trigger terms users would actually say, such as 'technical debt', 'code quality', 'code smells', 'decouple', or 'clean up code'.
Replace or supplement the abstract phrase 'deepening opportunities' with concrete actions the skill performs, e.g., 'Identifies modules to consolidate, suggests architectural improvements, and flags tightly-coupled code for refactoring'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names a domain ('deepening opportunities in a codebase') and references specific inputs (CONTEXT.md, docs/adr/), but the core actions are somewhat abstract—'find deepening opportunities' is not a concrete, well-defined action like 'extract text' or 'fill forms'. The 'Use when' clause adds some specificity (improve architecture, find refactoring opportunities, consolidate modules), but these are more goals than discrete actions the skill performs. | 2 / 3 |
Completeness | Clearly answers both 'what' (find deepening opportunities informed by domain language and ADRs) and 'when' (explicit 'Use when' clause covering architecture improvement, refactoring, consolidation, and testability). The trigger guidance is explicit and actionable. | 3 / 3 |
Trigger Term Quality | Includes several relevant keywords users might say: 'refactoring', 'architecture', 'tightly-coupled modules', 'testable'. However, 'deepening opportunities' and 'AI-navigable' are not natural terms users would typically use. Missing common variations like 'code quality', 'technical debt', 'code smell', 'decouple', or 'clean up code'. | 2 / 3 |
Distinctiveness Conflict Risk | The skill has some distinctive elements (references to CONTEXT.md, docs/adr/, 'deepening opportunities'), but terms like 'improve architecture' and 'refactoring opportunities' could overlap with general code review or refactoring skills. The concept of 'deepening' is somewhat niche but not universally understood, which could cause confusion rather than clarity. | 2 / 3 |
Total | 9 / 12 Passed |
Implementation
70%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-structured architectural skill with excellent workflow clarity and progressive disclosure. Its main weakness is the glossary section, which explains concepts Claude likely already understands (though the specific vocabulary constraints add value), and the lack of concrete examples showing what a deepening opportunity candidate looks like in practice. The three-phase process with explicit gates and side-effect triggers is a strong design.
Suggestions
Add a concrete example of a deepening opportunity candidate (files, problem, solution, benefits) to make the expected output format unambiguous and boost actionability.
Trim the glossary to only project-specific definitions (depth, seam, deletion test, locality, leverage) and drop standard terms like 'module,' 'interface,' and 'implementation' that Claude already knows — or reduce them to one-line reminders of the specific meaning intended here.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The glossary section is somewhat verbose — Claude already understands concepts like interfaces, implementations, and adapters. However, the specific definitions (e.g., 'depth as leverage,' 'deletion test') add genuine value as project-specific vocabulary. Some tightening is possible (e.g., the 'Key principles' preamble, the explanatory sentence about domain models). | 2 / 3 |
Actionability | The skill provides a clear process with concrete steps (explore, present candidates, grilling loop) and specific heuristics (deletion test, shallow module detection). However, it lacks executable code examples, concrete output formats for the candidate list, or a worked example showing what a deepening opportunity looks like in practice. The guidance is specific but not copy-paste ready. | 2 / 3 |
Workflow Clarity | The three-phase workflow (Explore → Present candidates → Grilling loop) is clearly sequenced with explicit checkpoints: the user must choose a candidate before proceeding, side effects are enumerated with clear triggers, and there's a feedback loop in the grilling phase. The 'Do NOT propose interfaces yet' constraint is a well-placed gate. ADR conflict handling includes a clear decision rule. | 3 / 3 |
Progressive Disclosure | Content is well-structured with clear references to supporting files (LANGUAGE.md, CONTEXT-FORMAT.md, ADR-FORMAT.md, INTERFACE-DESIGN.md) that are one level deep and clearly signaled. The SKILL.md serves as an overview with appropriate pointers. However, since no bundle files were provided, we can't verify the referenced files exist, but the structure itself is exemplary. | 3 / 3 |
Total | 10 / 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.
be88d6c
Table of Contents
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.