How do I install the Techdebt Scan skill?

Run npx skillmds@latest add dmitryprg-ai/techdebt-scan-2 in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Techdebt Scan safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: executes scripts. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Techdebt Scan?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Techdebt Scan free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Techdebt Scan?

dmitryprg-ai (@dmitryprg-ai) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Techdebt Scan by dmitryprg-ai — Agent Skill

Name: Techdebt Scan
Rating: 4.666666666666667 (3 reviews)
Author: dmitryprg-ai

Techdebt Scan

Scan codebase for technical debt and fix safely with TDD. Use to find oversized files, duplicated code, code smells, and refactor safely. Workflow - SCAN, TEST CASES, REFACTOR, VERIFY. Keywords - techdebt, tech debt, duplicates, code quality audit.

dmitryprg-ai Updated Sep 22, 2026

File contents

Technical Debt Scanner

Find and safely fix technical debt using TDD approach.

Order: SCAN -> TEST CASES -> REFACTOR -> VERIFY (do NOT skip steps!)

Phase 1: SCAN

Run scan scripts:

bash .cursor/skills/techdebt-scan/scripts/scan-large-files.sh
bash .cursor/skills/techdebt-scan/scripts/find-todos.sh

Then check for:

Files > 300 lines (routes, services, components > 200 lines)
Duplicated code patterns (grep for identical blocks > 5 lines)
Functions > 50 lines
Deep nesting (> 3 levels)
Files with > 10 exports
Magic numbers/strings

Scan Results Template

## TECHDEBT SCAN RESULTS — [date]

### Oversized Files
| File | Lines | Limit | Severity |
|------|-------|-------|----------|
| <path> | X | Y | HIGH/MED |

### Duplicate Code
| Pattern | File 1 | File 2 | Lines | Severity |
|---------|--------|--------|-------|----------|
| <desc> | <path> | <path> | X | HIGH/MED |

### Code Smells
| Type | Location | Description | Severity |
|------|----------|-------------|----------|
| Long function | <path>:<line> | X lines | MED |

### Exceptions (NOT violations)
| File | Exception Type | Reason |
|------|---------------|--------|
| <path> | High Cohesion Monolith | <reason> |

High Cohesion Monolith criteria:

Single business responsibility (not a god-object)
High method cohesion -- methods share common state
Splitting requires full test coverage for safety

Phase 2: PRIORITIZE

Severity	Impact	Effort	Priority
HIGH	Blocks development	Low	P0 -- Fix now
HIGH	Blocks development	High	P1 -- Plan
MED	Reduces quality	Low	P2 -- Quick win
MED	Reduces quality	High	P3 -- Backlog
LOW	Cosmetic	Any	P4 -- Optional

Phase 3: TEST CASES (MANDATORY before refactoring)

Write tests BEFORE any code changes. For each selected issue:

Create test cases table
Write failing tests
Verify tests FAIL (code not changed yet)

Phase 4: REFACTOR

Small steps -- one file at a time
Run tests after EACH change
Commit after each green test

Phase 5: VERIFY

## TECHDEBT FIX VERIFICATION
| ID | Description | Tests Written | Tests Passing | Status |
|----|-------------|---------------|---------------|--------|
| D1 | <desc> | X | X | OK |

- [ ] `npm run build` -- success
- [ ] `npm run lint` -- 0 errors
- [ ] `npm test` -- all passing

FORBIDDEN

Refactoring without SCAN first
Refactoring without TEST CASES
Writing tests AFTER refactoring
"Build passed = everything works"

---name: techdebt-scan-2description: Scan codebase for technical debt and fix safely with TDD. Use to find oversized files, duplicated code, code smells, and refactor safely. Workflow - SCAN, TEST CASES, REFACTOR, VERIFY. Keywords - techdebt, tech debt, duplicates, code quality audit.---# Technical Debt ScannerFind and safely fix technical debt using TDD approach.**Order: SCAN -> TEST CASES -> REFACTOR -> VERIFY** (do NOT skip steps!)## Phase 1: SCANRun scan scripts:```bashbash .cursor/skills/techdebt-scan/scripts/scan-large-files.shbash .cursor/skills/techdebt-scan/scripts/find-todos.sh```Then check for:- Files > 300 lines (routes, services, components > 200 lines)- Duplicated code patterns (grep for identical blocks > 5 lines)- Functions > 50 lines- Deep nesting (> 3 levels)- Files with > 10 exports- Magic numbers/strings### Scan Results Template```markdown## TECHDEBT SCAN RESULTS — [date]### Oversized Files| File | Lines | Limit | Severity ||------|-------|-------|----------|| <path> | X | Y | HIGH/MED |### Duplicate Code| Pattern | File 1 | File 2 | Lines | Severity ||---------|--------|--------|-------|----------|| <desc> | <path> | <path> | X | HIGH/MED |### Code Smells| Type | Location | Description | Severity ||------|----------|-------------|----------|| Long function | <path>:<line> | X lines | MED |### Exceptions (NOT violations)| File | Exception Type | Reason ||------|---------------|--------|| <path> | High Cohesion Monolith | <reason> |```**High Cohesion Monolith criteria:**- Single business responsibility (not a god-object)- High method cohesion -- methods share common state- Splitting requires full test coverage for safety## Phase 2: PRIORITIZE| Severity | Impact | Effort | Priority ||----------|--------|--------|----------|| HIGH | Blocks development | Low | P0 -- Fix now || HIGH | Blocks development | High | P1 -- Plan || MED | Reduces quality | Low | P2 -- Quick win || MED | Reduces quality | High | P3 -- Backlog || LOW | Cosmetic | Any | P4 -- Optional |## Phase 3: TEST CASES (MANDATORY before refactoring)Write tests BEFORE any code changes. For each selected issue:1. Create test cases table2. Write failing tests3. Verify tests FAIL (code not changed yet)## Phase 4: REFACTOR1. Small steps -- one file at a time2. Run tests after EACH change3. Commit after each green test## Phase 5: VERIFY```markdown## TECHDEBT FIX VERIFICATION| ID | Description | Tests Written | Tests Passing | Status ||----|-------------|---------------|---------------|--------|| D1 | <desc> | X | X | OK |- [ ] `npm run build` -- success- [ ] `npm run lint` -- 0 errors- [ ] `npm test` -- all passing```## FORBIDDEN- Refactoring without SCAN first- Refactoring without TEST CASES- Writing tests AFTER refactoring- "Build passed = everything works"

Frequently asked questions