SkillAgentSearch skills...

tech-debt-audit

Thorough, file-cited technical debt audit across 9 dimensions using AST-grep (tree-sitter), grep, LSP, and language-native tooling. Produces TECH_DEBT_AUDIT.md with severity, effort estimates, and prioritized fixes

Install / Use

npx skills add code-yeongyu/oh-my-openagent --skill tech-debt-audit

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

97/100

Supported Platforms

Zed

Our assessment of tech-debt-audit

tech-debt-audit scores 97/100 on our quality scale, 146th of 4,700 Development & Engineering skills we index (top 4%).

Its SKILL.md is 9.3 KB long, well organised into 36 sections with 2 code examples: a thorough specification that gives an agent plenty to work with.

With 69,362 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
29/30
Structure
18/20
Description
15/15
Adoption
20/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so tech-debt-audit is actively maintained.
  • Our last check on 2026-11-14 found the source still online.
  • No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
  • Its trust signals score 88/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-09-25. Automated pattern scan on 2026-09-25. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

tech-debt-audit compared with similar skills

All 4 of these similar skills score higher than tech-debt-audit; compare them before choosing.

SkillScoreStarsUpdatedFormat
tech-debt-audit (this skill)by code-yeongyu9769.4k53d agoSKILL.md
taste-skillby Leonxlnx100116.8k8d agoCLAUDE.md
ai-job-searchby ai-job-search-dev10072.1ktodayCLAUDE.md
claude-howtoby luongnv8910047.3k2d agoCLAUDE.md
lobehubby lobehub10085.6ktodayMCP Server

Frequently asked questions

How do I install tech-debt-audit?
Run npx skills add code-yeongyu/oh-my-openagent --skill tech-debt-audit. The install tabs above show the steps for each supported agent.
Which AI agents does tech-debt-audit work with?
It is written for Zed, as a SKILL.md file. Other agents that read the same format can often use it too.
Is tech-debt-audit safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 88/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is tech-debt-audit still maintained?
The repository was last updated about 2 months ago, so tech-debt-audit is actively maintained.

name: tech-debt-audit description: "Thorough, file-cited technical debt audit across 9 dimensions using AST-grep (tree-sitter), grep, LSP, and language-native tooling. Produces TECH_DEBT_AUDIT.md with severity, effort estimates, and prioritized fixes. Use when asked for codebase health check, tech debt audit, architecture review, code quality assessment, or cleanup planning. Triggers: 'tech debt', 'technical debt', 'debt audit', 'code health', 'technical debt audit', 'codebase health check', 'find tech debt', 'debt analysis', 'audit code quality'."

Tech Debt Audit Protocol

Model-agnostic technical debt audit for oh-my-openagent (OMO). Uses OMO's built-in tools (grep, glob, bash with sg, read, lsp_diagnostics, task). Produces a grounded, citable TECH_DEBT_AUDIT.md artifact.

Output

Write results to TECH_DEBT_AUDIT.md in the repo root with:

  1. Executive Summary — 3-5 sentences: overall health, worst dimension, quick wins count
  2. Mental Model — the repo's architecture in 1 paragraph (what it does, stack, module boundaries)
  3. Findings Table — columns: ID, Category, File:Line, Severity (Critical/High/Medium/Low), Effort (Hours), Description, Recommendation
  4. Top 5 Priorities — ranked by impact/effort ratio
  5. Quick Wins Checklist — items under 30 minutes each
  6. "Looks Bad But Is Fine" — patterns that look like debt but are intentional
  7. Open Questions — things the maintainer should clarify

Phase 0: Orient

Standard (always run)

  1. glob("**/*.ts") / glob("**/*.py") / etc — map the language stack
  2. glob("**/package.json") + read() — dependencies and build tooling
  3. bash("git log --oneline -200") — churn: find highest-change files
  4. glob("**/*") + basic math — find largest files (>300 LOC are candidates)
  5. Cross-reference high-churn + large = debt hot zones
  6. Write the mental model paragraph in your own working context

Phase 1: Audit Across 9 Dimensions

Use OMO tools for each dimension. Run parallel tool calls within each dimension. Every finding MUST cite file:line:col.

1. Architectural Decay

Standard (always run)

  • bash("sg -p \"import { $$$ } from '$SRC'\" -l ts .") — map module graph, look for circular patterns
  • bash("sg -p \"class $NAME { $$$ }\" -l ts .") — check for god classes
  • grep("TODO|FIXME|HACK|XXX|WORKAROUND|TEMP") — tagged debt markers
  • grep("async|await") on sync-looking files — misplaced async boundaries
  • bash("wc -l <file>") on each large file found in Phase 0

What to flag

  • Files > 500 LOC (god files)
  • Functions > 80 LOC or > 4 nesting levels
  • Classes with > 15 methods or > 400 LOC
  • Import cycles (A → B → A)
  • Dead exports: function/class defined but never imported elsewhere (confirm with lsp_find_references)
  • Commented-out code blocks (>3 consecutive consecutive lines)

2. Consistency Rot

Standard (always run)

  • bash("sg -p \"import $CLIENT from '$PKG'\" -l ts .") — multiple HTTP clients
  • grep("console.log|console.error|console.warn") — direct console use vs logger
  • bash("sg -p \"try { $$$ } catch ($$$) { $$$ }\" -l ts .") — error handling patterns
  • grep("as any|@ts-ignore|@ts-expect-error|as unknown") — type escapes
  • grep("eslint-disable|prettier-ignore") — lint suppressions

What to flag

  • 3+ ways of doing the same thing (HTTP, logging, validation, config)
  • Mixed naming conventions (camelCase + snake_case + PascalCase)
  • Multiple date/time handling libraries
  • Mixed error response shapes across modules

3. Type & Contract Debt

Standard (always run)

  • bash("sg -p \"$VALUE as any\" -l ts .") — runtime type escapes
  • grep("@ts-expect-error") — suppressed errors
  • grep("@ts-ignore") — suppressed errors (legacy)
  • bash("sg -p \"$NAME: any\" -l ts .") — typed as any
  • lsp_diagnostics(filePath="<src-dir>") — current type errors

What to flag

  • any types on public APIs and exported interfaces
  • Untyped function parameters
  • Missing schema validation at API/IO boundaries
  • LSP type errors grouped by file

4. Test Debt

Standard (always run)

  • glob("**/*.test.ts") — find all test files
  • bash("bun test 2>&1 | grep -E '(fail|skip|todo)'") — current test health
  • Cross-reference Phase 0 high-churn files with test existence

What to flag

  • Critical-path files with zero tests
  • Skipped tests (test.skip, describe.skip)
  • Tests asserting implementation details vs behavior
  • Slow tests (>1s each)

5. Dependency & Config Debt

Standard (always run)

  • bash("npm audit --omit=dev 2>&1 | head -40") — known CVEs (if node_modules present)
  • read("package.json") — check dependency count and stale deps
  • grep(".env|process.env|Bun.env") — env var usage
  • grep("API_KEY|SECRET|PASSWORD|TOKEN") in non-config files — hardcoded config

What to flag

  • Outdated major-version deps
  • Dependencies that do the same thing (duplicate libraries)
  • Referenced env vars not documented in README
  • Hardcoded environment-specific values

6. Performance & Resource Hygiene

Standard (always run)

  • bash("sg -p \"for ($$$ of $$$) { $$$ await $$$ }\" -l ts .") — async-in-loop
  • grep("await.*map|await.*filter|await.*forEach") — sequential async iteration
  • grep("Promise\\.all|Promise\\.allSettled") — existing parallel patterns (good signal)
  • grep("addEventListener|on\\(|subscribe") without removeEventListener|off\\(|unsubscribe nearby — listener hygiene

What to flag

  • await inside for/of loops (sequential when parallel possible)
  • N+1 query patterns
  • Missing cleanup on event listeners, intervals, handles
  • Unnecessary serialization/deserialization

7. Error Handling & Observability

Standard (always run)

  • bash("sg -p \"catch ($$$) { $$$ }\" -l ts .") — catch blocks
  • grep("catch.*{}|catch.*{\\s*}") — empty catch blocks
  • grep("console.error|logger\\.error|log\\.error") — actual error logging
  • bash("sg -p \"throw new $ERR($$$)\" -l ts .") — error types used

What to flag

  • Empty catch blocks (worst offense)
  • Generic catch (e) { console.error(e) } without recovery
  • Inconsistent error shapes across modules
  • Missing structured logging on critical paths
  • Errors swallowed in promise chains (.catch(() => {}))

8. Security Hygiene

Standard (always run)

  • grep("api[Kk]ey|api_secret|password|secret|token|credential") in source files (not config or env)
  • grep("SELECT .* FROM|INSERT INTO|UPDATE.*SET|DELETE FROM") — SQL construction
  • grep("innerHTML|dangerouslySetInnerHTML") — XSS vectors
  • grep("eval\\(|Function\\(|setTimeout\\(.*string|setInterval\\(.*string") — code injection

What to flag

  • Hardcoded secrets in source
  • String-concatenated SQL
  • innerHTML / dangerouslySetInnerHTML usage
  • eval() or string-based setTimeout/setInterval
  • Permissive CORS or auth middleware

9. Documentation Drift

Standard (always run)

  • read("README.md") — check if claims match reality
  • grep("@param|@returns|@throws") — docstring coverage
  • grep("FIXME|TODO|HACK|XXX|WORKAROUND") — fixme density
  • Compare README API examples with actual signatures

What to flag

  • README claiming features that don't exist
  • Public functions without any doc comment
  • Comments that contradict the code
  • Stale architecture decision records (ADRs) if present

Phase 2: Deeper Dives (Parallel Sub-Agents)

For large codebases (>50k LOC), delegate heavy dimensions to parallel sub-agents. Each sub-agent runs the standard tool passes for its dimensions:

task(category="unspecified-low", run_in_background=true, load_skills=[], prompt="[CONTEXT] Tech debt audit. [GOAL] Audit dimensions 1 (Architecture) and 2 (Consistency). [REQUEST] Run ast_grep and grep searches for dimensions 1-2 from the tech-debt-audit skill. Report every finding with file:line:col. Tag severity: Critical/High/Medium/Low.")
task(category="unspecified-low", run_in_background=true, load_skills=[], prompt="[CONTEXT] Tech debt audit. [GOAL] Audit dimensions 3 (Type debt) and 7 (Error handling). [REQUEST] Run searches for dimensions 3 and 7 from the tech-debt-audit skill. Report every finding with file:line:col. Tag severity.")

Spawn 2-3 sub-agents for the heaviest dimensions, collect results in parallel, then synthesize.

Phase 3: Synthesize & Deliver

  1. Collect all findings from direct tool calls and sub-agent results
  2. Deduplicate — same issue mentioned by multiple dimensions
  3. Classify severity:
    • Critical — Causes incorrect behavior, data loss, or security vulnerability
    • High — Will cause problems in production; blocks maintenance
    • Medium — Reduces maintainability; violates conventions
    • Low — Cosmetic; should fix when in the area
  4. Estimate effort in hours per finding (conservative)
  5. Write TECH_DEBT_AUDIT.md with all required sections
  6. Report summary to the user

Severity Rubric

Critical = actively causing bugs or security holes
High     = will cause problems under normal operation; blocks changes
Medium   = reduces maintainability; inconsistent; violates team conventions
Low      = cosmetic; would be nice to fix when nearby

Quick Checks Before Finishing

  • [ ] Every concrete finding has file:line:col citation
  • [ ] No generic claims without evidence
  • [ ] "Looks Bad But Is Fine" section explains at least 2-3 patterns
  • [ ] Top 5 priorities ranked by impact/effort
  • [ ] Quick wins are things that can be fixed in <30 minutes each

Related Skills

View on GitHub
GitHub Stars69.4k
CategoryDevelopment
Updated1mo ago
Forks5.7k

Languages

TypeScript

Trust signals

88/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 medium
tech-debt-audit — Zed Skill: Install & Safety Check | SkillAgent