用 Claude Code 造一个「代码体检」Skill：从零到产出可读的健康报告

mkdir -p ~/.claude/skills/code-health-audit/scripts

code-health-audit/
├── SKILL.md          # 入口：元数据 + 指令（触发时加载）
└── scripts/
    └── audit.py      # 体检脚本（执行，不进上下文）

---
name: code-health-audit
description: Scans a codebase for maintainability risks—long functions, deep nesting, too many parameters, oversized files, and TODO/FIXME debt—and writes a graded health report. Use when the user asks for a code health check, code smell scan, maintainability audit, refactor hotspot analysis, or technical debt inventory.
allowed-tools:
  - Bash(python3 *)
  - Read
  - Grep
argument-hint: "[directory]"
---

# Code Health Audit

Run the bundled audit script against the target directory (defaults to the project root):

```bash
python3 ${CLAUDE_SKILL_DIR}/scripts/audit.py $ARGUMENTS

**字段拆解**：

- `description`（强烈推荐）：这是 Claude 在上百个 Skill 里挑中你的唯一依据。务必第三人称、把**做什么**和**何时用**都写进去，并放进用户会自然说出的关键词（「code smell」「maintainability audit」「技术债」）。注意 `description` 与 `when_to_use` 合计在 Skill 列表里被截断到 **1536 字符**，所以把最关键的用例放在最前面。
- `name`：仅作展示名，默认等于目录名；命令名始终来自目录，而非此字段（插件根 `SKILL.md` 是唯一例外）。
- `allowed-tools`：**前置授权**——Skill 激活期间，列出的工具免逐次确认即可调用。这里放行 `Bash(python3 *)`，让体检脚本无须每次点头就能跑。注意它只「预授权」而不「限制」：其他工具仍可调用，最终仍受你的权限设置约束。
- `argument-hint`：自动补全时显示的参数提示，让用户知道可以传一个目录。
- 正文里的 `${CLAUDE_SKILL_DIR}`：在运行时被替换为该 Skill 自身所在目录，保证脚本路径无论装在个人级、项目级还是插件级都能正确解析。
- 正文里的 `$ARGUMENTS`：用户在 `/code-health-audit src/` 里跟在后面的 `src/` 会被替换进来；若正文没有 `$ARGUMENTS` 占位符，参数会被追加为 `ARGUMENTS:` 附在末尾。

**预期结果**：保存后，无需重启，新会话或当前会话都能用 `/code-health-audit` 调用，或在你问「体检一下代码」时被自动触发。

**常见问题**：

- *Skill 不触发？* 八成是 `description` 没覆盖用户原话。先用 `What skills are available?` 确认它被列出；再把用户的真实措辞补进 description。frontmatter YAML 写错时，Claude Code 会以空元数据加载正文，`/code-health-audit` 仍能用但自动匹配失效——用 `claude --debug` 可看到解析错误。
- *正文太长怎么办？* 官方建议 SKILL.md 正文控制在 **500 行以内**，因为一旦加载，正文会**在整个会话常驻**，每行都是反复的 token 成本。超长就拆成 `reference.md` 等附属文件，在正文里用一行链接指过去（引用保持**一层深**，不要 A 引 B、B 引 C）。

## 第四步：写体检脚本——确定性部分交给代码

体检是「窄桥两边是悬崖」的典型：必须精确、可复现，所以用固定脚本（低自由度），而不是让 Claude 每次临场写扫描逻辑。脚本遵循官方「**解决它，别甩给 Claude**」原则：自己处理文件读取异常，而不是把错误抛回去让模型兜底。

保存到 `~/.claude/skills/code-health-audit/scripts/audit.py`：

```python
#!/usr/bin/env python3
"""code-health-audit: scan a codebase for maintainability risks, emit a graded markdown report."""
import ast, sys, re
from pathlib import Path
from collections import Counter

IGNORE_DIRS = {'.git', 'node_modules', '__pycache__', '.venv', 'venv',
               'dist', 'build', '.idea', '.vscode'}
CODE_EXTS = {'.py', '.js', '.ts', '.jsx', '.tsx', '.java', '.go', '.rb',
             '.php', '.c', '.h', '.cpp', '.cc', '.cs', '.rs', '.kt', '.swift'}
TODO_RE = re.compile(r'\b(TODO|FIXME|HACK|XXX|BUG)\b')
LONG_LINE = 120        # chars per line
DEEP_INDENT = 6        # indent levels (1 level ~= 4 spaces)
LONG_FUNC_LINES = 50   # python functions longer than this
LONG_FILE_LINES = 500

LEGEND = {
    'long-function': '超长函数', 'many-params': '参数过多',
    'deep-nesting': '嵌套过深', 'long-file': '超大文件',
    'tech-debt': 'TODO/FIXME 债务', 'long-line': '超长行',
}

def walk(root):
    for p in Path(root).rglob('*'):
        if any(part in IGNORE_DIRS for part in p.parts):
            continue
        if p.is_file() and p.suffix in CODE_EXTS:
            yield p

def scan_file(path):
    issues, metrics = [], {'lines': 0, 'todos': 0, 'deepest': 0, 'long_lines': 0}
    try:
        text = path.read_text(encoding='utf-8', errors='replace')
    except OSError:                       # solve, don't punt: skip unreadable files
        return issues, None
    lines = text.splitlines()
    metrics['lines'] = len(lines)
    for i, line in enumerate(lines, 1):
        if TODO_RE.search(line):
            metrics['todos'] += 1
            issues.append((i, 'tech-debt', line.strip()[:80]))
        stripped = line.lstrip()
        levels = (len(line) - len(stripped)) // 4
        metrics['deepest'] = max(metrics['deepest'], levels)
        if levels >= DEEP_INDENT:
            issues.append((i, 'deep-nesting', f'nesting depth {levels}'))
        if len(line) > LONG_LINE:
            metrics['long_lines'] += 1
            issues.append((i, 'long-line', f'{len(line)} chars'))
    if metrics['lines'] > LONG_FILE_LINES:
        issues.append((metrics['lines'], 'long-file', f'{metrics["lines"]} lines'))
    if path.suffix == '.py':              # AST precision for Python
        try:
            tree = ast.parse(text)
        except SyntaxError:
            tree = None
        if tree:
            for node in ast.walk(tree):
                if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
                    length = getattr(node, 'end_lineno', node.lineno) - node.lineno + 1
                    if length > LONG_FUNC_LINES:
                        issues.append((node.lineno, 'long-function', f'{node.name}() = {length} lines'))
                    params = len(node.args.args) + len(node.args.kwonlyargs)
                    if params > 5:
                        issues.append((node.lineno, 'many-params', f'{node.name}() has {params} params'))
    return issues, metrics

def grade(density):                       # issues per 1000 lines, lower is better
    return 'A' if density < 5 else 'B' if density < 15 else \
           'C' if density < 30 else 'D' if density < 50 else 'F'

def main():
    root = Path(sys.argv[1] if len(sys.argv) > 1 else '.').resolve()
    all_issues, total_lines, per_file, type_counter = [], 0, [], Counter()
    for path in walk(root):
        issues, metrics = scan_file(path)
        if metrics is None:
            continue
        total_lines += metrics['lines']
        per_file.append((path, metrics, len(issues)))
        for _, typ, _ in issues:
            type_counter[typ] += 1
        all_issues.extend((path, ln, typ, det) for ln, typ, det in issues)
    density = len(all_issues) / total_lines * 1000 if total_lines else 0
    print('# 🩺 代码体检报告\n')
    print(f'**扫描目录**: `{root}`  ')
    print(f'**代码行数**: {total_lines:,}  **问题数**: {len(all_issues)}  '
          f'**密度**: {density:.1f}/千行  **评级**: **{grade(density)}**\n')
    print('## 问题分布\n| 类型 | 数量 |\n|------|------|')
    for t, n in type_counter.most_common():
        print(f'| {LEGEND.get(t, t)} | {n} |')
    print('\n## Top 重灾区（按问题数）\n| 文件 | 行数 | 问题数 |\n|------|------|--------|')
    for path, metrics, n in sorted(per_file, key=lambda x: -x[2])[:10]:
        if n:
            print(f'| {path.relative_to(root)} | {metrics["lines"]} | {n} |')
    print('\n## 具体问题清单（前 30 条）\n| 文件 | 行 | 类型 | 详情 |\n|------|----|------|------|')
    for path, ln, typ, det in sorted(all_issues, key=lambda x: x[1])[:30]:
        print(f'| {path.relative_to(root)} | {ln} | {LEGEND.get(typ, typ)} | {det} |')
    print(f'\n---\n_由 code-health-audit Skill 生成，共 {len(all_issues)} 条问题。_')

if __name__ == '__main__':
    main()

python3 ~/.claude/skills/code-health-audit/scripts/audit.py /path/to/your/repo

帮我看看这个模块的可维护性怎么样，有没有该重构的地方

/code-health-audit src/

def process_order(customer, items, coupon, shipping, tax_rate, warehouse, priority, note):
    # TODO: 这里的折扣逻辑太绕，等 Q3 重写
    total = 0
    for item in items:
        if item.get("qty", 0) > 0:
            if item.get("price", 0) > 0:
                if item.get("sku"):
                    if coupon and coupon.get("type") == "percent":
                        if priority == "vip":
                            total += item["price"] * item["qty"] * 0.8
                        else:
                            total += item["price"] * item["qty"] * 0.9
                    else:
                        total += item["price"] * item["qty"]
    # ... 此处省略后续 60 行未重构的结算、税费、出库逻辑 ...
    return total

python3 ~/.claude/skills/code-health-audit/scripts/audit.py ~/messy-demo

# 🩺 代码体检报告

**扫描目录**: `/home/you/messy-demo`
**代码行数**: 90  **问题数**: 4  **密度**: 44.4/千行  **评级**: **D**

## 问题分布
| 类型 | 数量 |
|------|------|
| 嵌套过深 | 1 |
| 参数过多 | 1 |
| 超长函数 | 1 |
| TODO/FIXME 债务 | 1 |

## 具体问题清单（前 30 条）
| 文件 | 行 | 类型 | 详情 |
|------|----|------|------|
| order.py | 2 | tech-debt | # TODO: 这里的折扣逻辑太绕，等 Q3 重写 |
| order.py | 10 | deep-nesting | nesting depth 5 |
| order.py | 1 | many-params | process_order() has 8 params |
| order.py | 1 | long-function | process_order() = 68 lines |

flowchart TD
    A["用户: 体检一下 src/"] --> B{"description 命中?"}
    B -->|是, 自动触发| C["加载 SKILL.md 全文入上下文"]
    B -->|否| I["用户手动: /code-health-audit src/"]
    I --> C
    C --> D["执行 python3 audit.py src/\n(allowed-tools 免确认)"]
    D --> E["脚本: AST + 行级指标扫描"]
    E --> F["输出 Markdown 体检报告"]
    F --> G["Claude 读取报告"]
    G --> H["汇总评级 + Top3 热点\n+ 每处一条 file:line 重构建议"]

flowchart LR
    subgraph S0["① 启动: 仅注入元数据"]
        M["所有 Skill 的 name + description\n进入系统提示"]
    end
    subgraph S1["② 触发: 按需加载正文"]
        SK["SKILL.md 全文\n(常驻本会话)"]
    end
    subgraph S2["③ 执行: 脚本不进上下文"]
        SC["scripts/audit.py 执行"]
        OUT["仅 stdout 输出进上下文"]
    end
    M -->|"description 命中"| SK --> SC --> OUT