How to use the Tech Debt Tracker agent skill

What an agent skill is and what this one does

An agent skill is a folder containing a SKILL.md file. The file tells the agent when to use the skill, which tools it may use, and how to carry out a task step by step. This one is named tech-debt and is part of the Claude Code Game Studios template.

Once installed, the agent can search your source code for common debt indicators: TODO, FIXME and HACK comments, @deprecated markers, duplicated code blocks, files over 500 lines and functions over 50 lines. It groups each finding under Architecture, Code Quality, Test, Documentation, Dependency or Performance debt, and records them in docs/tech-debt-register.md.

• Scan the code for debt indicators and report the findings
• Add a debt entry by answering a few questions
• Re-rank the register by impact versus effort
• Produce a summary report of open and resolved debt

Install the tech-debt skill from the ZIP or the Claude apps

Download the ZIP for the skill from this page. You have two options.

For a personal setup available in all your projects, unzip the download into ~/.claude/skills/. To limit it to one project, unzip it into that project's .claude/skills/ folder. Either way, the skill folder should contain SKILL.md.

If you use the Claude apps instead, upload the ZIP under Settings, then Capabilities, then Skills.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Run the skill with a subcommand

The skill takes one of four subcommands. In Claude Code you invoke it as /tech-debt followed by the mode name. If you give no subcommand, the skill prints its usage and stops.

Every write to the register asks you for permission first. The skill never overwrites the register; it updates matching entries or appends new ones.

• scan: search the code root and propose new or updated register entries
• add: enter one debt item through guided questions
• prioritize: re-sort the register by priority score
• report: print a read-only summary of current debt

Walk through a scan

Scan searches the code root for src/, Assets/ or Source/, depending on your engine. It uses text searches and size counts. Before it reports anything, it counts the source files it covered.

If the code root is missing or has no source files, the skill reports NOT ASSESSED rather than a clean result. Zero findings across many files is a clean codebase; zero findings across zero files tells you nothing.

After presenting the findings, the skill asks whether it may write them to docs/tech-debt-register.md. If you approve, a finding that matches an existing Open entry for the same file and kind of debt updates that entry instead of creating a duplicate. Open entries whose pattern no longer appears are proposed as Resolved, and you approve those in the same step.

• Counts the files scanned and states that number in its results
• Asks before any write
• Matches existing entries to avoid duplicates

Add, prioritize and report

Add mode asks for a description and affected files, then three choices: category (A to F), estimated fix effort (S, M, L or XL) and impact if left unfixed (Low, Med, High or Critical). It shows the complete entry and asks before appending it.

Prioritize scores each item as impact divided by effort, using Low 1 to Critical 4 and S 1 to XL 4, rounded to one decimal. Higher scores come first, and ties go to the older Added date. Items with a missing impact or effort are listed as not scored instead of being guessed.

Report mode is read-only. It summarises open items by category and effort, items added and resolved in the current sprint, and whether debt is growing, stable or shrinking. It also flags items older than three sprints.

• Add: category, effort and impact questions, then confirmation
• Prioritize: score = impact ÷ effort, ties to older items
• Report: writes no files

Requirements and safety notes

The skill needs Claude Code or a compatible SKILL.md agent and a bash shell. It runs a helper script, hooks/yaml-helper.sh, from the wider template to read configuration. The skill's instructions also refer to other template files, such as .claude/docs/automation-modes.md and .claude/docs/code-root-resolution.md, so it works best inside a project set up with that template.

The skill runs scripts. The source does not list any network use, and this assessment marks it as not using the network. Review the script and the allowed tools in SKILL.md if your organisation needs to approve what runs on its machines.

The skill only records and ranks debt. It does not fix code. It is not a full static analysis or security scanner, because it relies on simple text searches and size counts.

• Requires Claude Code or a compatible SKILL.md agent, plus a bash shell
• Runs scripts (hooks/yaml-helper.sh); uses no network
• Writes only after you approve
• Does not fix code or replace static analysis or security scanning

Tips for getting useful results

Run scan once implementation is underway. On an empty project the skill will stop with NOT ASSESSED, which is the correct result. Use report at the start of each sprint to see whether debt is growing. Keep impact and effort honest when adding entries, because prioritize depends entirely on those two columns.

• Scan after code exists, not on an empty repository
• Use add for judgement-based debt that scans cannot detect
• Run prioritize before sprint planning and feed the top items into /sprint-plan