This Claude Code skill provides a comprehensive, file-cited technical debt audit for entire codebases, targeting engineers and architects seeking actionable insights beyond generic checklists. It delivers a persistent, trackable artifact (TECH_DEBT_AUDIT.md) to identify and prioritize code quality issues, improving maintainability and reducing long-term development costs.

How It Works

The skill employs a three-phase protocol designed to avoid shallow LLM analysis. It begins with an "Orient" phase, mandating the model to first understand the codebase's architecture, directory structure, and git churn before forming opinions. The "Audit" phase systematically analyzes code across nine dimensions (architectural decay, consistency, type, test, dependency, performance, observability, security, documentation) using static analysis tools (rg, ast-grep, language-native linters/auditors) and git log. Crucially, every finding is strictly file-and-line cited. A unique "looks bad but is fine" section forces the model to justify why certain code patterns, which might appear problematic, are intentionally kept, differentiating it from superficial reviews. For large repositories, subagent dispatch parallelizes analysis to manage context window limitations.

Quick Start & Requirements

Installation involves placing the SKILL.md file into the Claude Code skills directory:

• Personal Install: mkdir -p ~/.claude/skills/tech-debt-audit && curl -o ~/.claude/skills/tech-debt-audit/SKILL.md https://raw.githubusercontent.com/ksimback/tech-debt-skill/main/SKILL.md
• Project-Only Install: mkdir -p .claude/skills/tech-debt-audit && curl -o .claude/tech-debt-audit/SKILL.md https://raw.githubusercontent.com/ksimback/tech-debt-skill/main/SKILL.md

Usage within Claude Code, in the target repository: /tech-debt-audit. First runs take 5-20 minutes depending on repo size; subsequent runs are faster. No non-default prerequisites are listed beyond the Claude Code environment. The full protocol details are available at SKILL.md.

Highlighted Details

• Whole-Repo Scope: Audits the entire codebase across nine defined dimensions of technical debt.
• Actionable Artifact: Generates TECH_DEBT_AUDIT.md with file:line citations, severity, effort estimates, ranked priorities, quick wins, and a "looks bad but is fine" section.
• Multi-Tool Grounding: Integrates findings from various language-specific tools (e.g., npm audit, ruff, golangci-lint).
• Repeat-Run Mode: Tracks changes over time, marking findings as RESOLVED, NEW, or updating stale ones, creating a living document.
• Customizable: Designed to be forked; users can add domain-specific dimensions or tune severity thresholds.

Maintenance & Community

The README encourages contributions via PRs, emphasizing the core constraint of producing actionable findings. Specific details regarding active maintainers, community channels (like Discord/Slack), sponsorships, or a public roadmap are not provided in the README.

Licensing & Compatibility

The project is licensed under the MIT license, permitting use, forking, and distribution, including for commercial purposes, with attribution appreciated but not required.

Limitations & Caveats

This is a static code audit, not a substitute for security penetration testing or threat modeling; it identifies hygiene issues but not complex vulnerabilities. It cannot detect business logic errors requiring domain expertise. For extremely large repositories (>200k LOC), analysis may become shallow even with subagent dispatch, potentially requiring scoped runs. The skill may struggle to perfectly distinguish intentional simplicity from accidental simplicity, relying on the "open questions" section for clarification.