Content
81%Weight 40%Scale 1-5Reviews 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.
| Dimension | Reasoning | Score |
|---|---|---|
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 |