1. 第一次写 Agent Skill为什么你的 SKILL.md 总是不被触发很多人第一次接触 Agent Skill脑子里想的都是「我写个 Markdown 文件Agent 就能自动学会一项新能力」。结果文件写完了丢进目录里Agent 该干嘛干嘛完全不搭理你。于是开始怀疑是不是格式写错了是不是要重启是不是这个 Agent 根本不支持 Skill我试过最典型的翻车场景是这样的写了一个「代码审查」的 Skilldescription 写的是「帮助审查代码」。然后给 Agent 一段有明显问题的 JavaScript它回了一段泛泛而谈的「建议检查变量命名、注意边界条件」完全没有按我预设的 JSON 结构输出。问题不在 Agent 笨而在于我的 SKILL.md 没有把「什么时候该调用我」「调用后按什么格式输出」讲清楚。Agent Skill 的本质是一份能被智能体自动发现并按规范执行的能力定义包。它不是一个 Prompt 模板也不是一段插件代码而是一个独立文件夹核心是里面的SKILL.md。这个文件要同时回答四个问题这个技能叫什么、它能做什么、什么场景下该被触发、执行步骤和输出格式是什么。只要有一个环节含糊Agent 就会选择「不调用」或者「调用后自由发挥」。这篇面向初次接触 Agent Skill 的开发者聚焦 SKILL.md 的结构设计与最小可运行示例。我会给出可复制的 SKILL.md 模板、目录结构、配置片段并结合 TaoToken 的统一 Key/API 通道完成一次真实调用。你跟着做能跑通第一个 Skill并且知道每一步为什么这么写。适合谁看写过一点 Python 或 Node想让 Agent 稳定执行某个固定任务的人被「输出格式飘忽不定」折磨过的人想把业务逻辑从随机 Prompt 里抽出来、做成可复用能力包的人。核心检索词就三个Agent Skill、SKILL.md、入门。下面从目录结构开始拆。2. SKILL.md 目录结构与 frontmatter 设计Agent Skill 入门指南先看一个 Skill 的最小目录长什么样。官方 Skills 仓库的规范是每个 Skill 独立成文件夹核心是SKILL.md其余都是可选资源code-review-skill/ ├── SKILL.md # 核心说明文件必须 ├── scripts/ # 可选自动化脚本 │ └── validate.py ├── templates/ # 可选输出格式模板 │ └── report.json ├── resources/ # 可选资源文件 └── examples/ # 可选示例输入/输出 ├── input.js └── output.json即便没有 scripts 和 templates只要SKILL.md结构合理它就能在支持 Skills 的系统里被发现并使用。但有一个坑必须提前说文件夹名字必须和 SKILL.md 里 frontmatter 的 name 字段一致。上面文件夹叫code-review-skill那 frontmatter 里就必须写name: code-review-skill。不一致的话加载时可能直接识别不到而且不会报错你只会觉得「怎么没反应」。frontmatter 用 YAML 格式封装最基本的身份信息--- name: code-review-skill description: 当用户提供 JavaScript 或 TypeScript 代码片段并希望获得结构化审查结果时使用。输出必须是包含 issues 和 recommendations 两个字段的合法 JSON。 ---这里description是整份文件里最容易被低估的一行。它不是「技能描述」而是系统判断「是否该调用这个 Skill」的依据。写「帮助审查代码」太泛Agent 无法判断边界写「当用户提供 JavaScript 或 TypeScript 代码片段并希望获得结构化审查结果时使用」触发条件就具体了。我的经验是description 里最好包含输入类型 触发意图 输出形态三要素缺一个都会让触发准确率下降。Instructions 部分负责执行流程原则是分步骤、每步单一任务、避免抽象表达## Instructions 1. 接收用户提供的代码片段识别语言类型JavaScript 或 TypeScript。 2. 按以下规则逐条检查组件命名是否首字母大写、是否存在未处理的 Promise 拒绝、是否有硬编码的敏感信息。 3. 将发现的问题整理为 issues 数组每条包含 line、type、message。 4. 将改进建议整理为 recommendations 数组每条为一句可执行的修改动作。 5. 输出合法 JSON不要输出任何解释性文字。Examples 不是装饰它是 Skill 能否稳定输出正确结构的关键。抽象描述「输出结构化结果」远不如一个真实输入输出对有效## Examples Input: js function helloWorld() { return divhi/div; }Expected Output: {issues:[{line:1,type:naming,message:组件名需首字母大写}],recommendations:[将函数名改为 HelloWorld]}Guidelines 是输出约束负责兜住边界情况 markdown ## Guidelines - 输出必须是合法 JSON不允许包裹 Markdown 代码块。 - 必须包含 issues 和 recommendations 两个字段即使为空数组也要保留。 - issues 中每条必须含 line、type、message 三个键。 - 不得输出 JSON 以外的任何字符。把四部分拼起来就是一份完整可用的 SKILL.md。这里有个判断标准如果你把这份文件交给一个没看过你需求的人他能不能照着复现出同样的输出能说明结构到位了不能说明某一部分还在靠「猜」。3. 用 TaoToken 统一 Key 跑通第一次 Skill 调用Skill 写好了接下来要让它真正跑起来。Agent 执行 Skill 时需要调用大模型而模型调用需要一个稳定的 API 通道。这里用 TaoToken 做统一入口好处是一个 Key 可以对接多种模型不用为每个模型单独维护一套鉴权和 Base URL。先拿到 Key。打开控制台页面创建 API Keyhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi_keys创建后复制那串以sk-开头的 Key只显示一次记得存好。然后确认你要用的模型 ID可以在模型对话页面试一下https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodels接下来是配置。如果你用的是 Claude Code 这类支持自定义端点的编码工具配置通常落在settings.json里。路径按你本机实际安装位置来配置片段如下{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-5 } }如果你用的是 Codex 系工具配置落在auth.json写法不同但三件套一致{ base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密钥, model: gpt-5 }不管哪种工具记住三件套Base URL Key Model ID。Base URL 统一用https://taotoken.net/api不要带 UTM 参数Key 用刚才创建的Model ID 用你在模型页面确认过的。三者缺一调用就会失败。如果你用的是 Cline 或带 MCP 的编辑器配置通常写在 MCP 的 settings 里结构类似{ mcpServers: { taotoken: { command: npx, args: [-y, taotoken/mcp-server], env: { TAOTOKEN_API_KEY: sk-你的TaoToken密钥, TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_MODEL: claude-sonnet-4-5 } } } }配置写完后把 Skill 文件夹放到 Agent 约定的 Skills 目录下。不同工具目录不同常见的是项目根目录的.skills/或用户目录下的~/.agent/skills/。放好后重启工具让 Agent 重新扫描 Skill。这一步最容易出的问题是「配置写了但没生效」。排查顺序先确认 Base URL 没有多余斜杠或空格再确认 Key 没有过期最后确认 Model ID 拼写和模型页面完全一致。三件套里任何一项错了都会表现为「调用无响应」或「鉴权失败」而不是明确告诉你哪一项错了。4. 验证请求与结果校验确认 Skill 真的被调用配置完成后做一次最小验证。先不经过 Agent直接用 curl 打一次 API确认通道本身是通的curl https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: sk-你的TaoToken密钥 \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-5, max_tokens: 256, messages: [ {role: user, content: 只回复两个字通了} ] }如果返回里能看到content字段和「通了」说明 Key、Base URL、Model ID 三件套没问题。这一步很重要它把「通道问题」和「Skill 问题」隔离开。很多人一上来就测 Skill失败了不知道是通道错还是 Skill 写错白白浪费时间。通道通了之后回到 Agent 里触发 Skill。给 Agent 一段和 Examples 里类似的代码function helloWorld() { return divhi/div; }预期结果是 Agent 调用code-review-skill并返回类似{ issues: [ {line: 1, type: naming, message: 组件名需首字母大写} ], recommendations: [ 将函数名改为 HelloWorld ] }校验时看三点第一输出是不是纯 JSON有没有被 Markdown 代码块包裹第二issues 和 recommendations 两个字段是否都在哪怕为空第三issues 里每条是否含 line、type、message。三点都满足说明 Skill 的 Guidelines 生效了。如果 Agent 没有调用 Skill而是直接用自己的方式回答说明 description 的触发条件没写准。这时候把 description 改得更具体比如加上「当用户提供 JavaScript 代码片段并要求结构化审查时」再重启工具重试。触发问题几乎都能通过改 description 解决。如果调用了但输出格式不对问题在 Guidelines 或 Examples。检查 Guidelines 里有没有明确「不允许包裹代码块」Examples 里的 Expected Output 是不是合法 JSON。示例越具体输出越可预测。5. 常见报错排查401、local proxy failed、reading choices、OAuth跑 Skill 的过程中报错基本集中在几类。下面按真实报错对照排查。401 Unauthorized。这是鉴权失败九成是 Key 问题。检查 Key 是否复制完整、是否过期、是否在配置里多了引号或空格。如果你在settings.json里写的是ANTHROPIC_AUTH_TOKEN: sk-xxx 末尾那个空格就会导致 401。另外确认 Base URL 是https://taotoken.net/api不要写成带/v1或其他路径的形式路径拼接错误也会表现为鉴权异常。local proxy failed。这个报错通常出现在工具尝试走本地代理转发时。检查你的配置里有没有残留的代理设置比如HTTP_PROXY、HTTPS_PROXY环境变量或者工具自身的 proxy 配置项。把 Base URL 直接指向https://taotoken.net/api不要经过任何中间转发层。如果工具默认开启了本地代理模式在设置里关掉改为直连。reading choices 相关报错。这类报错一般出现在解析响应体时提示读取choices字段失败。原因是请求发出去后返回的结构和预期不符常见于 Model ID 写错或接口路径不对。确认你用的 Model ID 和模型页面完全一致确认请求路径是/v1/messagesAnthropic 格式或对应格式。如果工具默认按 OpenAI 格式解析而模型返回的是 Anthropic 格式就会读不到choices。OAuth 相关报错。有些工具默认走 OAuth 登录流程而不是 API Key。如果你看到 OAuth 报错说明工具在尝试用账号授权而不是 Key 鉴权。在配置里显式指定 API Key 模式把ANTHROPIC_AUTH_TOKEN或对应的 Key 字段填上关掉 OAuth 自动流程。三件套里 Key 一旦显式配置工具就不会再走 OAuth。排查的通用顺序是先用 curl 确认通道通不通再确认配置三件套最后才怀疑 Skill 本身。这个顺序能帮你快速定位问题在哪一层而不是在三个层面之间反复横跳。6. 把 Skill 用起来从最小示例到可复用能力包跑通第一个 Skill 之后你会发现真正的价值不在于「写了一个 Markdown 文件」而在于把业务逻辑、输出规范和执行流程结构化表达出来。一个稳定的 Skill 需要四样东西明确的任务和触发判断、清晰的执行步骤、足够具体的示例、严格的输出约束。缺任何一样输出就会飘。接下来可以做的扩展把scripts/validate.py加进去在 Instructions 里引用它做输出校验把templates/report.json作为输出模板让 Guidelines 直接指向模板文件把多个相关 Skill 组织成一个能力包按目录分类管理。这些都不需要改 Agent 本身只需要在 SKILL.md 里把引用关系写清楚。如果你想把 Skill 接入到长期运行的编码或 Agent 工作流里可以考虑用 Coding Plan 做统一管理https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding_plan接入文档在这里里面有各工具的完整配置示例https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc最后给一个实用技巧每次改完 SKILL.md先用 Examples 里的输入跑一遍确认输出和 Expected Output 结构一致再去测边界情况。Examples 是你的回归测试用例别把它当摆设。结构对了边界情况才有讨论的意义。