Claude Code Skills 开发实战：从零造一个「代码异味扫描」Skill

.claude/skills/code-smell-scanner/
├── SKILL.md              # 入口，必填
├── references/
│   └── smell-catalog.md  # 异味详表（渐进披露第二层）
├── scripts/
│   └── scanner.py        # 自动扫描器（脚本层）
└── evals/
    └── cases.md          # 验证用例

---
name: code-smell-scanner
description: Reviews a single source file for code smells — long functions, deep nesting, overlong lines, excessive parameters, oversized files, and leftover TODO/FIXME comments. Use when the user asks to "check code quality", "find smells", "review this file for maintainability", or before submitting a large PR. Returns located findings with line numbers and concrete refactor suggestions; does not modify code.
---

# Code Smell Scanner

You are a maintainability reviewer. You **diagnose, never auto-edit**.

## Workflow

1. Ask the user for the target file (or infer from context). If a directory is given, ask whether to recurse.
2. Run the bundled scanner to get a deterministic baseline:
   `python3 scripts/scanner.py <file>`
3. Read the scanner output, then **augment** it with your own semantic judgement (the scanner only catches syntactic smells; you catch design smells like duplicated logic, misleading names).
4. For each finding, cite the line number and give ONE concrete suggestion.
5. Summarize severity at the end: 🔴 must-fix / 🟡 should-fix / 🟢 nit.

## The 6 smells we track

- **Long function** > 50 lines
- **Deep nesting** > 4 levels of indentation
- **Overlong line** > 120 chars
- **Too many parameters** > 4
- **Oversized file** > 400 lines
- **Leftover markers** TODO / FIXME / XXX

Full definitions and edge cases live in `references/smell-catalog.md` — read it only when a finding needs nuance.

## Output format

Always use this table so output is machine-parseable:

| Severity | Smell | Location | Suggestion |
|---|---|---|---|
| 🔴 | Long function | auth.py:login (88 lines) | extract validateCredentials() |

Do NOT reformat, do NOT add preamble. End with a one-line total: `Total: 3 🔴 / 5 🟡 / 2 🟢`.

# Smell Catalog — Detailed Definitions

## Long function (> 50 lines)
Count blank lines and comments as part of the body. **Exception**: long `switch`/`match`
statements with simple arms are acceptable — flag them as 🟢 only.

## Deep nesting (> 4 levels)
Indentation level is counted from the function's own scope. A method inside a class
inside a function starts at level 2 before any control flow.

## Too many parameters (> 4)
Options object / builder pattern collapses multiple params into one. Flag the *effective*
param count, not the literal count.

#!/usr/bin/env python3
"""Deterministic code-smell baseline scanner. Language-agnostic-ish."""
import sys, re

THRESHOLDS = {"long_func": 50, "deep_nest": 4, "long_line": 120,
              "max_params": 4, "max_file_lines": 400}

def scan(path):
    findings = []
    lines = open(path, encoding="utf-8", errors="ignore").read().splitlines()
    if len(lines) > THRESHOLDS["max_file_lines"]:
        findings.append(("🟡", "Oversized file", f"{path} ({len(lines)} lines)",
                         "split into focused modules"))
    # overlong lines + leftover markers
    for i, ln in enumerate(lines, 1):
        if len(ln) > THRESHOLDS["long_line"]:
            findings.append(("🟢", "Overlong line", f"{path}:{i} ({len(ln)} chars)",
                             "wrap or extract"))
        if re.search(r"\b(TODO|FIXME|XXX)\b", ln):
            findings.append(("🟡", "Leftover marker", f"{path}:{i}",
                             "resolve or track in issue tracker"))
    # long functions + deep nesting + params (brace-based heuristic)
    depth = 0; func_start = None; func_name = None; params = 0
    for i, ln in enumerate(lines, 1):
        m = re.search(r"def\s+(\w+)\s*\(([^)]*)\)", ln)
        if m:
            func_name, args = m.group(1), m.group(2)
            params = len([a for a in args.split(",") if a.strip()])
            if params > THRESHOLDS["max_params"]:
                findings.append(("🟡", "Too many params",
                                 f"{path}:{func_name} ({params})",
                                 "introduce options object"))
            func_start = i
        prev_depth = depth
        depth += ln.count("{") - ln.count("}")
        if depth > THRESHOLDS["deep_nest"]:
            findings.append(("🟡", "Deep nesting", f"{path}:{i} (level {depth})",
                             "extract early-return guard"))
        if prev_depth > 0 and depth == 0 and func_start:
            if i - func_start > THRESHOLDS["long_func"]:
                findings.append(("🔴", "Long function",
                                 f"{path}:{func_name} ({i-func_start} lines)",
                                 "extract helper(s)"))
            func_start = None
    return findings

if __name__ == "__main__":
    for sev, smell, loc, sug in scan(sys.argv[1]):
        print(f"{sev} | {smell} | {loc} | {sug}")

🔴 | Long function | auth.py:login (88 lines) | extract helper(s)
🟡 | Deep nesting | auth.py:42 (level 5) | extract early-return guard
🟡 | Leftover marker | auth.py:67 | resolve or track in issue tracker

description: Helps improve code quality.

flowchart TD
    A[用户输入] --> B{Claude 语义匹配}
    B -->|不相关| Z[不加载 Skill]
    B -->|匹配 description| C[载入 SKILL.md 第一层]
    C --> D[执行工作流]
    D --> E[运行 scripts/scanner.py]
    E --> F[确定性基线:行数/嵌套/参数]
    D --> G[模型语义补充:重复/命名/设计]
    F --> H{需要细节?}
    H -->|是| I[读取 references 第二层]
    H -->|否| J[合并发现]
    I --> J
    G --> J
    J --> K[输出表格+严重度总结]
    K --> L[/eval 持续验证触发精度/]