improve-codebase-architecture
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.
64
76%
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 ./.agents/skills/improve-codebase-architecture/SKILL.mdQuality
Discovery
82%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 solid description with a clear 'Use when' clause and good trigger term coverage. Its main weakness is that the core capability ('find deepening opportunities') is somewhat abstract and could benefit from more concrete action verbs. There is moderate overlap risk with general refactoring or architecture review skills.
Suggestions
Replace the abstract phrase 'find deepening opportunities' with more concrete actions, e.g., 'Identifies module boundaries, suggests extractions, and highlights coupling hotspots in a codebase'.
Add distinguishing language to reduce conflict with generic refactoring skills, e.g., emphasize the unique aspect of using CONTEXT.md domain language and ADR decisions as inputs.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names a domain ('deepening opportunities in a codebase') and references specific inputs (CONTEXT.md, docs/adr/), but the actual actions are somewhat abstract—'find deepening opportunities' is not as concrete as listing specific operations like 'extract modules', 'identify coupling', etc. | 2 / 3 |
Completeness | Clearly answers both 'what' (find deepening opportunities informed by domain language and ADRs) and 'when' (explicit 'Use when' clause listing improve architecture, refactoring, consolidation, testability, and AI-navigability). | 3 / 3 |
Trigger Term Quality | Includes strong natural trigger terms users would say: 'improve architecture', 'refactoring opportunities', 'consolidate tightly-coupled modules', 'testable', and 'AI-navigable'. These cover a good range of how users might phrase such requests. | 3 / 3 |
Distinctiveness Conflict Risk | Terms like 'refactoring opportunities' and 'improve architecture' could overlap with general code review or refactoring skills. However, the specific references to CONTEXT.md, ADRs, and the concept of 'deepening' provide some distinctiveness. Still, 'refactoring' is a broad trigger that could conflict. | 2 / 3 |
Total | 10 / 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 strong workflow clarity and good progressive disclosure. Its main weakness is the lack of concrete examples — a sample candidate presentation or before/after code snippet would significantly improve actionability. The glossary, while valuable for enforcing consistent vocabulary, could be tightened by removing definitions Claude already knows and focusing only on the project-specific meanings.
Suggestions
Add a concrete example of a presented deepening candidate (showing the Files/Problem/Solution/Benefits format with realistic content) to improve actionability.
Trim the glossary to only project-specific meanings — remove or compress entries like 'Implementation' and 'Adapter' that Claude already understands, keeping only the nuanced definitions (depth, deletion test, locality).
| 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 glossary preamble, the 'Key principles' bridge text). | 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 examples — no sample output format for candidates, no example of what a deepening opportunity looks like when presented, and no concrete code snippets showing before/after patterns. | 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 are feedback loops (grilling conversation, ADR offers on rejection, CONTEXT.md updates inline). The 'Do NOT propose interfaces yet' gate is a good validation checkpoint. | 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 to detailed materials. Each reference is contextually placed where the reader would need it. | 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.
- Repository
- coder/agent-tty
- Commit
a05d4e5
- Reviewed
Table of Contents
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.