mkdir -p ~/.claude/skills/health-check/scripts

health-check/
├── SKILL.md          # 入口（必需）
└── scripts/
    └── audit.py      # 真正干活的脚本

---
description: 项目代码体检工具。扫描代码库，统计文件结构、挖掘技术债（TODO/FIXME/HACK）、识别超大文件与空目录，并生成可在浏览器打开的交互式 HTML 健康报告。当用户说"检查项目健康度""代码体检""有哪些 TODO""项目质量报告"时使用。
argument-hint: [目标目录，默认当前目录]
allowed-tools: Bash(python3 *)
---

# 项目健康检查

对当前项目（或参数指定的目录）做一次代码体检，产出交互式 HTML 报告。

## 执行步骤
1. 运行体检脚本，目录优先取参数，否则取当前目录：
   ```bash
   python3 ${CLAUDE_SKILL_DIR}/scripts/audit.py "${1:-.}"
   ```
2. 脚本在当前目录生成 `health-report.html`。
3. 用一句话告知报告路径，并按严重度口头总结最值得先处理的 3 项。

## 当前工作树（动态注入，仅供你参考）
- 分支与改动：!`git rev-parse --abbrev-ref HEAD 2>/dev/null; git status --short 2>/dev/null | head -15`
- 未提交文件数：!`git status --short 2>/dev/null | wc -l`

#!/usr/bin/env python3
"""Project health-check: scan a codebase and emit an interactive HTML report."""
import sys, os, html
from pathlib import Path
from collections import Counter

IGNORE_DIRS = {'.git', 'node_modules', '__pycache__', '.venv', 'venv',
               'dist', 'build', '.next', 'target', '.idea', '.vscode'}
IGNORE_EXT = {'.lock', '.map', '.min.js', '.min.css'}
DEBT_TOKENS = ('TODO', 'FIXME', 'HACK', 'XXX')
LARGE_BYTES = 100 * 1024  # 100KB 阈值
MAX_DEBT = 500            # 技术债条目上限，防止超大仓库爆内存

def walk(root: Path):
    for dirpath, dirnames, filenames in os.walk(root):
        dirnames[:] = [d for d in dirnames if d not in IGNORE_DIRS and not d.startswith('.')]
        empty = not filenames and not dirnames
        yield Path(dirpath), filenames, empty

def main():
    root = Path(sys.argv[1] if len(sys.argv) > 1 else '.').resolve()
    if not root.is_dir():
        print(f'[error] not a directory: {root}', file=sys.stderr); sys.exit(1)

    ext_count = Counter(); ext_size = Counter()
    large_files = []; empty_dirs = []; debt = []; total = 0

    for dpath, files, empty in walk(root):
        if empty and dpath != root:
            empty_dirs.append(dpath.relative_to(root))
        for fn in files:
            f = dpath / fn
            try: size = f.stat().st_size
            except OSError: continue
            total += size
            ext = f.suffix.lower() or '(无扩展名)'
            ext_count[ext] += 1; ext_size[ext] += size
            if size > LARGE_BYTES:
                large_files.append((f.relative_to(root), size))
            if ext in ('.py', '.js', '.ts', '.tsx', '.jsx', '.go', '.rs',
                       '.java', '.c', '.cpp', '.h', '.rb', '.php', '.vue', '.sh'):
                try: scan_debt(f, root, debt)
                except (OSError, UnicodeDecodeError): pass
            if len(debt) > MAX_DEBT: break

    write_html(root, ext_count, ext_size, large_files, empty_dirs, debt, total)
    print(f'[ok] -> {Path("health-report.html").resolve()}')

def scan_debt(f, root, debt):
    for i, line in enumerate(f.read_text(encoding='utf-8', errors='ignore').splitlines(), 1):
        up = line.upper()
        for tok in DEBT_TOKENS:
            if tok in up:
                debt.append((tok, f.relative_to(root), i, line.strip()[:120]))
                return  # 每行只记第一个命中，避免噪声

def write_html(root, ext_count, ext_size, large_files, empty_dirs, debt, total):
    def kb(b): return f'{b/1024:.1f} KB' if b < 1048576 else f'{b/1048576:.2f} MB'
    top = ext_size.most_common(8)
    maxsz = top[0][1] if top else 1
    palette = ['#3776ab','#3178c6','#f7df1e','#00add8','#dea584','#cc342d','#264de4','#6b7280']
    bars = ''.join(
        f'<div style="margin:6px 0"><span style="font-family:monospace">{html.escape(e)}</span>'
        f'<div style="background:{palette[i%8]};width:{sz/maxsz*100:.1f}%;height:14px"></div>'
        f'<small>{ext_count[e]} 个 · {kb(sz)}</small></div>'
        for i,(e,sz) in enumerate(top))

    debt_rows = ''.join(
        f'<tr><td><b>{t}</b></td><td style="font-family:monospace">{html.escape(str(p))}</td>'
        f'<td>{ln}</td><td>{html.escape(msg)}</td></tr>'
        for t,p,ln,msg in sorted(debt, key=lambda x: ['TODO','FIXME','HACK','XXX'].index(x[0]))[:300]) or '<tr><td colspan=4>无</td></tr>'

    large_rows = ''.join(
        f'<tr><td style="font-family:monospace">{html.escape(str(p))}</td><td>{kb(sz)}</td></tr>'
        for p,sz in sorted(large_files, key=lambda x:-x[1])[:50]) or '<tr><td colspan=2>无</td></tr>'

    empty_list = ''.join(f'<li style="font-family:monospace">{html.escape(str(d))}/</li>'
                        for d in sorted(empty_dirs)[:50]) or '<li>无</li>'

    doc = f'''<!doctype html><html lang="zh"><head><meta charset="utf-8">
<title>健康报告 · {html.escape(root.name)}</title>
<style>body{{font-family:-apple-system,Segoe UI,sans-serif;margin:24px;color:#1a1a1a}}
h1{{font-size:20px}} .cards{{display:flex;gap:12px;flex-wrap:wrap;margin:16px 0}}
.card{{background:#f5f7fa;border-radius:8px;padding:14px 18px;min-width:120px}}
.card b{{font-size:22px;display:block}} table{{border-collapse:collapse;width:100%;margin:8px 0}}
td,th{{border:1px solid #e3e8ef;padding:6px 10px;text-align:left;font-size:13px}}
th{{background:#f5f7fa}} code{{background:#eef;padding:1px 4px;border-radius:3px}}</style></head>
<body><h1>🏥 项目健康报告</h1><p>扫描根目录：<code>{html.escape(str(root))}</code></p>
<div class="cards">
<div class="card"><b>{sum(ext_count.values())}</b>文件总数</div>
<div class="card"><b>{kb(total)}</b>总体积</div>
<div class="card"><b>{len(debt)}</b>技术债标记</div>
<div class="card"><b>{len(large_files)}</b>超大文件</div>
<div class="card"><b>{len(empty_dirs)}</b>空目录</div>
</div>
<h2>📊 按类型体积分布（Top 8）</h2>{bars}
<h2>⚠️ 技术债（TODO/FIXME/HACK/XXX）</h2>
<table><tr><th>类型</th><th>文件</th><th>行</th><th>内容</th></tr>{debt_rows}</table>
<h2>🐘 超大文件（&gt;100KB）</h2>
<table><tr><th>文件</th><th>体积</th></tr>{large_rows}</table>
<h2>🕳️ 空目录</h2><ul>{empty_list}</ul></body></html>'''

    Path('health-report.html').write_text(doc, encoding='utf-8')

if __name__ == '__main__':
    main()

帮我对这个项目做一次代码体检，重点看技术债。

/health-check ./packages/backend

flowchart TD
    A[用户: 帮我体检这个项目] --> B{description 是否匹配?}
    B -- 是 --> C[Claude Code 决定激活 Skill]
    B -- 否/手动 --> Z[/health-check dir/]
    Z --> C
    C --> D[注入 !git status 等真实数据]
    D --> E[把 SKILL.md 正文交给模型]
    E --> F[模型解析 ${CLAUDE_SKILL_DIR}]
    F --> G[执行 audit.py 目标目录]
    G --> H[脚本扫描并写 health-report.html]
    H --> I[模型读取脚本输出]
    I --> J[口头总结前三问题 + 报告路径]
    style C fill:#e3f2fd
    style G fill:#fff3e0
    style H fill:#fff3e0