Agent Skills 标准实战：用 SKILL.md 让 AI Agent 真正学会干活

1. 为什么你的 AI Agent 总是“会聊不会干”很多人第一次用 AI Agent 做自动化都会经历一个相似的落差对话里它讲得头头是道真让它按步骤把活干完就开始掉链子。你让它审查一段代码、生成一份符合团队规范的文档、或者走一遍报销审批流程它要么漏步骤要么把工具调用顺序搞反最后还得你手动收尾。问题往往不在模型本身而在于你每次都在用“一次性提示词”教它做事——这次教完下次对话又得从头再来。Agent Skills 这套开放规范想解决的正是这件事。简单说它把“完成某件事的完整经验”打包成一个可复用、可版本控制、可分享的文件夹核心是一份 SKILL.md。AI Agent 加载它就像手机装了个 App不用反复教就能按既定流程干活。它和 MCP 不是替代关系MCP 解决“AI 能调用哪些工具”Agent Skills 解决“AI 怎么把这些工具串起来完整做好一件事”。适合谁需要让 Agent 稳定执行多步任务的开发者尤其是团队里想把工作流沉淀下来、而不是散落在聊天记录里的人。我试过把一套代码审查流程从提示词改写成 Skill最直观的变化是以前每次要贴 300 字要求现在 Agent 自己判断该不该触发、该走哪几步。下面从目录结构讲到调用侧配置再演示一次从技能声明到任务执行的完整验证。2. TaoToken 前置统一 Key 与 API 通道在写 SKILL.md 之前先把调用侧的事情理清楚。Agent 执行技能时最终还是要落到模型 API 上。如果你同时用多个模型、多个工具Key 和 Base URL 散在各处排查问题会非常痛苦。我的做法是用 TaoToken 统一 Key 和 API 通道这样 Skill 里声明的模型调用、MCP 工具调用都走同一个入口出问题只看一个地方。TaoToken 的定位是统一的模型调用通道官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。你需要先在控制台创建一个 API Key然后把它配置到你的 Agent 运行环境里。注意这里说的是调用侧配置不是让你改编辑器——Skill 本身是纯文本规范跟具体 IDE 无关。具体要准备三样东西我把它叫“三件套”后面配置里会反复出现配置项值说明Base URLhttps://taotoken.net/api所有模型请求的统一入口API Key控制台生成建议用环境变量注入别硬编码Model ID按需选择在模型对话页确认可用模型名如果你用的是 Claude Code 这类工具配置通常写在 settings 文件里如果是 Cline 或带 MCP 的客户端则写在对应的 MCP 配置里。不管哪种Base URL、Key、Model ID 这三件套都要写全缺一个就会在请求阶段报错。我踩过的坑是只填了 Key 没改 Base URL结果请求打到了默认地址一直超时排查了半天才发现是入口没换。拿到 Key 之后建议先做一次最小验证确认通道是通的再去写 Skill。验证方式很简单用 curl 发一个对话请求即可下一节会给完整命令。这一步别跳过否则后面 Skill 报错时你分不清是 Skill 写错了还是通道没通。3. 可复制配置SKILL.md 目录结构与字段Agent Skills 的目录结构非常固定照着建不会错。一个 Skill 就是一个文件夹必需文件只有 SKILL.md其余都是可选的my-skill/ ├── SKILL.md # 必需YAML 元数据 Markdown 指令 ├── scripts/ # 可选可执行脚本Python/Bash/Node 都行 ├── references/ # 可选参考文档按需加载 └── assets/ # 可选模板、图片、配置文件SKILL.md 分两部分YAML 元数据frontmatter和 Markdown 正文。两个字段是必需的少一个就加载不出来。name 要求 1-64 个字符只能用小写字母、数字和连字符而且必须和文件夹名完全一致description 要求 1-1024 个字符既要说明能做什么也要说清什么时候用最好带上触发关键词。下面是一份可直接复制的 SKILL.md用于代码审查场景--- name: code-review description: 对代码变更进行结构化审查。当用户请求审查代码、检查 PR、或提到 review 时使用。 license: MIT compatibility: 需要 Python 3.8 metadata: author: dev-team version: 1.0.0 --- # 代码审查技能 ## 工作流程 1. 收集待审查的代码变更确认文件范围和改动内容 2. 调用 scripts/check_style.py 做基础风格检查 3. 按 references/review-checklist.md 逐项核对逻辑与边界 4. 输出结构化审查意见标注严重级别 ## 异常处理 - 如果变更涉及数据库迁移提醒补充回滚方案 - 如果缺少测试用例直接提示补充如果你用的是带 MCP 的客户端配置里要把三件套写全。以常见的 MCP 配置为例{ mcpServers: { taotoken: { url: https://taotoken.net/api, headers: { Authorization: Bearer ${TAOTOKEN_API_KEY} }, env: { MODEL_ID: your-model-id } } } }注意 Base URL 用的是 https://taotoken.net/api Key 通过环境变量注入Model ID 按你在模型对话页确认的填。这样 Skill 在执行脚本、调用工具时都走同一条通道。渐进式披露是这套规范很贴心的设计Agent 启动时只加载 name 和 description约 100 tokens匹配任务后才加载完整 SKILL.md需要参考资料时再加载 references需要跑脚本时才执行 scripts。所以一个 Skill 包再大也不会一上来就撑爆上下文。4. 验证请求从技能声明到任务执行配置写完必须验证。分两步先确认 API 通道通再确认 Skill 能被正确触发。第一步用 curl 验证通道。把 Key 换成你自己的curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: your-model-id, messages: [{role: user, content: 回复 ok}] }返回里能看到 choices 数组和内容就说明通道正常。如果报 401说明 Key 不对如果连接超时检查 Base URL 是不是写成了 https://taotoken.net/api 。第二步验证 Skill 触发。把 my-skill 文件夹放到 Agent 约定的技能目录下不同客户端路径不同常见的是项目根目录的 .agents/skills/ 或全局技能目录。然后在对话里输入一个能匹配 description 的请求比如“帮我审查一下这次改动”。观察 Agent 是否加载了 SKILL.md、是否按工作流程走。成功的话你会看到它先收集变更、再调用脚本、最后按 checklist 输出意见而不是泛泛地给几句建议。这里有个细节description 写得好不好直接决定触发准不准。我一开始写“帮助处理代码”Agent 经常不触发改成“当用户请求审查代码、检查 PR、或提到 review 时使用”之后命中率明显提升。所以验证时如果没触发先回头改 description加上明确的使用场景关键词。5. 本篇常见错排查实际用下来报错集中在几个地方对照着查能省很多时间。401 UnauthorizedKey 没传对。检查环境变量是否真的注入成功echo $TAOTOKEN_API_KEY看有没有值如果写在配置文件里确认没有多余空格或换行。用 TaoToken 的话Key 在控制台生成注意别把测试 Key 和正式 Key 搞混。local proxy failed / 连接失败Base URL 写错或网络不通。确认写的是 https://taotoken.net/api 不要多加路径或斜杠。如果客户端有代理设置检查是否误开了本地代理导致请求被拦。reading choices 报错 / 返回结构解析失败通常是模型名不对或者请求体格式有问题。确认 Model ID 和模型对话页里列出的完全一致注意大小写。另外检查 messages 数组格式role 和 content 不能缺。OAuth 相关报错如果你用的是 Claude Code 这类带 OAuth 的工具报 OAuth 错误往往说明认证方式冲突了。这时候改用 API Key 方式配置把三件套Base URL Key Model ID写全别混用两种认证。Skill 不触发不是报错但很常见。先确认文件夹名和 name 字段完全一致再确认 description 里有没有触发关键词。如果用了 disable-model-invocation 且设为 true就只能手动输入指令触发自动匹配不会生效。脚本执行失败检查 scripts 目录下脚本的可执行权限以及 compatibility 字段声明的运行环境是否满足。Python 脚本记得在 SKILL.md 里写清依赖。排查顺序建议先 curl 验证通道再确认 Skill 加载最后看脚本执行。一层层往下别一上来就怀疑 Skill 写错了。6. 把 Skill 沉淀成团队资产写到这里配置和验证的链路已经跑通了。最后说一个实际感受Agent Skills 真正的价值不在单次使用而在沉淀。你把一套流程写成 SKILL.md纳入 Git 管理团队里谁都能加载、谁都能改改了什么一目了然。这比把提示词散在聊天记录里强太多。如果你想让 Agent 长期跑编码和 Agent 任务可以了解下 Coding Plan配合统一的 Key 和通道把技能库慢慢养起来。需要生成或验证模型调用时模型对话页可以直接试。接入过程中遇到配置问题接入文档里有更细的字段说明API Key 则在控制台管理。从创建一个最简单的 SKILL.md 开始就行不用一上来就搞复杂。先让 Agent 稳定做好一件事再慢慢加脚本、加参考文档。技能库是养出来的不是一次写完的。