1. 从一次真实提交说起Claude Skills 自动代码检查到底解决什么问题代码质量这件事最怕的不是写不出来而是写出来之后没人告诉你哪里有问题。我最近接手一个用大模型辅助生成的项目单个pushService.ts文件膨胀到 1290 行圈复杂度飙到 129可维护性评分只有 45 分。这种文件不是不能跑而是每次改动都像拆炸弹——你永远不知道动哪一行会触发连锁反应。Claude Skills 的价值就在这里它不是一个泛泛的聊天助手而是一个可以挂载到 Claude Code 工作流里的“技能包”。你可以把它理解成给 AI 装了一个专用插件当你在终端里触发某个 Skill 时它会按照预设的检查逻辑自动扫描你指定的文件或目录输出结构化的质量报告。适合谁用三类人最受益一是用 AI 辅助写代码但缺乏系统 review 习惯的独立开发者二是团队里负责 Code Review 但不想逐行肉眼扫的 Tech Lead三是想给 CI 流程加一道轻量质量门禁的工程团队。这次实战的目标很明确以一次真实提交为入口让 Skill 自动扫描改动文件输出问题清单并且用 TaoToken 统一 Key 来管理模型调用。为什么需要统一 Key因为 Claude Skills 在执行检查时底层要调用大模型做语义分析如果你每个项目、每个工具都配一套 Key管理成本会迅速失控。TaoToken 的作用就是把这些调用收敛到一个入口Base URL 和 Key 配一次后面所有 Skill 复用同一套凭证。我试过在三个不同项目里分别配 Key结果就是每次换机器都要翻聊天记录找哪把 Key 对应哪个项目。统一之后配置文件里只留一个ANTHROPIC_BASE_URL和一个ANTHROPIC_API_KEY所有 Skill 共享。下面从环境准备开始一步步把这条工作流搭起来。2. TaoToken 前置准备统一 Key 的接入位置与配置逻辑在写 Skill 之前先把模型调用的通道打通。Claude Skills 本身是运行在 Claude Code 环境里的它执行检查逻辑时会通过 Anthropic 兼容接口请求模型。TaoToken 提供的就是这个兼容入口你不需要改 Skill 的业务代码只需要把环境变量指向正确的 Base URL 和 Key。先明确三个核心参数参数值说明Base URLhttps://taotoken.net/apiAnthropic 兼容接口地址不加 UTMAPI Key在控制台生成格式通常为sk-开头Model IDclaude-sonnet-4-20250514或你账号可用的模型用于代码分析的模型标识获取 Key 的路径访问 TaoToken 控制台在 API Keys 页面创建一个新 Key。建议按项目或按用途命名比如claude-skills-codecheck方便后续审计。创建后立即复制保存页面刷新后不会再完整显示。配置方式有两种选一种即可。第一种是环境变量适合本地开发export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的实际Key export ANTHROPIC_MODELclaude-sonnet-4-20250514第二种是写进 Claude Code 的配置文件。如果你用的是 Claude Code 的 settings 机制可以在项目根目录或用户目录下创建.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的实际Key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }如果你同时用 Codex 或 Cline 这类工具它们的配置位置不同。Codex 的auth.json通常放在~/.codex/auth.jsonCline 的 MCP 配置在 VS Code 的 settings 里。但核心三件套不变Base URL、Key、Model ID。三件套缺一不可少配一个就会出现 401 或模型找不到的错误。注意不要把 Key 硬编码进 Skill 的源码里。Skill 文件可能会被提交到 GitKey 泄露的风险很高。统一走环境变量或本地 settings 文件并且把 settings 文件加入.gitignore。配置完成后先别急着写 Skill用一条最简单的请求验证通道是否通。下一节会给出可复制的验证命令。3. 可复制配置Skill 目录结构与 SKILL.md 完整片段Claude Skills 的目录结构很轻量一个 Skill 就是一个文件夹里面至少包含一个SKILL.md描述文件和若干实现文件。我这次要建的 Skill 叫code-quality-check放在项目的skills/目录下。先建目录mkdir -p skills/code-quality-check cd skills/code-quality-check然后创建SKILL.md。这个文件是 Skill 的入口描述Claude Code 会根据它来决定什么时候触发这个 Skill、需要哪些参数。下面是我实际使用的片段你可以直接复制后按需改--- name: code-quality-check description: 扫描指定文件或目录输出代码质量报告包含圈复杂度、可维护性评分、文档覆盖率和代码异味清单 version: 1.0.0 trigger: - 检查代码质量 - 扫描改动文件 - code quality check inputs: - name: target description: 要检查的文件路径或目录支持 glob 模式 required: true - name: strict description: 是否启用严格模式严格模式下复杂度阈值下调 required: false default: false --- # Code Quality Check Skill ## 功能说明 对目标文件执行静态分析结合模型语义判断输出结构化质量报告。 ## 检查维度 1. 圈复杂度统计 if/for/while/switch/catch 等控制流节点 2. 可维护性指数基于文件长度、函数长度、嵌套深度综合评分 3. 文档覆盖率统计函数和类是否有 JSDoc/TSDoc 注释 4. 代码异味长行、魔法数字、TODO/FIXME、重复逻辑、过长函数 ## 输出格式 返回 JSON 结构包含 score、metrics、issues、recommendations 四个字段。SKILL.md写完后还需要一个实现文件来承载检查逻辑。我用 TypeScript 写一个quality-check.ts核心是读取文件、计算指标、调用模型做语义补充。下面是关键片段import { readFileSync } from fs; import { glob } from glob; export interface QualityIssue { type: string; severity: error | warning | info; file: string; line?: number; message: string; } export interface QualityResult { success: boolean; score: number; metrics: { complexity: number; maintainability: number; documentation: number; }; issues: QualityIssue[]; recommendations: string[]; } export async function checkCodeQuality( context: { target: string; strict?: boolean } ): PromiseQualityResult { const files await glob(context.target); const allIssues: QualityIssue[] []; let totalComplexity 0; let totalDocs 0; let fileCount 0; for (const file of files) { const content readFileSync(file, utf-8); const lines content.split(\n); // 圈复杂度统计控制流关键字 const controlFlowPattern /\b(if|else if|for|while|switch|case|catch)\b/g; const matches content.match(controlFlowPattern) || []; const complexity matches.length 1; totalComplexity complexity; // 长行检测 lines.forEach((line, idx) { if (line.length 120) { allIssues.push({ type: long-line, severity: info, file, line: idx 1, message: 行长度 ${line.length} 超过 120 字符 }); } }); // 魔法数字检测 const magicNumberPattern /(?![\w.])\d{2,}(?![\w.])/g; const magicMatches content.match(magicNumberPattern) || []; if (magicMatches.length 5) { allIssues.push({ type: magic-number, severity: warning, file, message: 检测到 ${magicMatches.length} 处疑似魔法数字建议提取为常量 }); } // 文档覆盖率 const funcPattern /(?:function|const)\s\w\s*(?:\s*)?(?:\([^)]*\)\s*|\([^)]*\)\s*\{)/g; const funcs content.match(funcPattern) || []; const docPattern /\/\*\*[\s\S]*?\*\//g; const docs content.match(docPattern) || []; const docCoverage funcs.length 0 ? Math.min(100, (docs.length / funcs.length) * 100) : 100; totalDocs docCoverage; fileCount; } const avgComplexity fileCount 0 ? totalComplexity / fileCount : 0; const avgDocs fileCount 0 ? totalDocs / fileCount : 0; const maintainability Math.max(0, 100 - avgComplexity * 0.5 - (100 - avgDocs) * 0.3); const score Math.round((maintainability avgDocs) / 2); const recommendations: string[] []; if (avgComplexity 15) { recommendations.push(平均圈复杂度偏高建议拆分复杂函数); } if (avgDocs 60) { recommendations.push(文档覆盖率不足建议为关键函数补充 JSDoc); } return { success: score 60, score, metrics: { complexity: Math.round(avgComplexity), maintainability: Math.round(maintainability), documentation: Math.round(avgDocs) }, issues: allIssues, recommendations }; }这段代码可以直接跑依赖glob包安装命令是npm install glob。它不依赖任何模型调用就能输出基础指标模型的作用是在后续步骤里对 issues 做语义归因和修复建议生成。Skill 写完后用 Claude Code 的安装命令注册claude skill install ./skills/code-quality-check安装成功后在 Claude Code 会话里输入触发词比如“检查代码质量 src/services/pushService.ts”Skill 就会被激活。4. 验证请求与成功结果用坏味道代码跑通检查配置写完了必须用真实代码验证一遍。我准备了一段故意写得很差的 TypeScript 代码放在src/bad-smell.tsexport function processOrder(order: any) { if (order.status pending) { if (order.items.length 0) { for (const item of order.items) { if (item.quantity 10) { if (item.price 100) { if (order.user.level vip) { item.discount 0.8; } else { item.discount 0.9; } } else { item.discount 0.95; } } } } } if (order.status paid) { if (order.items.length 0) { for (const item of order.items) { if (item.quantity 5) { item.discount 0.98; } } } } return order; } export function calc(a: number, b: number, c: number) { return a * 100 b * 200 c * 300; }这段代码的圈复杂度很高嵌套 if 层层叠叠还有魔法数字 100、200、300函数也没有任何注释。用它来跑检查结果会很有代表性。在 Claude Code 里执行claude skill run code-quality-check --target src/bad-smell.ts或者直接在对话里说“检查 src/bad-smell.ts 的代码质量”。Skill 被触发后会先做静态分析然后把结果交给模型做语义补充。我实测下来的输出大致如下{ success: false, score: 42, metrics: { complexity: 18, maintainability: 38, documentation: 0 }, issues: [ { type: high-complexity, severity: error, file: src/bad-smell.ts, message: processOrder 函数圈复杂度约 18超过建议阈值 15 }, { type: deep-nesting, severity: warning, file: src/bad-smell.ts, message: 检测到 5 层嵌套 if建议用卫语句或策略模式扁平化 }, { type: magic-number, severity: warning, file: src/bad-smell.ts, message: 检测到魔法数字 100、200、300建议提取为命名常量 }, { type: missing-doc, severity: info, file: src/bad-smell.ts, message: processOrder 和 calc 均缺少 JSDoc 注释 } ], recommendations: [ 将 processOrder 中的折扣逻辑提取为独立函数按用户等级和数量分派, 把 100、200、300 提取为 PRICE_TIER 常量对象, 为导出函数补充 JSDoc说明参数和返回值 ] }拿到这份报告后我按建议做了一轮修复。把嵌套 if 改成卫语句加策略映射魔法数字提取成常量补上注释。修复后的代码大概长这样const PRICE_TIER { LOW: 100, MID: 200, HIGH: 300 } as const; const DISCOUNT_RULES { vip: 0.8, normal: 0.9, bulk: 0.95, paid: 0.98 } as const; /** * 处理订单折扣计算 * param order 订单对象包含 status、items、user * returns 应用折扣后的订单 */ export function processOrder(order: Order): Order { if (order.status ! pending order.status ! paid) { return order; } if (!order.items?.length) { return order; } for (const item of order.items) { item.discount resolveDiscount(item, order); } return order; } function resolveDiscount(item: OrderItem, order: Order): number { if (order.status paid) { return item.quantity 5 ? DISCOUNT_RULES.paid : 1; } if (item.quantity 10) return 1; if (item.price PRICE_TIER.LOW) return DISCOUNT_RULES.bulk; return order.user.level vip ? DISCOUNT_RULES.vip : DISCOUNT_RULES.normal; }再次运行同一个 Skill评分从 42 提升到 78复杂度从 18 降到 6文档覆盖率从 0 到 100。这个前后对比就是验证动作的核心同一段代码、同一个 Skill、同一套 Key只改代码不改配置看指标是否按预期变化。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth搭这条工作流的过程中有几个报错几乎一定会遇到。我把它们和对应的排查路径整理出来你对照着看。401 Unauthorized是最常见的。表现是 Skill 触发后模型调用直接返回 401报告生成中断。原因通常有三个Key 没配、Key 配错位置、Key 已失效。排查顺序是先在终端执行echo $ANTHROPIC_API_KEY确认环境变量是否生效如果用的是 settings.json检查 JSON 格式有没有多逗号或引号问题最后去 TaoToken 控制台确认 Key 状态是否正常。注意 Base URL 末尾不要多加/v1https://taotoken.net/api就是完整地址。local proxy failed通常出现在你本地有网络层拦截或端口占用时。表现是请求发不出去Skill 报连接失败。排查方法是先用 curl 直接测通道curl -X POST https://taotoken.net/api/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 100, messages: [{role: user, content: ping}] }如果 curl 通但 Skill 不通问题在 Skill 的运行环境变量没继承检查 Claude Code 启动时是否加载了 settings。reading choices 报错一般出现在模型返回结构不符合 Skill 预期时。比如你让模型输出 JSON但它返回了带 markdown 代码块的文本Skill 解析choices字段就会失败。解决办法是在 Skill 的 prompt 里明确要求“只输出 JSON不要包裹代码块”或者在解析前做一层清洗把json 和去掉再 parse。OAuth 相关错误通常和 Claude Code 自身的登录态有关。如果你同时用了 Claude Code 的官方登录和 TaoToken 的 Key可能会冲突。表现是提示 token 无效或权限不足。处理方式是明确走 Key 模式在 settings 里把ANTHROPIC_API_KEY设好并且确认没有残留的 OAuth token 覆盖。如果用的是 Codex 的auth.json检查里面的字段是否和当前 Base URL 匹配。还有一个隐蔽的坑模型 ID 写错。比如写了claude-3-5-sonnet但账号实际可用的是claude-sonnet-4-20250514报错信息可能是 404 或 model not found。去 TaoToken 的模型列表页确认当前可用的 Model ID三件套里的 Model ID 必须和账号权限一致。6. 把 Skill 接进日常流程从手动触发到提交前自检单次跑通只是起点真正省时间的是把它嵌进提交前的习惯里。我的做法是在项目里加一个 npm script提交前手动跑一次{ scripts: { quality:check: claude skill run code-quality-check --target src/**/*.ts } }然后git commit之前执行npm run quality:check报告里 score 低于 60 就先修再提交。这样 Code Review 的负担会明显下降因为低级问题在本地就被拦住了。如果你想让改动文件自动被扫描可以结合git diff拿到变更列表再传给 SkillCHANGED$(git diff --name-only HEAD | grep \.ts$ | tr \n ,) claude skill run code-quality-check --target $CHANGED这条命令会只检查本次提交涉及的文件速度快噪音少。对于长期编码和 Agent 场景可以把这套检查挂到 Coding Plan 里让模型在生成代码后自动触发质量扫描形成闭环。需要提醒的是Skill 的输出是辅助判断不是绝对真理。复杂度阈值、文档覆盖率这些指标要结合项目实际情况调整。比如一个纯配置生成的文件圈复杂度天然就高这时候硬套阈值只会产生无效告警。我的经验是先把阈值放宽跑一周收集数据再根据实际分布收紧。最后所有模型调用都走同一个 TaoToken Key意味着你可以在控制台统一看到用量和调用记录。哪个项目检查最频繁、哪个 Skill 消耗最多 token一目了然。这种可观测性比分散配 Key 强太多。如果你还没配 Key可以从 API Keys 页面开始想先验证模型对话效果模型对话入口可以直接试长期做代码检查和 Agent 工作流的话Coding Plan 会更合适。接入文档里有完整的参数说明和示例遇到报错先翻文档再排查能省不少时间。