Agent skill

Tech Debt

A skill your agent uses when reworking a change to prevent tech debt, or auditing existing debt to categorize, score, and prioritize the refactor backlog.

MITAuto-check passedDevelopment

Install Tech Debt

skills CLI

$ npx skills add secondsky/claude-skills --skill tech-debt -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI

$ gh skill install secondsky/claude-skills tech-debt --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy

$ git clone --depth 1 https://github.com/secondsky/claude-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/plugins/tech-debt/skills/tech-debt .claude/skills/tech-debt && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Paste into Claude Code

Install the "tech-debt" agent skill from https://github.com/secondsky/claude-skills/tree/main/plugins/tech-debt/skills/tech-debt into .claude/skills/tech-debt/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "tech-debt", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/secondsky/claude-skills/tree/main/plugins/tech-debt/skills/tech-debt

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add secondsky/claude-skills --skill tech-debt -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install secondsky/claude-skills tech-debt --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/secondsky/claude-skills.git skills-src && mkdir -p .agents/skills && cp -r skills-src/plugins/tech-debt/skills/tech-debt .agents/skills/tech-debt && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "tech-debt" agent skill from https://github.com/secondsky/claude-skills/tree/main/plugins/tech-debt/skills/tech-debt into .agents/skills/tech-debt/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "tech-debt", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add secondsky/claude-skills --skill tech-debt -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install secondsky/claude-skills tech-debt --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/secondsky/claude-skills.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/plugins/tech-debt/skills/tech-debt .cursor/skills/tech-debt && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "tech-debt" agent skill from https://github.com/secondsky/claude-skills/tree/main/plugins/tech-debt/skills/tech-debt into .cursor/skills/tech-debt/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "tech-debt", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/secondsky/claude-skills.git --path plugins/tech-debt/skills/tech-debt

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add secondsky/claude-skills --skill tech-debt -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install secondsky/claude-skills tech-debt --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/secondsky/claude-skills.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/plugins/tech-debt/skills/tech-debt .gemini/skills/tech-debt && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "tech-debt" agent skill from https://github.com/secondsky/claude-skills/tree/main/plugins/tech-debt/skills/tech-debt into .gemini/skills/tech-debt/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "tech-debt", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install secondsky/claude-skills tech-debt

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add secondsky/claude-skills --skill tech-debt -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/secondsky/claude-skills.git skills-src && mkdir -p .github/skills && cp -r skills-src/plugins/tech-debt/skills/tech-debt .github/skills/tech-debt && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "tech-debt" agent skill from https://github.com/secondsky/claude-skills/tree/main/plugins/tech-debt/skills/tech-debt into .github/skills/tech-debt/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "tech-debt", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add secondsky/claude-skills --skill tech-debt -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install secondsky/claude-skills tech-debt --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/secondsky/claude-skills.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/plugins/tech-debt/skills/tech-debt .opencode/skills/tech-debt && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "tech-debt" agent skill from https://github.com/secondsky/claude-skills/tree/main/plugins/tech-debt/skills/tech-debt into .opencode/skills/tech-debt/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "tech-debt", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: tech-debt
GitHub stars: 227
Token cost: ~1.2k tokens
SKILL.md length: 552 words
Files: 3 (incl. references)
Skills in repo: 169
Repo updated: Sep 28, 2026
First seen: Oct 7, 2026
Licence: MIT

At a glance

A skill your agent uses when reworking a change to prevent tech debt, or auditing existing debt to categorize, score, and prioritize the refactor backlog.

Reworking a change to prevent tech debt
SKILL.md covers Overview, When to use, How this skill works — router and Routing, plus 3 more sections
Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
Auditing existing debt to categorize

What it does

Tech Debt is an agent skill from secondsky/claude-skills. Use when reworking a change to prevent tech debt, or auditing existing debt to categorize, score, and prioritize the refactor backlog.

Its SKILL.md is about 1.2k tokens, which your agent loads only when the skill is triggered. The skill folder holds 3 other files, including reference files (for example `references/prevent-during-change.md` and `references/triage-backlog.md`).

It sits in Development, covering Technical debt. The repository describes itself as: Production-ready skills for Claude Code CLI - Cloudflare, React, Tailwind v4, and AI integrations. The licence is MIT.

When your agent uses it

Reworking a change to prevent tech debt
Auditing existing debt to categorize
Prioritize the refactor backlog

Example prompts

“/tech-debt”

What it can do on your machine

Read from SKILL.md and the folder at commit 8837836. It shows what the files ask for, not the result of running them.

Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
No scripts in the folder and no shell commands in SKILL.md (its code samples are dot).
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Tech Debt loads about 1.2k tokens when it runs, and up to ~3.8k if it reads all its reference files. Until then it costs about 36 tokens; SKILL.md has 552 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~36
When it runs · the whole SKILL.md, loaded when a task matches: ~1.2k
With references · SKILL.md plus every file in references/, read only if the agent opens them: ~3.8k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from secondsky/claude-skills at commit 8837836, republished under its MIT licence (© secondsky). 552 words, ~1,231 tokens.

Download SKILL.mdSave it as .claude/skills/tech-debt/SKILL.md (or your agent's skills folder). This skill also uses 2 other files; get the full folder from GitHub.

name: tech-debt
description: Use when reworking a change to prevent tech debt, or auditing existing debt to categorize, score, and prioritize the refactor backlog.
license: MIT
metadata.keywords: tech-debt, technical-debt, refactor, cleanup, dead-code, remediation, architecture-debt, code-smell, mode-flags, compatibility-cruft, backward-compatible…

Tech Debt

Overview

Two complementary stances on technical debt, picked apart by the router in this file:

Mode A — Prevent: while you're making a change, rework it toward the intended end state. Delete the dead compatibility path instead of preserving it.
Mode B — Triage: while you're assessing existing code, categorize, score, and prioritize the debt into a remediation plan.

They run at different points in a debt's lifecycle: prevent when writing, triage when planning. Triage output feeds back into prevent, one item at a time.

When to use

Use Mode A when:

You are implementing, finishing, or reviewing a feature / fix / refactor and the user wants the change clean.
You're about to keep a fallback, alias, mode flag, or wrapper "just in case" — check it has a caller first.
The user says "do this properly", "no bandaids", "zero tech debt", or "don't leave a mess".

Use Mode B when:

The user asks for a tech-debt audit, code-health review, or "what should we refactor?"
The user wants to prioritize a maintenance / refactor backlog or roadmap.
Debt has accumulated and nobody is sure what to fix first.

When NOT to use:

A single obvious local fix with no structural angle — just fix it; don't invoke a debt framework.
Style/formatting nits — point them at the linter/formatter, not here.
Greenfield where the intended end state is genuinely unknown (Mode A can't target what isn't defined yet).

How this skill works — router

This skill is a ROUTER. This file stays a thin orchestrator. It picks exactly one mode (or the chain A→B→A), then you load the matching references/*.md and follow it. The two reference docs hold the actual steps, rules, and examples.

Never inline a reference doc's body. If a branch is more than a 2–3 line summary, it belongs in references/. The decision of which branch to take stays here.

Why: keeping the router thin keeps it scannable, and loading the branch body only when the mode is confirmed saves context on the wrong branch.

Show full SKILL.md (221 more words)Show less

Routing

Decision criterion — one boolean property of the task: Is the user actively making a change right now (writing/editing code, has a diff)? yes → Mode A; no → Mode B. The chain rule: once a triaged item is being implemented, switch to Mode A for that change.

dot

digraph tech_debt_route {
  rankdir=TB;
  node [shape=box];

  start  [label="User task touches tech debt" shape=oval];
  q      [label="Actively making a change\n(writing/editing code, has a diff)?" shape=diamond];
  a      [label="MODE A — PREVENT\nRework THIS change to the\nintended end state"];
  b      [label="MODE B — TRIAGE\nCategorize + score the\nwhole codebase's debt"];
  loadA  [label="Load references/prevent-during-change.md"];
  loadB  [label="Load references/triage-backlog.md"];
  chain  [label="Implementing a triaged item?\nSwitch to Mode A for that change" shape=diamond];

  start -> q;
  q -> a [label="yes"];
  q -> b [label="no — assessing existing code"];
  a -> loadA;
  b -> loadB;
  loadB -> chain;
  chain -> loadA [label="yes, per item"];
}

Routing table

If the user is…	Mode	Load
implementing/finishing a feature, fix, or refactor and wants the change clean	A	`references/prevent-during-change.md`
about to preserve a fallback/alias/flag "just in case"	A	`references/prevent-during-change.md`
asking for a tech-debt audit / "what should we refactor" / code-health review	B	`references/triage-backlog.md`
asking to prioritize a maintenance or refactor backlog	B	`references/triage-backlog.md`
fixing an item that came out of a triage	A (per item)	`references/prevent-during-change.md`

Mode A — Prevent (during a change)

Rework the change from the intended end state, not the path that led to the current patch. Optimize for the code that should exist; delete dead compatibility paths rather than improving them. Prefer one clear component/flow over mode flags.

Load references/prevent-during-change.md and follow it.

Mode B — Triage (audit a backlog)

Systematically identify, categorize, and prioritize existing debt across the codebase. Produce a prioritized list with effort estimates and a phased remediation plan that can run alongside feature work.

Load references/triage-backlog.md and follow it.

Bottom line

Prevent new debt while you're changing the code; triage old debt when you're planning what to fix.

Files

SKILL.md and 2 other files (references) in plugins/tech-debt/skills/tech-debt of secondsky/claude-skills.

SKILL.md
references/prevent-during-change.md
references/triage-backlog.md

Open the folder on GitHubat commit 8837836

Compare with similar skills

Tech Debt next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Tech Debt compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Tech Debt this skillsecondsky/claude-skills	227	—	~1.2k	Automated safety check: Pass	MIT	9 days ago
Systematic Code Refactoringluongnv89/claude-howto	42k	—	~3k	Automated safety check: Pass	MIT	7 days ago
Code Simplification for ego-litecitrolabs/ego-lite	17k	—	~1.2k	Automated safety check: Pass	MIT	14 days ago
Code Refactoring Workflowluongnv89/claude-howto	42k	—	~3.1k	Automated safety check: Pass	MIT	7 days ago
Cto AdvisorIbrahim-3d/orchestrator-supaconductor	380	4 repos	~2.4k	Automated safety check: Pass	MIT	10 days ago
Tech Debt Analyzerailabs-393/ai-labs-claude-skills	454	2 repos	~3.9k	Automated safety check: Pass	MIT	11 mo ago

Similar skills

Systematic Code Refactoring
luongnv89/claude-howto
Guides refactoring in phases based on Martin Fowler's method: research, test coverage check, planning and small tested steps, with your approval at each phase.
42k GitHub stars~3k tokensUpdated 7 days ago
DevelopmentAuto-check passed
Code Simplification for ego-lite
citrolabs/ego-lite
Finds and implements evidence-backed simplifications in the ego-lite repository, such as dead code, duplicated state and speculative abstractions, without hiding behavior changes.
17k GitHub stars~1.2k tokensUpdated 14 days ago
DevelopmentAuto-check passed
Code Refactoring Workflow
luongnv89/claude-howto
Guides systematic, test-backed refactoring in the style of Martin Fowler, moving through research, planning and small incremental changes with your approval at each phase.
42k GitHub stars~3.1k tokensUpdated 7 days ago
DevelopmentAuto-check passed
Cto Advisor
Ibrahim-3d/orchestrator-supaconductor
Technical leadership guidance for engineering teams, architecture decisions, and technology strategy.
380 GitHub starsUsed in 4 repos~2.4k tokens
DevelopmentAuto-check passed
Tech Debt Analyzer
ailabs-393/ai-labs-claude-skills
This skill should be used when analyzing technical debt in a codebase, documenting code quality issues, creating technical debt registers, or assessing code maintainability.
454 GitHub starsUsed in 2 repos~3.9k tokens
DevelopmentAuto-check passed
FIXME Resolver
tailcallhq/forgecode
Finds every FIXME comment in a codebase, groups related ones across files into one task, implements the work they describe and removes the comments once it is done.
7.6k GitHub stars~1.1k tokensUpdated today
DevelopmentAuto-check passed

More from secondsky/claude-skills

All 169 skills in this repo

Tanstack AI
secondsky/claude-skills
TanStack AI (alpha) provider-agnostic type-safe chat with streaming for OpenAI, Anthropic, Gemini, Ollama.
227 GitHub starsUsed in 1 repo~3.6k tokens
Auto-check: notes
Auto Animate
secondsky/claude-skills
AutoAnimate (@formkit/auto-animate) zero-config animations for React.
227 GitHub stars~2.9k tokensUpdated 9 days ago
Auto-check passed
Base UI React
secondsky/claude-skills
MUI Base UI unstyled React components with Floating UI. An agent skill from secondsky/claude-skills.
227 GitHub stars~1.9k tokensUpdated 9 days ago
Auto-check passed
Cloudflare Images
secondsky/claude-skills
This skill should be used when the user asks to "upload images to Cloudflare", "implement direct creator upload", "configure image transformations", "optimize WebP/AVIF", "create image variants"…
227 GitHub stars~3.6k tokensUpdated 9 days ago
Auto-check: notes
Cloudflare Nextjs
secondsky/claude-skills
Deploy Next.js to Cloudflare Workers via the OpenNext adapter (@opennextjs/cloudflare).
227 GitHub stars~5.3k tokensUpdated 9 days ago
Auto-check: notes
Cloudflare Sandbox
secondsky/claude-skills
Cloudflare Sandboxes SDK for secure code execution in Linux containers at edge.
227 GitHub stars~4.5k tokensUpdated 9 days ago
Auto-check passed

Questions about Tech Debt

What does Tech Debt do?

A skill your agent uses when reworking a change to prevent tech debt, or auditing existing debt to categorize, score, and prioritize the refactor backlog. Tech Debt is an agent skill from secondsky/claude-skills. Use when reworking a change to prevent tech debt, or auditing existing debt to categorize, score, and prioritize the refactor backlog.

When should I use Tech Debt?

Tech Debt fits situations like: reworking a change to prevent tech debt; auditing existing debt to categorize; prioritize the refactor backlog.

How do I install Tech Debt in Claude Code?

Run `npx skills add secondsky/claude-skills --skill tech-debt -a claude-code`. Or copy the skill folder (plugins/tech-debt/skills/tech-debt in secondsky/claude-skills) into .claude/skills/tech-debt in your project. Claude Code loads it when a task matches its description.

How do I install Tech Debt in Codex?

Run `npx skills add secondsky/claude-skills --skill tech-debt -a codex`. Or copy the skill folder (plugins/tech-debt/skills/tech-debt in secondsky/claude-skills) into .agents/skills/tech-debt in your project. Codex loads it when a task matches its description.

Can I use Tech Debt in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add secondsky/claude-skills --skill tech-debt -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/tech-debt, .gemini/skills/tech-debt, .github/skills/tech-debt and .opencode/skills/tech-debt in your project.

What does Tech Debt need to run?

SKILL.md names no scripts, command-line tools or credentials: Tech Debt is instructions for the agent only.

Does Tech Debt access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Tech Debt safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Tech Debt use?

Tech Debt is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Tech Debt use?

About 1.2k tokens (SKILL.md is roughly 4.9k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 2.5k tokens, read only when the agent opens those files.

What are the alternatives to Tech Debt?

Skills that share tags, products or a category with Tech Debt: Systematic Code Refactoring (luongnv89/claude-howto, 42k stars), Code Simplification for ego-lite (citrolabs/ego-lite, 17k stars), Code Refactoring Workflow (luongnv89/claude-howto, 42k stars) and Cto Advisor (Ibrahim-3d/orchestrator-supaconductor, 380 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Tech Debt?

secondsky (a GitHub user) maintains it in secondsky/claude-skills, which has 227 GitHub stars. The repository holds 169 skills in this directory. The repository was last updated on September 28, 2026.

Source: secondsky/claude-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.

Install Tech Debt

Facts

At a glance

What it does

When your agent uses it

Example prompts

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

Tech Debt

Overview

When to use

How this skill works — router

Routing

Routing table

Mode A — Prevent (during a change)

Mode B — Triage (audit a backlog)

Bottom line

Files

Compare with similar skills

Similar skills

More from secondsky/claude-skills

Related

Questions about Tech Debt