CtrlK
BlogDocsLog inGet started
Tessl Logo

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.

60

Quality

68%

Does it follow best practices?

Impact

No eval scenarios have been run

SecuritybySnyk

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./plugins/agentic-engineering/skills/improve-codebase-architecture/SKILL.md
SKILL.md
Quality
Evals
Security

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 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'.

DimensionReasoningScore

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.

DimensionReasoningScore

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.

Validation11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository
belchman/claude-skills
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.