CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

tech-debt

Track, categorize and prioritize technical debt across the codebase — scans for debt indicators, maintains a register.

Quality

74%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/tech-debt/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

81%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.

This is a strong instruction-style skill: every mode has an explicit sequence, validation checkpoints, approval gates and failure verdicts, and the register contract is specified to the column. The main gaps are minor — the scan step itself lacks executable commands (especially for duplication detection), and one rhetorical paragraph plus the shared register spec could be trimmed or externalized.

Suggestions

Give the scan step executable commands (e.g. the grep invocations for TODO/FIXME/HACK/@deprecated and a line-count command), and state how duplicated-code detection should be performed or explicitly delegate it.

Trim the rhetorical justification in Scan Mode ("The distinction is the whole point of the scan...") to the operative rule: state the denominator whenever findings are reported.

Move the shared Debt Register Format spec to a reference file (e.g. references/register-format.md) since it is a cross-skill contract also written by /story-done, keeping a one-line pointer in SKILL.md.

DimensionReasoningScore

Conciseness

The body is dense, imperative and project-specific with no explanations of concepts Claude already knows; the one clear instance of over-explanation is the rhetorical justification in Scan Mode ("zero findings over 400 files is a clean codebase; zero findings over zero files is no information at all") that repeats a rule already stated above it. Anchor 4 (efficient, minor instances that could be trimmed) rather than 5 because that paragraph and a few editorializing asides ("these are bugs disguised as debt") could be tightened.

4 / 5

Actionability

Highly concrete throughout: exact search markers (TODO, FIXME, HACK, @deprecated), numeric thresholds (500-line files, 50-line functions), copy-paste AskUserQuestion prompts with full option text, an exact scoring formula ("impact ÷ effort", Low 1/Critical 4, rounded to one decimal), exact paths and a full register template. Not 5 because the core scan operation is never given as an actual command — "Duplicated code blocks (similar patterns in multiple files)" has no detection method, and code-root resolution is delegated to an external doc.

4 / 5

Workflow Clarity

Each subcommand is a clearly sequenced phase with explicit validation checkpoints and error-recovery loops: the zero-source-files check ("If that count is zero ... report NOT ASSESSED ... and stop"), approval gates before every write with BLOCKED verdicts on decline, missing-register recovery ("run /tech-debt scan first. Stop."), match-before-append dedup, and a subagent fallback for missing AskUserQuestion. This matches the anchor-5 example's validate/fix/only-proceed structure; writes are batch operations but validation is present, so no cap applies.

5 / 5

Progressive Disclosure

No bundle files exist, and external references (.claude/docs/automation-modes.md, .claude/docs/code-root-resolution.md, /sprint-plan, /story-done) are one level deep and clearly signaled at point of use; section structure is clear and easy to navigate. Not 5 because the ~40-line Debt Register Format spec, which is shared contract with other skills (/story-done writes the same columns), is inlined in SKILL.md rather than split into a referenced file, and the body is long enough (~220 lines) that this split would pay off.

4 / 5

Total

17

/

20

Passed

Description

58%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 states concrete capabilities in third person with a clear niche, but it omits any 'when to use' trigger guidance and is thin on natural trigger terms (notably the colloquial "tech debt" and TODO/FIXME-style phrasing users actually say). It is solid on the "what" and weak on the "when".

Suggestions

Add an explicit trigger clause, e.g. "Use when the user mentions tech debt, technical debt, TODO/FIXME cleanup, or asks to prioritize or track deferred work."

Include natural synonyms and artifacts users would say — "tech debt", "code debt", "TODO/FIXME comments", "debt register" — alongside "technical debt".

Mention the reporting function ("generates debt-trend reports") so all four subcommands are represented in the capability list.

DimensionReasoningScore

Specificity

Lists several concrete actions ("Track, categorize and prioritize", "scans for debt indicators", "maintains a register"), but coverage has minor gaps — the report-generation function and what the scan actually looks for are not mentioned. Not 3 (more than 1-2 concrete actions) and not 5 (the generic "track" and the missing report function leave gaps).

4 / 5

Completeness

The "what" is clear (track, categorize, prioritize, scan, maintain a register), but there is no "Use when..." clause or equivalent trigger guidance, which caps completeness at 3 per the rubric guidelines. Not 2 because the "what" half is concrete, not vague.

3 / 5

Trigger Term Quality

"technical debt" and "debt indicators" are the relevant keywords, but common variations users would actually say — "tech debt" (the skill's own name), "code debt", "refactoring", "TODO/FIXME cleanup" — are absent. Matches anchor 3 (some relevant keywords, missing common variations) rather than 4's "a few natural terms missing".

3 / 5

Distinctiveness Conflict Risk

"technical debt across the codebase" and "maintains a register" define a clear niche distinct from most skills. Not 5 because without any 'when' guidance it could still contend with refactoring or code-review skills for overlapping queries.

4 / 5

Total

14

/

20

Passed

Validation

87%

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

Validation — 14 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

allowed_tools_field

'allowed-tools' contains unusual tool name(s)

Warning

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

14

/

16

Passed

Repository

Donchitos/Claude-Code-Game-Studios

Path

.claude/skills/tech-debt/SKILL.md

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.