1. 从一次“Agent 不听话”说起Skill 到底解决什么问题你可能遇到过这种场景同一个 Agent昨天写技术文章结构清晰今天同样的提示词却输出得乱七八糟或者你反复强调“先分析根因再改代码”它还是上来就补表面症状。问题不在模型本身而在于你每次都在用 Prompt 做“一次性指挥”没有把“这类任务该怎么做”沉淀下来。Skill 就是干这个的。它是一套给 Agent 使用的可复用工作流说明书通常是一个文件夹里面至少有一个SKILL.md。Agent 启动时只看到 Skill 的名称、描述和路径当你的请求命中它的适用场景Agent 才会读取完整的SKILL.md并按里面的流程执行。它和 Prompt、MCP、Plugin 的分工可以这样对照对象作用典型场景Prompt临时告诉 Agent 这一次怎么做一次性问答、临时改写Skill长期告诉 Agent 这一类任务怎么做固定格式写复盘、按规范审查组件MCP让 Agent 连接外部工具、服务和数据访问 GitHub、数据库、NotionPlugin把 Skill、MCP 配置、素材打包分发团队统一安装一套能力所以 Skill 的本质不是“提示词增强”而是流程产品化。它把你的经验、方法、检查标准和输出偏好变成 Agent 可以重复执行的工作流。这篇面向刚接触 Agent Skill 的开发者从零拆解目录结构、SKILL.md编写规范、在 Codex/Plugin 场景下的放置位置并演示通过 TaoToken 统一 Key/API 通道完成一次 Skill 调用验证确认结构真的生效。适合谁正在用 Codex、Cline、Claude Code 等工具做 Agent 开发想让输出稳定可复现的人。2. TaoToken 前置准备统一 Key 与 API 通道怎么配在验证 Skill 之前先把模型调用通道打通。TaoToken 提供统一的 Key 和 API 入口你不需要在多个模型供应商之间来回切换配置。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 这个地址不加 UTM 参数。先拿到 Key。打开控制台页面 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 登录后在 API Keys 区域创建一个新 Key。创建时给它起个能认出来的名字比如skill-verify方便后面排查是哪个 Key 在调用。复制出来的 Key 只显示一次先存到本地环境变量里别直接写进会提交到 Git 的文件。# macOS / Linux写入当前 shell 会话 export TAOTOKEN_API_KEYsk-你的Key # Windows PowerShell $env:TAOTOKEN_API_KEYsk-你的Key如果你用的是 Claude Code 这类需要 Anthropic 兼容端点的工具可以参考接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里的说明配置 Base URL。核心三件套永远是Base URL、API Key、Model ID。缺一个都会在调用时报错后面排障章节会逐个对照。这里要强调一点Skill 本身不负责模型调用它只描述“怎么做”。真正把请求发出去的是你用的 Agent 工具或脚本。所以验证 Skill 是否生效思路是——让 Agent 在读取SKILL.md后通过 TaoToken 通道发起一次真实请求看输出是否符合 Skill 里定义的流程和验收标准。3. 可复制配置SKILL.md 模板与目录树先建目录。最小可用 Skill 只有一个文件但实际项目里建议按需扩展。下面这棵目录树可以直接复制使用my-skill/ ├─ SKILL.md ├─ agents/ │ └─ openai.yaml ├─ scripts/ │ └─ validate.py ├─ references/ │ └─ checklist.md ├─ templates/ │ └─ report.md └─ examples/ └─ sample-output.md不是每个目录都必须存在原则是需要什么才放什么。SKILL.md是入口文件必须存在agents/openai.yaml是 Codex 可选元数据可配置显示名、默认提示和隐式触发策略scripts/放确定性脚本references/放规范、术语表、检查清单templates/放输出模板examples/放输入输出示例。SKILL.md顶部是 YAML front matter下面才是正文。直接复制这个模板--- name: tech-article-writer description: Use when the user asks to write or rewrite a technical article in a fixed structure with code blocks, parameter tables, and a verification section. Do not use for casual chat or pure translation. --- # Tech Article Writer ## When to use - 用户要求按固定结构写技术文章 - 需要包含可复制代码、参数对照表、排障章节 ## Steps 1. 读取 references/checklist.md 确认结构要求 2. 按 templates/report.md 生成骨架 3. 填充代码块并标注语言 4. 运行 scripts/validate.py 检查标题层级 5. 输出前对照验收标准自检 ## Acceptance criteria - 每个 H2 正文不少于 800 字 - 代码块必须标注语言 - 包含至少一个参数对照表name要短、稳定、可被引用description要直接因为 Agent 靠它判断是否触发。写得太空比如description: Help with writing.Agent 根本不知道什么时候该用。触发条件里最好同时写清适用边界和不适用场景减少误触发。如果你在 Codex 里用agents/openai.yaml可以这样写display_name: Tech Article Writer icon: doc default_prompt: 按固定结构写一篇技术文章 implicit_invocation: true tools: - shell - file_readimplicit_invocation: true表示允许 Agent 在没被点名时也自动触发。如果你发现误触发太多就把它改成false只在你明确点名时使用。4. 验证请求通过 TaoToken 跑通一次 Skill 调用配置写好了得验证它真的生效。这里用一个最小脚本模拟 Agent 读取SKILL.md后通过 TaoToken 发起请求。先确认环境变量已设置然后执行curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [ {role: system, content: 你已加载 Skill: tech-article-writer请按 SKILL.md 中的 Steps 和 Acceptance criteria 执行。}, {role: user, content: 写一篇关于 Skill 目录结构的技术文章。} ] }成功时你会拿到一个 JSON 响应choices[0].message.content里是模型输出。判断 Skill 是否生效不看它“写了文章”而看它是否遵守了SKILL.md里的约束有没有先读references/checklist.md、有没有按templates/report.md的骨架、代码块有没有标语言、有没有跑scripts/validate.py。如果你用的是 Claude Code配置方式略有不同。在项目根目录创建.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }保存后重启 Claude Code它会读取这个配置并通过 TaoToken 通道发起请求。此时把 Skill 放进对应目录再让它执行一个命中场景的任务观察输出是否符合SKILL.md的验收标准。想快速验证模型通道本身是否通可以先用模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 发一条消息确认 Key 和 Base URL 没问题再回到 Skill 验证。这样能把“通道问题”和“Skill 结构问题”分开排查。5. 常见报错排查401、local proxy failed、reading choices验证过程中最容易撞上几类报错逐个对照。401 UnauthorizedKey 没传对或已失效。检查Authorization头是不是Bearer sk-xxx格式中间有没有多余空格检查环境变量是否在当前 shell 会话里生效echo $TAOTOKEN_API_KEY看有没有值。如果 Key 是在别的终端创建的确认复制完整没有截断。local proxy failed / connection refused通常是 Base URL 写错或本地网络配置问题。确认用的是https://taotoken.net/api不要多加/v1之外的路径也不要用带 UTM 的地址做 API 调用。如果你在settings.json里把ANTHROPIC_BASE_URL写成了官网首页地址就会连不上。reading choices of undefined响应体里没有choices字段说明请求根本没走到模型。常见原因是请求体 JSON 格式错误比如少了逗号、引号没闭合或者model字段填了一个不存在的 Model ID。先用最小请求体测试确认能拿到正常响应再往上加内容。OAuth / authentication 相关报错如果你用的是 Codex 或 Claude Code 的登录态同时又配了 API Key可能两套认证打架。检查auth.json或settings.json里是不是同时存在 OAuth token 和 API Key。保留一套即可用 TaoToken 统一 Key 时把 OAuth 相关字段清掉。Skill 没触发不是报错但很常见。先看description是不是写得太泛把关键触发词前置再看implicit_invocation是不是设成了false最后确认 Skill 放对了目录——Codex 仓库级是.agents/skills/个人级是$HOME/.agents/skills/放错位置 Agent 扫不到。排障时建议按“通道→认证→请求体→Skill 结构”的顺序查别一上来就改SKILL.md。多数问题出在前三步。6. 把 Skill 用起来放置位置与长期维护Skill 放哪里决定了它的作用范围。Codex 支持多个层级仓库级放在当前项目的.agents/skills/适合团队共享Codex 会从当前工作目录向上扫描直到仓库根目录个人级放在$HOME/.agents/skills/Windows 上通常是C:\Users\你的用户名\.agents\skills\适合你个人长期使用的写作风格、图片风格、工作流。如果你要把一个或多个 Skill 分发给别人或者把 Skill 和 MCP 配置、图标一起打包就做成 Plugin。Plugin 的目录结构是my-plugin/ ├─ .codex-plugin/ │ └─ plugin.json └─ skills/ └─ my-skill/ └─ SKILL.mdSkill 是工作流本身Plugin 是安装和分发单位。其他 Agent 工具的扫描目录不一定和 Codex 相同如果某个工具兼容SKILL.md结构它通常会要求你把每个 Skill 作为独立文件夹放进指定技能目录。不要默认把 Codex 的路径直接搬过去具体位置以该工具当前文档为准。长期维护上我试过把每次踩坑的检查项补进references/checklist.md比改SKILL.md正文更安全因为正文改动可能影响触发判断。另外scripts/里的校验脚本值得单独写测试Skill 越常用确定性逻辑越应该脚本化减少 Agent 每次重新实现带来的波动。如果你打算长期做编码类 Agent 任务可以了解 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 把 Skill 和统一 Key 通道结合起来用。需要管理多个 Key 或查看调用情况时回到 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 操作即可。
