1. 从一次“文档翻车”说起Skill 工作流到底解决什么问题你可能也遇到过这种场景让 AI 编程助手帮忙生成一份 API 文档结果它洋洋洒洒写了一大篇格式看着还行但仔细一读——错误码表格没有、鉴权说明漏了、参数命名一会儿驼峰一会儿下划线跟团队规范完全不搭。你只好从头口述一遍要求下次换个任务又得重来一遍。这不是模型不够聪明而是它缺少“你们团队希望这件事怎么做”的上下文。Agent 本身能力很强能读代码库、能规划多步修改、能调用工具链但它不知道你团队的约定、流程、检查清单和输出模板。每次任务都靠自然语言临时交代既低效又不稳定。Skill 就是冲着这个问题来的。它是一套开放的、可移植的、版本可控的指令包把“某类任务应该怎么做”写成一份SKILL.md文件放在项目目录或团队共享库里。当 Agent 识别到任务匹配时会自动加载对应 Skill获得完成任务所需的领域知识和流程约束。用一句话概括Agent 负责“能做事”Skill 负责“知道怎么按你的规矩做事”MCP 负责“有工具可用”。三者配合才能把一次性对话变成可复用的工作流。这篇文章面向想搭建自动化工作流的开发者我会从SKILL.md的目录结构讲起串起 Agent 与 MCP 的协作方式最后给出一套可复现的本地验证步骤。你不需要先精通 Agent 原理跟着操作就能跑通第一条 Skill 工作流。2. 前置准备TaoToken 接入与 SKILL.md 目录结构设计在动手写 Skill 之前先把“模型调用通道”和“Skill 文件结构”这两件事准备好。前者决定 Agent 能不能稳定推理后者决定工作流能不能被正确加载。2.1 为什么先用 TaoToken 打通模型调用Skill 工作流的执行主体是 AgentAgent 的推理依赖大模型。如果你在本地调试 Skill最省事的做法是先把模型调用统一到一个兼容 OpenAI 接口的入口上这样 Claude Code、Cline、Codex 这类工具都能复用同一套 Base URL 和 Key不用每个工具单独配一遍。TaoToken 提供的就是这样一个统一入口官网地址是https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 地址是https://taotoken.net/api注意 API 地址不带 UTM 参数。它的作用是让你用一套凭证访问多种模型方便在 Skill 调试阶段快速切换模型对比效果。你需要先拿到 API Key。进入控制台创建密钥https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite然后在 API Keys 页面生成https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite。拿到 Key 之后先别急着写 Skill我们先把目录结构定下来。2.2 SKILL.md 的标准目录结构一个 Skill 至少包含一份SKILL.md复杂一点可以带参考文档、模板和脚本。推荐的结构如下skills/ └── api-doc-generator/ ├── SKILL.md # 必需元数据 工作流指令 ├── references/ │ ├── error-codes.md # 错误码规范 │ └── auth-guide.md # 鉴权说明模板 ├── assets/ │ └── doc-template.md # 输出文档模板 └── scripts/ └── validate.py # 可选校验脚本SKILL.md本身由两部分组成YAML frontmatter元数据和 Markdown body工作流指令。元数据里最关键的是name和description——Agent 启动时只加载这两项用来判断当前任务是否匹配这个 Skill。description 写得越具体触发越准。--- name: api-doc-generator description: 为 REST API 生成符合团队规范的接口文档包含错误码表格、鉴权说明和 snake_case 参数命名。当用户要求生成或更新 API 文档时使用。 --- # API 文档生成工作流 ## 步骤 1. 读取目标接口的源码或 OpenAPI 描述文件 2. 从 references/error-codes.md 加载错误码规范 3. 按 assets/doc-template.md 的结构组织输出 4. 检查所有参数命名是否为 snake_case 5. 输出前运行 scripts/validate.py 做格式校验这里有个设计要点Progressive Disclosure渐进式披露。Agent 启动时只读 frontmatter任务匹配后才加载 body执行到具体步骤才按需读取references/和assets/。这样你可以同时挂几十个 Skill上下文窗口也不会被撑爆。2.3 MCP 配置片段让 Agent 有工具可用Skill 描述“怎么做”但真正执行读文件、跑脚本这些动作靠的是 MCP。MCP 是 Agent 与外部工具之间的标准接口你可以把它理解成“工具插座”。下面是一个典型的 MCP 配置片段放在项目的.mcp.json或工具对应的配置文件中{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, ./skills] }, shell: { command: npx, args: [-y, modelcontextprotocol/server-shell] } } }这段配置做了两件事把./skills目录暴露给 Agent 读取同时允许它执行校验脚本。注意生产环境的数据库连接、密钥管理这类敏感操作不要直接挂到 MCP 上调试阶段用本地文件系统就够了。如果你用的是 Claude Code配置方式略有不同需要在settings.json里声明 MCP server如果用 Cline则在 MCP 配置面板里填。无论哪种工具三件套都是Base URL Key Model ID。Base URL 填https://taotoken.net/apiKey 填你刚才生成的Model ID 按你选的模型填。3. 可复制配置把 SKILL.md 和 MCP 串起来上一节给了骨架这一节把配置补全让你可以直接复制到项目里跑。我会用一个“代码审查工作流”作为例子因为它比文档生成更能体现多步骤协作。3.1 完整的 SKILL.md 示例--- name: code-review-workflow description: 对指定代码文件执行团队代码审查检查命名规范、错误处理、日志格式和测试覆盖。当用户要求审查代码或提交 PR 前自检时使用。 --- # 代码审查工作流 ## 触发条件 用户提到“审查代码”“review”“PR 自检”时加载本 Skill。 ## 工作流步骤 ### 第一步读取目标文件 调用 filesystem MCP 读取用户指定的文件路径。如果用户没指定询问具体文件。 ### 第二步加载审查清单 从 references/review-checklist.md 加载团队审查清单包含 - 命名规范变量 snake_case类 PascalCase - 错误处理不允许裸 except - 日志格式统一使用结构化日志 - 测试覆盖新增函数必须有对应测试 ### 第三步逐项检查 对每个检查项输出通过 / 不通过 / 需人工确认并附上具体行号。 ### 第四步生成审查报告 按 assets/review-report.md 模板输出包含问题列表和修复建议。 ### 第五步运行校验 调用 shell MCP 执行 scripts/lint.sh把结果附在报告末尾。3.2 配套的 MCP 与工具配置在 Claude Code 的settings.json中配置如下{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, ./skills] }, shell: { command: npx, args: [-y, modelcontextprotocol/server-shell] } }, env: { OPENAI_BASE_URL: https://taotoken.net/api, OPENAI_API_KEY: 你的_API_Key, OPENAI_MODEL: 你的_Model_ID } }如果你用的是 ClineMCP 配置写在cline_mcp_settings.json里结构类似。Codex 的话认证信息放在auth.jsonBase URL 和 Key 的填法参考官方文档。三件套缺一不可Base URL 指向https://taotoken.net/apiKey 用你生成的Model ID 按实际模型填。3.3 目录与文件的对应关系把上面的配置落到磁盘上目录长这样project/ ├── .mcp.json ├── settings.json └── skills/ └── code-review-workflow/ ├── SKILL.md ├── references/ │ └── review-checklist.md ├── assets/ │ └── review-report.md └── scripts/ └── lint.shSKILL.md里的路径都是相对 Skill 根目录的Agent 加载时会自动解析。这一点很重要不要把绝对路径写死在 SKILL.md 里否则换台机器就失效了。4. 验证请求跑通第一条 Skill 工作流配置写完了怎么确认它真的生效这一节给出一套可复现的本地验证步骤从发请求到看结果一步步来。4.1 启动 Agent 并加载 Skill以 Claude Code 为例在项目根目录执行claude进入交互界面后输入请审查 skills/code-review-workflow/scripts/lint.sh 这个文件如果 Skill 配置正确Agent 应该会识别到“审查”这个关键词自动加载code-review-workflowSkill。你会在输出里看到它先读取文件然后加载审查清单再逐项检查。4.2 用 curl 直接验证模型通道如果你想先确认 TaoToken 的模型调用是通的可以单独发一个请求curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的_API_Key \ -d { model: 你的_Model_ID, messages: [ {role: user, content: 用一句话说明什么是 Skill 工作流} ] }返回结果里如果能看到choices字段和正常的文本内容说明模型通道没问题。这一步能帮你把“模型调用失败”和“Skill 配置失败”两类问题分开排查。4.3 观察渐进式加载是否生效验证 Skill 是否按 Progressive Disclosure 工作时可以故意在references/review-checklist.md里放一个明显的检查项比如“所有函数必须有 docstring”。然后让 Agent 审查一个没有 docstring 的文件。如果报告里出现了这一项说明 references 被正确加载了。反过来如果 Agent 完全没提这个检查项可能是 description 没匹配上或者 MCP 没读到references/目录。这时候先检查.mcp.json里的路径是不是指向了./skills再检查SKILL.md里的相对路径有没有写错。4.4 成功结果的判断标准一次成功的 Skill 工作流执行应该满足三个条件Agent 自动加载了正确的 Skill不需要你手动指定、工作流按 SKILL.md 里的步骤顺序执行、输出符合模板和检查清单的要求。如果只满足了第一条说明 Skill 触发了但指令没被完整执行通常是 body 写得太模糊需要把步骤拆得更细。5. 常见报错排查401、local proxy failed 与 OAuth 问题调试 Skill 工作流时报错大多集中在模型通道和 MCP 连接两块。下面按真实报错逐个拆。5.1 401 Unauthorized这是最常见的报错意思是 Key 无效或没带上。检查三处settings.json里的OPENAI_API_KEY是不是复制时多了空格curl 请求的Authorization头是不是Bearer开头Key 是不是在控制台被删了或过期了。如果用的是 Claude Code还要确认它读的是哪个配置文件——有时候项目级配置和用户级配置会冲突。5.2 local proxy failed这个报错通常出现在 MCP server 启动失败时。原因可能是npx找不到包或者网络环境导致包下载不下来。先手动执行npx -y modelcontextprotocol/server-filesystem ./skills看能不能正常启动。如果卡在下载检查 npm 源如果启动后立刻退出检查路径参数是不是写错了。注意这里不要引入任何网络代理相关的配置保持本地直连即可。5.3 reading choices 报错当你看到类似cannot read property choices of undefined的报错说明模型返回的结构不符合预期。常见原因是 Base URL 填错了——比如填成了https://taotoken.net而不是https://taotoken.net/api导致请求打到了网页而不是 API。另一个原因是 Model ID 写错了模型不存在时返回体里没有choices字段。5.4 OAuth 相关报错部分工具比如 Codex用 OAuth 方式认证如果你混用了 API Key 和 OAuth会出现 token 冲突。解决办法是二选一要么全用 API Key在auth.json里填 Base URL 和 Key要么全用 OAuth。混用时最容易出现的报错是invalid token或token expired看起来像 Key 失效其实是认证方式串了。5.5 Skill 不触发如果模型通道没问题但 Agent 就是不加载 Skill先检查description是不是太笼统。比如写成“处理代码相关任务”就很难触发改成“审查 Python 代码的命名规范和错误处理”就精准得多。其次检查 Skill 目录是不是在 MCP 暴露的路径下最后确认 frontmatter 的 YAML 格式有没有缩进错误。6. 下一步把 Skill 工作流用起来跑通第一条工作流之后你可以沿着两个方向继续一是把更多团队规范编码成 Skill比如发布流程、测试用例生成、日志排查二是把 Skill 和 Coding Plan 结合让 Agent 在长期编码任务里自动调用。如果你还没拿到 Key先去控制台创建https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite然后在 API Keys 页面生成https://taotoken.net/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。如果你打算把 Skill 工作流用在长期编码或 Agent 任务上Coding Plan 会更合适https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite。最后分享一个我踩过的坑Skill 的description不要写得太“聪明”要写得像给新同事交代任务一样具体。我一开始写“优化代码质量”结果 Agent 十次有八次不触发改成“检查函数命名是否为 snake_case、是否有裸 except、是否有对应单元测试”之后触发率立刻上来了。Skill 的价值不在于写得多优雅而在于写得足够明确让 Agent 每次都能按同一套标准执行。