codebase-cleanup-tech-debt

Identify technical debt from actual code and change history, estimate its impact, and prioritize bounded improvements with explicit assumptions.

Quality

60%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/codebase-cleanup-tech-debt/SKILL.md

Quality

Content

56%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The skill body delivers a well-sequenced, actionable technical-debt workflow with concrete thresholds and honest labeling of hypothetical figures. Its main weaknesses are verbosity (long taxonomies and templates Claude largely knows) and a monolithic structure with no progressive disclosure into reference files.

Suggestions

Cut the debt-type taxonomy to a compact checklist (type + quantify metric only) and drop the concepts Claude already knows, such as definitions of cyclomatic complexity or feature envy.

Move the metrics dashboard YAML, communication-plan markdown, and team-allocation templates into a references/ file (e.g., references/templates.md) and link to them from SKILL.md.

Replace illustrative stub code (the pass-body PaymentService) with either complete runnable snippets or an explicit note that the pattern is a template to adapt, and add per-phase validation checkpoints (e.g., verify metrics against the repo before impact scoring).

Dimension	Reasoning	Score
Conciseness	The ~395-line body extensively catalogs concepts Claude already knows ("High cyclomatic complexity (>10)", "Feature envy", "God classes", "Brittle tests") and inlines long hypothetical dashboards, team-allocation YAML, and stakeholder-report templates, matching the 2 anchor (noticeably verbose, several padded sections). Not 3 because the padding spans many sections rather than being occasional.	2 / 5
Actionability	Concrete thresholds (">500 lines, >20 methods", "max 5% duplication"), quantification prompts per debt type, and an executable facade/feature-flag migration pattern in Python give mostly executable guidance. Not 5 because some examples remain illustrative stubs (e.g., PaymentService.process_payment is a pass body) and no runnable commands for scanning a repo are given.	4 / 5
Workflow Clarity	The eight numbered phases (Inventory through Success Metrics) plus a defined Output Format give a clear sequence, and Requirements supplies checkpoints ("Report missing cost/usage inputs as unknown", "Stop and ask for clarification if required inputs... are missing"). Not 5 because there are no explicit validate-then-proceed feedback loops between analysis phases; not 3 because sequence and key checkpoints are present.	4 / 5
Progressive Disclosure	Sections are clearly headed, but there are no bundle files at all; content that clearly belongs in separate references (metrics dashboard template, communication-plan templates, the full debt taxonomy) is inlined in a monolithic ~400-line file. This matches the 3 anchor (some structure, should-be-separate content inline); not 4 because no one-level-deep references exist to signal.	3 / 5
	Total	13 / 20 Passed

Description

63%Weight 40%Scale 1-5

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 specific and concrete about what the skill does, using third-person active verbs with well-qualified actions. Its main weakness is the complete absence of a "when to use" trigger clause and of common user-facing synonyms, which caps both completeness and trigger-term quality at 3.

Suggestions

Append an explicit trigger clause such as "Use when the user mentions technical debt, tech debt, code cleanup priorities, or asks what should be refactored first."

Add natural synonyms users would actually say (e.g., "tech debt", "refactoring backlog", "code health") to broaden trigger coverage.

Clarify the distinctness from general refactoring skills by naming the deliverable (e.g., "produce a prioritized debt inventory and ROI roadmap").

Dimension	Reasoning	Score
Specificity	"Identify technical debt from actual code and change history, estimate its impact, and prioritize bounded improvements with explicit assumptions" lists three concrete, qualified actions with comprehensive coverage of the skill's purpose. It matches the 5 anchor (multiple specific concrete actions) rather than 4, which would require minor gaps in coverage.	5 / 5
Completeness	The description has a clear "what" (identify, estimate, prioritize technical debt) but no "Use when..." clause or equivalent explicit trigger guidance, which caps completeness at 3 per the judging guidelines. Not 2 because the "what" is specific and detailed, not vague.	3 / 5
Trigger Term Quality	"technical debt" is a relevant, natural keyword, but common variations users would say ("tech debt", "refactoring", "code quality", "cleanup") are missing, matching the 3 anchor. Not 4 because there is no trigger phrasing or natural-term coverage beyond the single domain term.	3 / 5
Distinctiveness Conflict Risk	"bounded improvements with explicit assumptions" and the focus on impact estimation carve a mostly distinct niche versus generic refactoring or code-review skills, matching the 4 anchor. Not 5 because terms like "prioritize improvements" could overlap with general refactoring or code-quality skills.	4 / 5
	Total	15 / 20 Passed

Validation

93%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: sickn33/agentic-awesome-skills
Path: skills/codebase-cleanup-tech-debt/SKILL.md
Commit: 7b534bc

Reviewed: 6 days ago

Table of Contents

Discovery Implementation Validation

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.