Content
57%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.
A well-structured, genuinely actionable tech-debt analysis procedure with concrete thresholds, templates, and a clear output format. Its weaknesses are token bloat from boilerplate and a catalog of code smells Claude already knows, zero validation checkpoints in the workflow, and a monolithic single-file layout where detailed templates should be split into referenced files.
Suggestions
Trim the 'Use this skill when / Do not use this skill when' boilerplate and compress the standard code-smell catalog (cyclomatic complexity, god classes, feature envy, etc.) into a one-line checklist, since Claude already knows these concepts — keep only the quantified thresholds.
Add validation checkpoints to the workflow, e.g., after the Debt Inventory verify metrics with an actual tool run, and confirm effort/cost assumptions with the user before proposing multi-hundred-hour investments like the 300-hour test suite initiative.
Move detailed templates (metrics dashboard YAML, stakeholder communication reports, prevention gate configs) into reference files (e.g., references/templates.md) linked from a lean SKILL.md overview, and add runnable measurement commands (e.g., complexity/duplication tool invocations) so the inventory step is executable rather than descriptive.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient checklist/template structure, but padded in places: the generic "Use this skill when / Do not use this skill when" boilerplate, a catalog of standard code smells Claude already knows ("High cyclomatic complexity (>10)", "God classes", "Feature envy (methods using other class data)"), and fabricated example arithmetic ("240 hours × $150/hour = $36,000"). Not 2 because items are compact checklist labels and output templates rather than prose explanations of basics; not 4 because several sections add tokens without new information for Claude. | 3 / 5 |
Actionability | Concrete, specific guidance throughout: quantified thresholds ("complexity >10", "methods >50 lines", "classes >500 lines"), complete YAML metric/gate templates ("pre_commit_hooks: complexity_check: 'max 10'"), explicit ROI math patterns, and a phased facade/refactoring Python example. Not 5 because there are no runnable commands for actually measuring debt (no tool invocations), the Python example contains `pass` placeholders, and cost figures like "$150/hour" are hard-coded rather than parameterized; not 3 because the guidance is structured and specific, not pseudocode-level. | 4 / 5 |
Workflow Clarity | A clear, coherent 8-step sequence (Inventory → Impact → Metrics → Plan → Implementation → Prevention → Communication → Success Metrics) with an explicit "## Output Format" listing deliverables, but validation checkpoints are entirely missing: no step verifies findings (e.g., re-running a metrics tool or confirming assumptions with the user) before proposing large efforts like "Effort: 300 hours". Not 4 because no checkpoints are present at all; not 2 because the sequence is complete and well-defined, not rough with many gaps. | 3 / 5 |
Progressive Disclosure | No bundle files exist (no references/, scripts/, or assets/), so all ~380 lines are inlined in SKILL.md. Section structure is good (numbered ### 1-8 headers, clear Output Format), but content that clearly belongs in separate reference files — the debt taxonomy, metrics dashboard templates, and stakeholder communication templates — is inlined. Not 2 because the document is well-headered and navigable, not a wall of text; not 4/5 because there are no one-level-deep references and the body far exceeds overview length (the under-50-lines exception does not apply). | 3 / 5 |
Total | 13 / 20 Passed |