1. 为什么我把 code-review 从提示词搬进了 SKILL.md如果你也在用 Claude Code、Cursor 或者自建的 Agent 做代码审查大概率经历过这个阶段每次审查都要把「命名规范、安全要求、性能红线」重新贴一遍贴完还要担心上下文被吃掉一半。更麻烦的是团队里每个人的提示词都不一样A 审出来说变量名要 camelCaseB 审出来说无所谓最后代码没统一审查意见先打起来了。我试过把规范塞进一个超长 prompt结果就是每次调用都在烧 token而且模型经常「选择性失忆」明明写了禁止v-html它还是给你放过。后来我把这套东西拆成了 skill 结构一个SKILL.md当契约入口reference/放具体规范scripts/放可执行校验再通过 TaoToken 的统一 Key 通道去调模型。这样做的直接好处是——元信息常驻、指令按需加载、资源只在触发时读取token 消耗肉眼可见地降下来审查标准也终于能版本化管理了。这篇就按「能直接抄去用」的标准来写先给SKILL.md骨架再给目录结构和配置片段最后用 TaoToken 的 API 通道跑一次真实的 code-review 验证。适合已经在用 Agent 做研发提效、但被提示词维护折磨过的同学。2. TaoToken 前置把 Key 和通道先理顺skill 本身是「能力描述」它不负责网络请求。真正去调模型的那一步需要一个稳定的 API 入口。我这边统一走 TaoToken 的通道原因是它把 Key 管理和模型调用收敛到一个地方skill 里只写「调用哪个模型、传什么参数」不用关心底层换没换供应商。你需要先拿到一个可用的 API Key。操作路径是登录后进控制台在 API Keys 页面创建一个新 Key复制出来存到环境变量里别硬编码进SKILL.md——这一点和前端规范里「禁止硬编码 Secret」是同一个道理。export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api注意SKILL.md里只描述「需要调用模型完成审查」具体的 Key 和 base_url 通过环境变量注入。这样 skill 可以进 Git 仓库Key 不会泄露。如果你还没建 Key直接去控制台的 API Keys 页面操作即可接入细节和参数说明在接入文档里有完整字段表。这两个入口分别是API Keys 管理https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite模型对话调试页可以用来先手动验证一次请求通不通地址是 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。我习惯先在对话页发一条「你好」确认 Key 有效再去跑脚本能省掉一半排障时间。3. 可复制配置SKILL.md 骨架与目录结构3.1 目录长什么样skill 采用三层元信息常驻、指令按需、资源按需。落到文件系统上就是下面这样skills/ └── code-review/ ├── SKILL.md ├── reference/ │ ├── python-code.md │ ├── go-code.md │ ├── 前端代码.md │ ├── security.md │ ├── performance.md │ └── default-code.md └── scripts/ └── check_naming.pySKILL.md是入口调度器本身不写具体规范只写「什么语言加载哪个文件、什么维度叠加哪个文件」。reference/放规范正文scripts/放可执行校验脚本。这样模型每次只读它真正需要的那一份而不是把六份规范全塞进上下文。3.2 SKILL.md 骨架下面这份可以直接改改就用重点是 frontmatter 里的name和description——这两个字段是常驻加载的描述写清楚模型才知道什么时候该触发它。--- name: code-review description: 代码审查调度器。根据代码语言和审查维度自动加载 reference/ 下对应规范文件作为审查依据 version: 1.0.0 tags: [code-review, dispatcher, reference-loader] --- # 代码审查调度器 本文件是审查任务的入口不包含具体标准只负责按规则加载 reference/ 下的规范文件。 ## 规范文件映射 ### 按语言加载基础规范 | 代码语言 | 规范文件 | 路径 | |----------|----------|------| | Python | Python 代码规范 | reference/python-code.md | | Go | Go 代码规范 | reference/go-code.md | | JavaScript / TypeScript | 前端代码规范 | reference/前端代码.md | | Java | Java 代码规范 | reference/java-code.md | ### 按维度叠加专项规范 | 审查维度 | 规范文件 | 路径 | |----------|----------|------| | 安全 | 安全编码规范 | reference/security.md | | 性能 | 性能优化规范 | reference/performance.md | | 测试 | 单元测试规范 | reference/testing.md | ## 执行逻辑 1. 识别输入代码的语言 2. 匹配基础规范文件并加载 3. 若指定 focus_areas叠加加载对应专项规范 4. 以加载到的规范内容作为唯一审查依据 5. 输出报告并在 reference 字段标注已加载的文件路径 ## 注意事项 - 语言未命中映射表时加载 reference/default-code.md 兜底 - 未指定审查维度时只加载基础规范 - 规范文件加载失败要明确告知不能静默跳过3.3 reference 规范片段reference/前端代码.md里放的就是可执行的条款比如命名和 XSS 这两块写具体一点模型才好判# 前端代码规范 适用语言JavaScript / TypeScript / Vue / React ## 1. 命名规范 - 变量、函数用 camelCase如 userName、fetchData - 常量用 UPPER_SNAKE_CASE如 MAX_RETRY_COUNT - 布尔值以 is / has / can / should 开头 - 组件名用 PascalCase文件名与组件名一致 ## 2. 安全规范 - 禁止用 v-html / dangerouslySetInnerHTML 渲染用户输入 - 必须使用时先经 DOMPurify 过滤 - 禁止在前端硬编码 API Key、Token、Secret - 敏感信息通过环境变量注入以 VITE_ / REACT_APP_ 前缀标识3.4 scripts 校验脚本scripts/check_naming.py做一件很窄的事扫一遍目标文件把不符合 camelCase 的变量名挑出来。它不替代模型审查而是把「机械可判定」的部分先跑掉减少模型误判。import re import sys CAMEL re.compile(r^[a-z][a-zA-Z0-9]*$) SNAKE_CONST re.compile(r^[A-Z][A-Z0-9_]*$) def check(path): bad [] with open(path, encodingutf-8) as f: for i, line in enumerate(f, 1): m re.match(r\s*(?:let|const|var)\s([A-Za-z_][A-Za-z0-9_]*), line) if not m: continue name m.group(1) if name.isupper(): if not SNAKE_CONST.match(name): bad.append((i, name, 常量应为 UPPER_SNAKE_CASE)) elif not CAMEL.match(name): bad.append((i, name, 变量应为 camelCase)) return bad if __name__ __main__: for path in sys.argv[1:]: for line, name, msg in check(path): print(f{path}:{line} {name} - {msg})跑起来是这样python scripts/check_naming.py src/utils/format.js输出会直接告诉你第几行的哪个变量名不合规模型拿到这份结果后只需要负责「语义层面」的判断比如这个函数该不该拆、这个副作用有没有清理。4. 验证请求用 TaoToken 通道跑一次真实审查配置齐了接下来验证整条链路。我用 Python 写一个最小调用把SKILL.md的调度逻辑和 TaoToken 的 API 串起来。核心思路是先根据语言读对应的 reference 文件拼进 system 消息再让模型按规范审代码。import os import requests API_KEY os.environ[TAOTOKEN_API_KEY] BASE_URL os.environ[TAOTOKEN_BASE_URL] def load_reference(lang): mapping { python: reference/python-code.md, javascript: reference/前端代码.md, typescript: reference/前端代码.md, } path mapping.get(lang, reference/default-code.md) with open(path, encodingutf-8) as f: return path, f.read() def review(code, langjavascript, focusNone): ref_path, ref_text load_reference(lang) if focus security: with open(reference/security.md, encodingutf-8) as f: ref_text \n\n f.read() ref_path reference/security.md system f你是代码审查器。以下规范是唯一审查依据\n\n{ref_text} payload { model: claude-sonnet-4-20250514, messages: [ {role: system, content: system}, {role: user, content: f审查以下代码\n\n{code}}, ], } resp requests.post( f{BASE_URL}/v1/chat/completions, headers{Authorization: fBearer {API_KEY}}, jsonpayload, timeout60, ) resp.raise_for_status() data resp.json() print(已加载规范:, ref_path) print(data[choices][0][message][content]) if __name__ __main__: sample const UserName admin; const max_retry 3; function FetchData() { return fetch(/api/user).then(r r.json()); } review(sample, langjavascript, focussecurity)跑之前确认环境变量已经导出然后执行python review.py实测下来输出会先打印「已加载规范: reference/前端代码.md reference/security.md」然后给出审查意见比如UserName应为 camelCase、max_retry常量应大写、FetchData函数名首字母不该大写、.then()嵌套应改async/await。这些判断全部来自 reference 文件而不是模型自由发挥所以团队里谁跑结果都一致。如果你更想先手动确认模型和 Key 没问题可以打开模型对话页发一条测试消息确认返回正常再跑脚本。长期做编码和 Agent 任务的话Coding Plan 那条通道更适合高频调用地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。5. 本篇常见错排查5.1 规范文件加载失败模型却「假装审了」最常见的就是路径写错。SKILL.md里写的是reference/前端代码.md但实际文件名是前端规范.md模型读不到文件又不会主动报错就凭自己的常识审了一遍。表现是审查意见和你的规范对不上。排查方法在脚本里加一行print(ref_path)确认打印出来的路径真实存在。规范里那句「加载失败要明确告知不能静默跳过」就是防这个的。5.2 401 / 403Key 没生效先确认TAOTOKEN_API_KEY真的导出了echo $TAOTOKEN_API_KEY能看到值。如果是在 IDE 里跑注意 IDE 的终端可能没继承你 shell 里的环境变量重启一下终端或者写进项目.env再加载。另外检查请求头是不是Authorization: Bearer sk-xxx少个空格都会 401。5.3 模型没触发 skilldescription写得太泛比如只写「代码审查」模型不知道什么时候该用。把它写成「根据代码语言和审查维度自动加载 reference/ 下对应规范文件作为审查依据」触发意图就明确了。frontmatter 里的tags也建议带上code-review、dispatcher这类关键词。5.4 token 还是很高检查是不是把整个reference/目录都读进去了。正确做法是按语言只读一份基础规范专项规范按focus_areas叠加。如果一次审查把六份规范全塞进 systemtoken 自然下不来。另外scripts/的输出要精简只回传不合规的行别把整个文件内容再喂一遍。5.5 脚本和模型结论打架check_naming.py说没问题模型说变量名不合规通常是脚本的正则太窄漏掉了const { a, b } obj这种解构赋值。脚本负责机械判定模型负责语义判断两者定位不同不要指望脚本覆盖全部规则。遇到分歧以 reference 条款为准回头补脚本的正则。6. 把 skill 接进你的日常流程这套结构跑通之后我把它接进了提交前的检查环节git diff拿到改动文件按扩展名判断语言调review()出报告scripts/的结果作为附注一起贴到 PR 评论里。整个过程不需要人再复制粘贴规范审查标准跟着仓库走谁改规范谁提 PR版本可追溯。如果你要长期跑这类编码和 Agent 任务建议把 Key 和通道固定下来用 Coding Plan 那条线做高频调用会更省心https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。接入过程中遇到字段或鉴权问题直接翻接入文档对照https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。Key 的创建和轮换在 API Keys 页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。最后留一个我踩过的坑reference/里的规范文件别写太长单份控制在 200 行以内条款要能判定「是/否」。写成一整篇散文模型反而抓不住重点审查意见会变得模棱两可。规范是给机器执行的契约不是给人读的文档这一点想清楚skill 的复用价值才真正出来。
