Tech Debt Tracker
Scan a codebase for tech-debt items—complexity, duplication, large functions, security smells—and prioritize fixes with severities and a health score.
Overview
Tech Debt Tracker is an agent skill most often used in Ship (also Build backend, Operate iterate) that scans code and emits prioritized tech-debt items with severities and a health score.
Install
npx skills add https://github.com/alirezarezvani/claude-skills --skill tech-debt-trackerWhat is this skill?
- Structured scan output: metadata, summary (files/lines/debt count, health_score, debt_density), and enumerated debt_item
- Debt types include large_function, duplicate_code, security_risk, and high_complexity with severity tiers (e.g. critical
- Each item gets an ID (DEBT-####), file_path, description, detected_date, and status such as identified
- Example summary shows 25 files, 12,543 lines, 28 debt items, health_score 68.5, debt_density 1.12
- Oriented toward prioritizing remediation before velocity collapses on solo-maintained codebases
- Example scan: 25 files, 12,543 lines, 28 debt items, health_score 68.5, debt_density 1.12
- Debt items use typed categories including large_function, duplicate_code, security_risk, high_complexity
Adoption & trust: 531 installs on skills.sh; 17.5k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your solo project accumulated large functions, duplicated logic, and security smells but you have no ordered inventory of what to fix first.
Who is it for?
Indie developers preparing a release or monthly cleanup who want agent-friendly JSON debt registers from a source tree scan.
Skip if: Greenfield prototypes with almost no code, or teams that already run full SAST/compliance suites and do not need skill-guided debt triage.
When should I use this skill?
When you need a structured tech-debt inventory and health metrics from a project source directory.
What do I get? / Deliverables
You receive a structured debt report with typed items, severities, file paths, and summary metrics so you can plan targeted refactors or security fixes.
- JSON scan report with debt_items and severities
- Summary health_score and debt_density metrics
- Identified remediation candidates with file paths
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Debt scanning fits Ship review as a pre-release quality read, but the same inventory supports ongoing Operate iteration. Review subphase hosts systematic codebase assessment beyond single-file lint fixes.
Where it fits
Run a pre-release scan to block shipping if critical security_risk debt items remain open.
Regenerate the debt register monthly to watch health_score and debt_density trend on a solo-maintained API.
After a big feature merge, list large_function and duplicate_code hits before starting the next epic.
How it compares
Skill-guided debt inventory with severities—not a substitute for dedicated SAST products or automated CI quality gates unless wired into your pipeline.
Common Questions / FAQ
Who is tech-debt-tracker for?
Solo and small-team builders who own a growing codebase and need a repeatable scan that labels debt types and severities for agent-assisted cleanup.
When should I use tech-debt-tracker?
Before Ship release review to catch critical security_risk items; during Build when complexity spikes; in Operate iterate when health_score drifts down between features.
Is tech-debt-tracker safe to install?
Review the Security Audits panel on this Prism page; scanning implies filesystem read access to your project paths—treat reports as sensitive if they surface secrets locations.
SKILL.md
READMESKILL.md - Tech Debt Tracker
{ "scan_metadata": { "directory": "/project/src", "scan_date": "2024-01-15T09:00:00", "scanner_version": "1.0.0" }, "summary": { "total_files_scanned": 25, "total_lines_scanned": 12543, "total_debt_items": 28, "health_score": 68.5, "debt_density": 1.12 }, "debt_items": [ { "id": "DEBT-0001", "type": "large_function", "description": "create_user function in user_service.py is 89 lines long", "file_path": "src/user_service.py", "severity": "high", "detected_date": "2024-01-15T09:00:00", "status": "identified" }, { "id": "DEBT-0002", "type": "duplicate_code", "description": "Password validation logic duplicated in 3 locations", "file_path": "src/user_service.py", "severity": "medium", "detected_date": "2024-01-15T09:00:00", "status": "identified" }, { "id": "DEBT-0003", "type": "security_risk", "description": "Hardcoded API key in payment_processor.py", "file_path": "src/payment_processor.py", "severity": "critical", "detected_date": "2024-01-15T09:00:00", "status": "identified" }, { "id": "DEBT-0004", "type": "high_complexity", "description": "process_payment function has cyclomatic complexity of 24", "file_path": "src/payment_processor.py", "severity": "high", "detected_date": "2024-01-15T09:00:00", "status": "identified" }, { "id": "DEBT-0005", "type": "missing_docstring", "description": "PaymentProcessor class missing docstring", "file_path": "src/payment_processor.py", "severity": "low", "detected_date": "2024-01-15T09:00:00", "status": "identified" }, { "id": "DEBT-0006", "type": "todo_comment", "description": "TODO: Move this to configuration file", "file_path": "src/user_service.py", "severity": "low", "detected_date": "2024-01-15T09:00:00", "status": "identified" }, { "id": "DEBT-0007", "type": "empty_catch_blocks", "description": "Empty catch block in update_user method", "file_path": "src/user_service.py", "severity": "medium", "detected_date": "2024-01-15T09:00:00", "status": "identified" }, { "id": "DEBT-0008", "type": "magic_numbers", "description": "Magic number 1800 used for lock timeout", "file_path": "src/user_service.py", "severity": "low", "detected_date": "2024-01-15T09:00:00", "status": "identified" }, { "id": "DEBT-0009", "type": "deep_nesting", "description": "Deep nesting detected: 6 levels in preferences handling", "file_path": "src/frontend.js", "severity": "medium", "detected_date": "2024-01-15T09:00:00", "status": "identified" }, { "id": "DEBT-0010", "type": "long_line", "description": "Line too long: 156 characters", "file_path": "src/frontend.js", "severity": "low", "detected_date": "2024-01-15T09:00:00", "status": "identified" }, { "id": "DEBT-0011", "type": "commented_code", "description": "Dead code left in comments", "file_path": "src/frontend.js", "severity": "low", "detected_date": "2024-01-15T09:00:00", "status": "identified" }, { "id": "DEBT-0012", "type": "global_variables", "description": "Global variable userCache should be encapsulated", "file_path": "src/frontend.js", "severity": "medium", "detected_date": "2024-01-15T09:00:00", "status": "identified" }, { "id": "DEBT-0013", "type": "synchronous_ajax", "description": "Synchronous AJAX call blocks UI thread", "file_path": "src/frontend.js", "severity": "high", "detected_date": "2024-01-15T09:00:00", "status": "identified" }, { "id": "DEBT-0014",