techdebt
Skill2 starsChanged 8 months agoApache-2.0View on GitHub
Scan for technical debt and fix it. Uses Simplifier to identify dead code, duplication, complexity, and inconsistencies, then Verifier to confirm no regressions.
14 other projects use a version of this.
Adopted by
Most recently taken up by
- Lucface/claude-skillstheir own version, first seen Nov 16, 2026
- jh941213/my-cc-harnesstheir own version, first seen Nov 1, 2026
- jh941213/ADLC-harnesstheir own version, first seen Nov 1, 2026
- LucasCooperBey/claude-skillstheir own version, first seen Oct 20, 2026
- mikezamayias/agent-skillstheir own version, first seen Oct 11, 2026
- DoubleML/doubleml-for-pytheir own version, first seen Oct 8, 2026
Used with
Projects with it also use docs-ci, docs-interfaces and 8 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
jh941213Skilldocs-ci
문서 CI(링크·OpenAPI lint·breaking 게이트·mermaid 검증)나 문서 드리프트 감지(docs.yaml 신선도 검사)를 설치하거나 돌릴 때 사용. 문서 내용 작성은 docs-architecture·docs-interfaces·docs-manuals.
Also in 3 projects that use this
jh941213Skilldocs-interfaces
API·이벤트 인터페이스 문서(OpenAPI·swagger·AsyncAPI 명세, 엔드포인트 레퍼런스, API 구성도·시퀀스, API CHANGELOG)를 만들거나 코드와 맞출 때 사용. 시스템 구성도는 docs-architecture, API 설계 원칙은 api-design-principles.
Also in 3 projects that use this
RachaelQuiselSkillclient-docs
Client documentation. Use when a build needs documentation updates or missing project documents need to be identified.
Also in 3 projects that use this
planailabsSkilldocs-architecture
Layout, build pipeline, and structural gotchas for this dual-Astro repo. Read before changing structure, routing, or adding content. Operational/dev-server questions → dev-build skill.
Also in 3 projects that use this
diego-tobalinaSkillbuild-fix
Fix build and compilation errors systematically. Run when build fails.
Also in 3 projects that use this
nilecuiSkillasync-python-patterns
Master Python asyncio, concurrent programming, and async/await patterns for high-performance applications. Use when building async APIs, concurrent systems, or I/O-bound applications requiring non-blocking operations.
Also in 3 projects that use this
- +4 more from jh941213
Other versions14 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 14
- DoubleML/doubleml-for-py★ 798same name
- DataDog/dd-trace-java★ 739same name
- chenzhen7/akari★ 189same name
- jh941213/ADLC-harness★ 125same name
- jh941213/my-cc-harness★ 125same name
- jh941213/my-claude-code-asset★ 125same name
- aromanarguello/roman-skills★ 18same name
- almax000/claude-skills★ 1same name
- LucasCooperBey/claude-skills★ 1same name
- Lucface/claude-skills★ 1same name
4 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository14 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- commit-push-prSkill
- freshSkill
- goSkill
- grillSkill
- investigateSkill
- prove-itSkill
- retroSkill
- saveSkill
- secreviewSkill
- statusSkill
- tddSkill
- teamSkill
- test-and-fixSkill
The file
We split this skill into the rules it gives an agent
12 rules. 0 are common, 12 are distinctive, and 0 are very specific to this project.
0
Common
Most of the 8 edited versions we read keep these.
12
Distinctive
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 39
Import ordering and formatting inconsistencies
- Distinctive: line 42
Use Glob and Grep to find the files in scope
- Distinctive: line 43
Use Grep to search for debt signals:
- Distinctive: line 50
Use Read to examine flagged files for the deeper categories (duplication, complexity, naming)
- Distinctive: line 69
Run the relevant lint/test command for the language
- Distinctive: line 70
If tests fail, revert the change and move the item to the "Deferred" list
- Distinctive: line 80
Run the full test suite for affected languages
- Distinctive: line 81
Run lint checks (clippy, ruff, shellcheck as appropriate)
- Distinctive: line 83
If anything regressed, report it and revert the offending fix
- Distinctive: line 118
Before a release to clean up accumulated debt
- Distinctive: line 119
After a large feature merge to catch rushed code
- Distinctive: line 120
When onboarding to an unfamiliar codebase to understand its weak spots
“Common” is measured: kept by at least 6 in 10 of the 8 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
/techdebt — Find and Fix Technical Debt
Scan a file, directory, or entire project for technical debt. Identify issues, fix what can be fixed safely, and report what remains.
Input: Optional path (file, directory, or . for the whole project). Defaults to . if no argument given.
Target: $ARGUMENTS
Phase 1 — SCAN (Identify Debt)
Agent perspective: Simplifier (subagent_type: simplifier)
Analyze the target for the following categories of technical debt, ordered by severity:
Category A — Correctness Risk
- Missing error handling (silent failures, bare
unwrap(), emptyexcept:) - TODO/FIXME/HACK comments indicating known broken or incomplete code
- Unreachable code paths that mask bugs
Category B — Maintainability
- Duplicated logic (3+ lines repeated in 2+ places) that should be extracted
- Overly complex functions (50+ lines or 4+ levels of nesting)
- Inconsistent naming or patterns within the same module
- Dead code and unused imports
Category C — Code Hygiene
- Magic numbers/strings that should be constants
- Outdated comments that no longer match the code
- Unnecessary type conversions or redundant operations
- Import ordering and formatting inconsistencies
How to scan:
- Use Glob and Grep to find the files in scope
- Use Grep to search for debt signals:
TODO|FIXME|HACK|XXX|NOCOMMIT unwrap() (Rust — without context) except: (Python — bare except) # shellcheck disable (Shell — suppressed warnings) - Use Read to examine flagged files for the deeper categories (duplication, complexity, naming)
- For each finding, record:
file:line, category (A/B/C), and a one-line description
SCAN checkpoint: [N] findings across [M] files. Breakdown: [A: X, B: Y, C: Z]Phase 2 — FIX (Safe Remediation)
Agent perspective: Simplifier (subagent_type: simplifier)
Fix what can be fixed safely. Rules:
- Category A fixes — Always fix. Missing error handling and dead code are correctness risks.
- Category B fixes — Fix if the change is mechanical (extract function, rename, remove dead code). Skip if it requires design decisions.
- Category C fixes — Fix only if trivial (add constants, fix imports). Skip anything cosmetic that touches many files.
For each fix:
- Make the change
- Run the relevant lint/test command for the language
- If tests fail, revert the change and move the item to the "Deferred" list
FIX checkpoint: [N] items fixed, [M] deferred. Files modified: [list]Phase 3 — VERIFY (Confirm No Regressions)
Agent perspective: Verifier (subagent_type: verifier)
- Run the full test suite for affected languages
- Run lint checks (clippy, ruff, shellcheck as appropriate)
- Confirm all previously passing tests still pass
- If anything regressed, report it and revert the offending fix
Output Format
## Tech Debt Report: [Target]
**Scanned**: [N files, M lines]
**Found**: [X issues] — A: [n], B: [n], C: [n]
**Fixed**: [Y issues]
**Deferred**: [Z issues]
### Fixed
1. `path/file.ext:42` — [Category A] Added error handling for unchecked Result
2. `path/file.ext:87` — [Category B] Extracted duplicated validation into `validate_input()`
...
### Deferred (Requires Design Decision)
1. `path/file.ext:150` — [Category B] Function `process_all` is 120 lines; needs decomposition plan
2. `path/file.ext:33` — [Category A] TODO: "rewrite when upstream API stabilizes"
...
### Verification
- Tests: [X pass, Y fail, Z skip]
- Lint: PASS/FAIL
- Regressions: [None / List]
### Recommended Next Steps
- [ ] [Highest priority deferred item — why it matters]
- [ ] [Second priority — estimated effort]When to Use
- Regular codebase hygiene — run periodically on active projects
- Before a release to clean up accumulated debt
- After a large feature merge to catch rushed code
- When onboarding to an unfamiliar codebase to understand its weak spots
- Any time the user invokes
/techdebtwith an optional target
When NOT to Use
- During active feature development (use
/tddinstead) - For security-specific audits (use SecOps agent directly)
- For design/architecture review (use Architect agent or
/team)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

