The Zero Tech Debt Skill: Force Your AI Agent Delete Legacy Code Instead of Patching It

Notes: installs with one npx command. teaches your agent to design from the end state and cut the historical cruft.

i found this skill file a few weeks ago and i’ve been running it on my codebase ever since. it’s one of the best skill files you can add to a project. readability goes up every time it runs.

the whole philosophy fits in one line:

“rework the change from the intended end state, not from the historical path that produced the current patch.”

your agent’s default is the opposite: smallest diff on top of whatever already exists. this skill flips that. design the change as if the ideal version always existed, then delete what’s left over.

when to run it?

right after you fix a bug or ship a feature, while the agent still has full context. do it consistently and the debt never compounds.

the skill file (skip, installation step below):

---
name: zero-tech-debt
description: Rework a change as if the intended UX and architecture existed from day one, deleting compatibility cruft and accidental complexity.
user-invocable: true
---

# Zero Tech Debt

Rework the change from the intended end state, not from the historical path that produced the current patch.

## Steps

1. State the intended end state in one or two sentences.

2. Search for real callers before preserving compatibility.
   If a mode, prop, wrapper, route alias, or fallback has no current caller, delete it.

3. Reshape around the final product surface.
   Prefer one clear component or flow over mode flags. Split only when it creates an obvious boundary such as state, layout, controls, or domain commands.

4. Move shared rules to one place.
   Feature flags, permissions, route gating, URL state, and command naming should not be duplicated across pages or hidden in view components.

5. Verify the intended flow.
   Test the new behavior and any deleted assumptions that affect navigation, permissions, or persisted state.

## Rules

- Optimize for the code that should exist, not the smallest diff from the old shape.
- Delete dead compatibility paths instead of making them better.
- Do not invent a generic framework for one feature.
- Keep the refactor scoped to what makes the final shape coherent.
- Prefer names that describe product intent over implementation history.

install

npx skills add jnsahaj/skills

Or directly:

npx skills add https://github.com/jnsahaj/skills --skill zero-tech-debt

also on skills.sh.

why your agent needs it

left alone, every coding agent does the same things:

• patches instead of redesigns.

• keeps legacy code “for compatibility” that nothing calls.

• duplicates rules across files.

• gets lazy with names. that’s how newDashboardV2Wrapper ends up in production.

these are defaults, not bugs. you can’t prompt them away once; you have to override them every time. that’s what the skill file does.

---

one markdown file. costs nothing. every run makes the next change easier to make.