tech-debt-audit: a Claude Code skill that refuses to guess

One slash command and a markdown file in the repo

The interface is deliberately tiny. In Claude Code, in the repository you want audited, you run the slash command.

/tech-debt-audit

The output goes to TECH_DEBT_AUDIT.md in the repo root, with file-cited findings, severity, effort estimates and a ranked list of what to actually fix. You can also scope the audit to a subtree, which the README suggests for very large monorepos.

/tech-debt-audit src/payments

There is a second interface, and it is the one the README recommends for a first run on any new codebase. You interrupt after Phase 1 and ask the agent a question, telling it what surprised you in the orientation phase and what you want it to investigate that is not in the dimensions list. The README's reasoning is worth taking seriously, because it says the best findings often come from things the prompt did not anticipate. A first run is therefore a conversation, not a report you receive.

The failure mode it is built to avoid

The why section names the problem with a precision that explains the rest of the design. LLM-generated code reviews fail in a predictable way: they pattern-match against generic heuristics, surface obvious findings without grounding them in the actual code, and produce output that feels thorough but that nobody acts on. The result, in the README's words, is a tab nobody opens twice. The skill is opinionated about avoiding that, and the three design choices that do the work are stated up front. The first is forced orientation before judgment, where the protocol requires the model to read the manifest, map the directory structure, analyse git churn and write a mental model of the architecture before it forms any opinions. Phase 1 is not optional, and the summary of the reasoning is blunt: findings without context are vibes.

A citation on every finding, and a section for false alarms

The second choice is file and line citations on every finding, because a finding without a citation is unfalsifiable and unfalsifiable findings do not get fixed. The skill rejects vague claims like the code generally and requires a path/to/file.ext:LINE reference on every concrete finding. The third choice is the one the README calls the single biggest separator between a real audit and a checklist regurgitation: a required section titled looks bad but is actually fine, listing the calls the model considered making and chose not to. Forcing the model to surface those is what catches shallow analysis, and the README says that if the section comes back empty, the audit did not look hard enough. The skill also explicitly forbids recommending rewrites, forbids padding categories with filler, and produces a persistent artifact you can commit and track over time.

Three phases, and what each one actually does

The protocol is documented in full in the skill file, and the README summarises it. The first phase is Orient, where the model reads the manifest, maps the structure, analyses the git log for churn, identifies the largest and most-modified files, and writes a mental model. The README notes that the intersection of largest and most-modified is where debt usually hides, which is a concrete heuristic rather than a general one. The second phase is Audit, a sweep across nine dimensions using ripgrep, ast-grep and language-native tooling, with a citation on every finding. The third is Deliverable, writing the report with an executive summary, the mental model, a findings table, top five priorities, quick wins, the looks-bad-but-is-fine section and open questions. The nine dimensions are architectural decay, consistency rot, type and contract debt, test debt, dependency and configuration debt, performance and resource hygiene, error handling and observability, security hygiene, and documentation drift.

It shells out to the tools your stack already uses

The multi-tool grounding is what keeps the findings grounded in something other than the model's own reading. The skill detects the stack and runs the right tools, folding the results into the report. For TypeScript and JavaScript that is npm audit, knip, madge and depcheck. For Python it is pip-audit, ruff, vulture and pydeps. For Rust it is cargo audit, cargo udeps and cargo machete. And for Go it is govulncheck, staticcheck and golangci-lint. That list tells you the shape of the output, because the findings in the categories of dependency debt and security hygiene are largely the output of those tools rather than of the model, while the architectural and documentation findings are the model's own reading. The language-native tools are also why the skill detects the stack rather than asking you to configure it.

Large repositories get subagents, and repeat runs get a diff

Two features address the practical problems of running this at scale. For codebases over roughly 50k lines of code, the protocol parallelises across modules so the main agent does not run out of context window before Phase 3, which is the failure mode of asking a single agent to read an entire large repository. The second is the repeat-run mode. On subsequent runs, resolved findings are marked RESOLVED, stale ones are updated and new ones are tagged NEW, so the audit becomes a living document rather than a fresh snapshot each time. The README also notes that subsequent runs in this mode are faster, because the existing audit is used as a baseline. The report is designed to be committed, reviewed in pull requests and linked to specific findings, which is what turns a one-off analysis into a tracking mechanism.

Installing it, and how it compares to the built-in skills

Installation is a personal or project-level copy of a single file. For a personal install across all your projects you create the skills directory and download the skill file.

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

For a project-only install the same two commands are combined into one line with a local .claude path. You then verify it is picked up with a skills listing filtered by name. The README explains why this exists alongside the skills Claude Code already ships, and the reasoning is about scope. The review skill is diff-scoped and useful before merging, not when you have inherited a large codebase. The simplify skill is tactical rather than architectural, and does not survey, cite or produce an artifact. The debug skill is reactive, aimed at a known problem, while an audit's job is to find the problems. The loop and batch skills are orchestration primitives rather than analysis.

Editorial conclusion

tech-debt-audit fits a team that has inherited a large repository and wants a written, citable debt inventory it can track over time rather than a wall of ungrounded review comments. It does not fit a small codebase where a manual read is faster, and it does not fit a team that will not commit the report and act on it, since the value of the artifact comes from the follow-up. Verify first that the tools the skill expects are installed for your stack, because it shells out to language specific audit tools, and plan for the runtime, since a first run takes 5 to 20 minutes depending on repository size.

Frequently asked questions

Official sources

1. Issues
2. ksimback/tech-debt-skill on GitHub
3. README