1. 从重复提示词到可复用技能Agent Skills 要解决的真实问题如果你用大语言模型做过稍微复杂一点的事大概率经历过这样的循环每次开新对话都要把同一套背景、同一套规范、同一套输出格式重新贴一遍。写代码审查要贴一遍团队规范做数据清洗要贴一遍字段说明生成周报要贴一遍模板结构。贴到第十次的时候你会开始怀疑自己到底是在用 AI还是在给 AI 当人肉上下文搬运工。Agent Skills 就是冲着这个痛点来的。它原本是 Anthropic 团队内部使用 Claude 的一套方法后来随着官方发布相关博客逐渐成为一个跨平台可移植的开放标准和 MCP 一样属于扩展大语言模型能力的方式。各个厂商的 CLI 工具也陆续接入了这个概念。用一句话概括Agent Skills 是一种把「重复提示词 配套脚本 参考文档」打包成目录的机制模型在合适的场景下自动调用。每个技能就是一个目录目录里必须有一个SKILL.md文件还可以带脚本、模板、参考文档。模型先通过SKILL.md里的 name 和 description 判断要不要用这个技能确认使用后才读取完整内容。这个设计的关键在于「渐进式披露」。模型启动时只加载每个技能的元数据大约每个技能 100 个 token当请求匹配到某个技能描述时才加载SKILL.md主体通常不到 5k token至于目录里的脚本和资源按需通过 bash 执行内容根本不进上下文窗口。这样一来你装十个技能日常对话的上下文开销依然很小。适合谁三类人最该关注一是每天要跟模型重复交代同一套规则的后端/算法工程师二是想把团队规范沉淀成资产的技术负责人三是已经在用 Claude Code、Cursor 这类工具想让 Agent 更懂自己项目的人。这篇就按「目录结构 → 配置骨架 → 接入通道 → 加载验证 → 排错」的顺序把落地路径走一遍。2. TaoToken 前置统一 Key 与 API 通道的准备在写SKILL.md之前先把模型调用通道理顺。原因很实际技能里经常要调用模型做二次处理比如让模型读一段代码再按规范输出审查意见。如果每个技能各自维护一套 Key 和 endpoint后面维护会非常痛苦。用 TaoToken 做统一通道一个 Key 走所有模型调用技能里只引用环境变量迁移和换模型都省事。TaoToken 在这里的角色是统一的 API 接入层官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数直接用它作为 base_url 即可。你需要先拿到一个 API Key。进入控制台创建 Key 的入口在这里https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建完成后把 Key 存到环境变量里不要硬编码进SKILL.md或脚本。Key 管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 后续轮换、吊销都在这里操作。配置环境变量的方式Linux/macOS 下直接写进 shell 配置export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/apiWindows PowerShell 用$env:TAOTOKEN_API_KEYsk-你的key $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api这里有个容易踩的坑很多人把 base_url 写成带/v1的完整路径结果请求 404。TaoToken 的 base_url 就是https://taotoken.net/api具体路径由 SDK 或请求体决定。另外 Key 不要提交到 Git建议在项目根目录加.env并写进.gitignore。如果你还没决定用哪个模型可以先到模型对话页面试一下https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 确认通道通不通、返回是否正常再去写技能。这一步花两分钟能省掉后面一半的排错时间。3. 可复制配置SKILL.md 目录结构与配置骨架现在进入正题。一个标准的技能目录长这样我以一个「代码审查」技能为例code-review-skill/ ├── SKILL.md # 必需技能主文件 ├── CHECKLIST.md # 可选详细检查清单 ├── REFERENCE.md # 可选API/规范参考 └── scripts/ └── lint_check.py # 可选确定性脚本SKILL.md由两部分组成顶部的 YAML 前置数据frontmatter和下面的 Markdown 主体。前置数据里的 name 和 description 就是 Level 1 元数据模型启动时只读这部分。description 写得准不准直接决定技能会不会被正确触发。下面是一个可以直接复制的骨架--- name: code-review description: 按团队规范审查代码检查命名、错误处理、日志和边界条件。当用户提交代码片段、要求 review、或提及代码审查、规范检查时使用。 --- # 代码审查技能 ## 使用场景 当用户提供代码并要求审查或提到 review、规范、代码质量时按本技能执行。 ## 审查流程 1. 先通读代码识别语言和框架 2. 按 CHECKLIST.md 中的清单逐项检查 3. 对每个问题给出位置、问题、修改建议 4. 输出格式统一为 Markdown 表格 ## 输出格式 | 严重级别 | 位置 | 问题 | 建议 | |---------|------|------|------| ## 参考 详细检查项见 [CHECKLIST.md](CHECKLIST.md) 需要调用模型做二次判断时使用环境变量 TAOTOKEN_API_KEY 和 TAOTOKEN_BASE_URL。注意几个细节。第一description 里要包含用户可能自然说出的关键词比如「review」「代码审查」「规范检查」否则模型匹配不到。第二主体里引用其他文件用相对路径的 Markdown 链接模型会按需读取。第三脚本放在scripts/下在主体里说明「运行 scripts/lint_check.py 做静态检查」模型会通过 bash 执行脚本内容不进上下文。CHECKLIST.md可以写得更细# 代码审查检查清单 ## 命名 - 变量名是否表意清晰 - 函数名是否为动词开头 ## 错误处理 - 是否有未捕获的异常 - 错误信息是否包含上下文 ## 日志 - 关键路径是否有日志 - 日志级别是否合理scripts/lint_check.py做一个确定性的检查比如统计函数长度import ast import sys def check_file(path): with open(path, encodingutf-8) as f: tree ast.parse(f.read()) for node in ast.walk(tree): if isinstance(node, ast.FunctionDef): length node.end_lineno - node.lineno if length 50: print(f{node.name}: {length} 行建议拆分) if __name__ __main__: check_file(sys.argv[1])这个脚本的好处是模型不需要把整个文件读进上下文直接执行就能拿到结果确定性强、可重复。4. 验证请求一次技能加载与调用的完整动作配置写完了得验证它真的能被加载和调用。分两步走先验证模型通道再验证技能触发。第一步用 curl 确认 TaoToken 通道正常curl https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 回复 ok}] }返回里能看到choices[0].message.content就说明通道没问题。如果返回 401检查 Key 是否带上了Bearer前缀返回 404检查 base_url 是否多写了/v1。第二步把技能目录放到 Claude Code 的技能加载路径下。不同工具路径略有差异常见的是项目根目录的.claude/skills/或用户目录的~/.claude/skills/。放好后重启会话让模型重新扫描技能元数据。然后发一条能匹配 description 的请求比如帮我 review 一下这段代码 def f(x): return x/0预期行为是模型先识别到请求匹配code-review技能的 description弹出确认提示部分工具会显示「是否使用 code-review 技能」确认后模型读取完整SKILL.md按流程输出审查表格。如果技能里引用了CHECKLIST.md模型会再读一次该文件如果要求运行脚本模型会调用 bash 执行lint_check.py。验证成功的标志有三个一是确认提示出现说明元数据被正确加载二是输出格式符合SKILL.md里定义的表格结构说明主体被读取三是如果脚本被调用能看到脚本输出混在结果里。三个都满足技能就算真正跑通了。如果你更想先验证模型本身对技能描述的理解可以到模型对话页面手动贴入SKILL.md内容试一次https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 确认描述能引导出预期行为再放进技能目录。5. 本篇常见错排查SKILL.md 不触发、脚本不执行、Key 报错技能跑不起来九成是下面几类问题。我按出现频率排一下。技能完全不触发。最常见的原因是 description 写得太抽象。比如只写「帮助处理代码」模型根本不知道什么时候该用。解决办法是把用户会说的原话塞进去「当用户提交代码片段、要求 review、或提及代码审查时使用」。另一个原因是技能目录层级放错模型扫描不到。确认目录结构是skills/code-review/SKILL.md而不是skills/code-review.md。触发了但输出不符合预期。说明元数据匹配上了但主体没被正确读取。检查SKILL.md的 frontmatter 是否用---正确包裹YAML 缩进是否合法。YAML 对缩进敏感name和description必须顶格冒号后要有空格。另外主体里引用其他文件时路径要相对于SKILL.md所在目录写绝对路径模型读不到。脚本不执行。先确认脚本有可执行权限chmod x scripts/lint_check.py。再确认SKILL.md主体里明确写了「运行 scripts/xxx.py」如果只是把脚本放在目录里但没在指令中提及模型不会主动去跑。还有一点脚本依赖的第三方库要在运行环境里装好否则 bash 执行会报 ModuleNotFoundError。调用模型时报 401 或 403。检查环境变量是否在当前 shell 生效echo $TAOTOKEN_API_KEY看有没有值。如果是在 IDE 插件里跑插件可能不继承 shell 环境变量需要在插件配置里单独填。Key 失效或额度用尽也会返回 403到 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 确认 Key 状态。返回 404 或连接超时。404 基本都是 base_url 写错记住是https://taotoken.net/api不要加/v1。超时则检查网络出口是否稳定以及请求体里的 model 名称是否拼写正确模型名写错有时也会返回非预期错误码。技能之间互相干扰。如果装了很多技能description 关键词重叠模型可能选错。解决办法是让每个技能的 description 聚焦一个明确场景避免「通用助手」这类宽泛描述。互斥的上下文尽量拆到不同技能减少 token 浪费。排错时建议开一个最小复现只留一个技能、一条请求确认通了再逐步加复杂度。这样定位问题比一上来就全量调试快得多。6. 把技能沉淀成资产接入文档与长期编码路径技能跑通之后真正有价值的是持续迭代。官方给的建议里有一条特别实用站在模型的角度思考观察它在真实场景里怎么用你的技能注意有没有意料之外的路径或对某些上下文的过度依赖。我自己的做法是每次技能输出不理想时不急着改提示词而是先问一句「它为什么没按预期走」往往问题出在 description 的匹配精度上而不是主体指令不够详细。另一个经验是代码既可以作为可执行工具也可以作为文档。你要在SKILL.md里明确告诉模型某个脚本是「直接运行」还是「读入上下文作为参考」。这两者差别很大前者不消耗上下文后者会占用 token。确定性强的检查尽量写成脚本直接跑需要模型理解判断的才放进 Markdown。如果你打算把技能接入到自己的应用里而不是只在 CLI 里用接入文档在这里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的请求格式和参数说明。长期做编码类 Agent 的话可以考虑 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 配合技能目录使用能把「规范沉淀 模型调用」这条链路固定下来。最后说一个我踩过的坑一开始我把所有规则都塞进一个巨大的SKILL.md结果主体超过 8k token每次触发都吃掉大量上下文反而比手动贴提示词还慢。后来按「互斥上下文分离」的原则拆成三个技能每个主体控制在 2k token 以内触发准确率和响应速度都明显好转。技能不是越大越好拆得对才是关键。