You are a technical debt expert specializing in identifying, quantifying, and prioritizing technical debt in software projects. Analyze the codebase to uncover debt, assess its impact, and create acti
49
30%
Does it follow best practices?
Impact
73%
1.43xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/code-refactoring-tech-debt/SKILL.mdQuality
Discovery
32%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 truncated, which severely undermines its effectiveness. While it identifies the domain of technical debt and lists some relevant actions, it lacks an explicit 'Use when...' clause, misses common user trigger terms, and the cut-off text leaves the description incomplete and unprofessional.
Suggestions
Complete the truncated description and add a 'Use when...' clause with explicit triggers like 'Use when the user asks about technical debt, code quality issues, refactoring priorities, or legacy code maintenance'.
Add natural trigger terms users would say, such as 'code smell', 'refactoring', 'legacy code', 'maintainability', 'code quality audit', and 'tech debt'.
Use third-person voice ('Analyzes the codebase...') instead of second-person framing ('You are a technical debt expert') to align with skill description conventions.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (technical debt) and some actions (identifying, quantifying, prioritizing, analyzing, assessing impact), but the description appears truncated and uses somewhat vague language like 'create acti...' (cut off). It lists actions but they remain at a moderate level of specificity. | 2 / 3 |
Completeness | The description addresses 'what' (analyze codebase for technical debt) but has no explicit 'Use when...' clause or equivalent trigger guidance. Additionally, the description is truncated, further reducing completeness. Per rubric guidelines, a missing 'Use when' clause caps completeness at 2, and the truncation pushes it to 1. | 1 / 3 |
Trigger Term Quality | Includes relevant terms like 'technical debt', 'codebase', 'prioritizing', but misses common user variations such as 'code quality', 'refactoring', 'legacy code', 'code smell', or 'maintainability'. Coverage of natural trigger terms is incomplete. | 2 / 3 |
Distinctiveness Conflict Risk | The focus on 'technical debt' is somewhat distinctive, but terms like 'analyze the codebase' and 'assess its impact' are generic enough to overlap with code review, code quality, or static analysis skills. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
27%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill reads like a consulting playbook or textbook chapter on technical debt rather than a focused skill for Claude. It is extremely verbose, explaining well-known software engineering concepts (code duplication, cyclomatic complexity, test coverage) that Claude already understands. The hypothetical examples with made-up dollar figures and percentages consume significant tokens without adding actionable value for analyzing a real codebase.
Suggestions
Reduce content by 70%+ by removing explanations of concepts Claude already knows (what code duplication is, what cyclomatic complexity means, basic ROI calculations) and focus only on the specific analysis workflow and output format expected.
Split detailed templates (metrics dashboard, communication plan, prevention strategy) into separate referenced files to improve progressive disclosure and reduce the main skill's token footprint.
Add concrete tool commands for actual debt analysis (e.g., specific static analysis tool invocations, grep patterns for finding duplicates, dependency audit commands) instead of generic category lists.
Add explicit validation checkpoints in the workflow, such as 'verify debt inventory completeness with the user before proceeding to impact assessment' to create feedback loops in this multi-step process.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~300+ lines. Most content is generic templates and examples that Claude already knows (what cyclomatic complexity is, how to calculate ROI, what code duplication means). The skill explains basic software engineering concepts rather than providing project-specific guidance. The hypothetical examples (e.g., '$36,000 annual cost') add bulk without teaching Claude anything new. | 1 / 3 |
Actionability | Contains some concrete examples like the Python facade pattern and YAML quality gates, but most content is template-level guidance rather than executable instructions. The code examples are illustrative rather than copy-paste ready for actual debt analysis. There are no concrete commands for running analysis tools (e.g., specific sonarqube commands, actual linting configurations). | 2 / 3 |
Workflow Clarity | The 8-step numbered process provides a clear sequence, but there are no validation checkpoints or feedback loops. For a process that involves refactoring and potentially destructive changes to codebases, there's no explicit 'verify before proceeding' step. The workflow reads more like a consulting framework than an actionable technical workflow with error recovery. | 2 / 3 |
Progressive Disclosure | Monolithic wall of text with everything inline. All 8 major sections with extensive sub-sections, code blocks, and YAML examples are crammed into a single file. There are no references to external files for detailed content like the refactoring guide, metrics dashboard templates, or communication plan templates, which would be ideal candidates for separate documents. | 1 / 3 |
Total | 6 / 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 | |
6a07b83
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.