1. 为什么你的 AI 每次都要重新教一遍如果你每天都在用 AI 处理周报、会议记录、项目文档大概率经历过这个循环打开对话框敲一段长长的指令——“先读文件再总结提炼待办最后存到某个路径”——AI 执行完你满意地关掉。第二天同样的任务你又得把那段指令重新敲一遍或者从历史记录里翻出来复制粘贴。问题不在于 AI 不够聪明而在于你把“流程”存在了自己的脑子里而不是存在一个 AI 能自动读取的地方。每次对话都是一张白纸它不知道你昨天是怎么要求的也不知道你团队里其他人是怎么要求的。这就是 SKILL.md 要解决的问题。它本质上是一个约定格式的 Markdown 文件放在 Agent 工具能扫描到的目录里用来告诉 AI遇到什么场景该触发、按什么步骤执行、输出成什么格式、哪些事不能做。写一次之后同类任务只需要一句“把这份会议记录整理成摘要和待办”Agent 就会自动加载对应的 Skill 并按固定流程执行。这篇文章面向已经在用 Cline、Claude Code 这类 Agent 工具、但还在靠“每次手打提示词”干活的开发者。我会从零写一个可复用的 SKILL.md然后把它接到 TaoToken 的统一 Key 通道上让 Skill 的调用走同一个 API 入口最后给一次可复现的验证动作确认 Skill 真的被加载和复用了。全程不需要你改编辑器也不需要你记一堆命令。2. TaoToken 前置把 Key 通道统一起来在写 Skill 之前先把“AI 从哪来”这件事定下来。Agent 工具要调用模型就得配 API Key 和 Base URL。如果你同时用 Cline 写代码、用 Claude Code 跑终端任务、又想在网页端对话每个工具各配一套 Key管理起来很碎。TaoToken 在这里的角色是一个统一的 API 通道。你可以在它的控制台生成一个 Key然后让不同工具都指向同一个 Base URL。这样 Skill 里定义的流程不管在哪个 Agent 里跑底层调用的入口是一致的。你需要先拿到两样东西API Key在控制台的 API Keys 页面创建格式通常是一串以sk-开头的字符串。Base URLhttps://taotoken.net/api注意这个地址不带任何查询参数直接作为 OpenAI 兼容接口的 base 使用。创建 Key 的入口在这里https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite拿到 Key 之后先别急着写 Skill我们先把 Agent 工具的配置改好确保模型能通。因为 Skill 的验证依赖模型能正常响应如果 Key 通道没通后面排查会分不清是 Skill 的问题还是配置的问题。注意API Key 只显示一次创建后立刻复制保存。如果丢了就重新生成一个不要试图从浏览器缓存里找。3. 可复制配置settings.json 与 config.toml 片段不同 Agent 工具的配置文件格式不一样。Cline 走的是 VS Code 设置体系Claude Code 走的是config.toml。下面给两份可直接粘贴的片段你按自己用的工具选一份。3.1 Cline 的 settings.json 配置Cline 的模型配置在 VS Code 的 settings.json 里。打开命令面板输入 “Open Settings (JSON)”在文件里加入或修改以下字段{ cline.apiProvider: openai, cline.openAiApiKey: sk-你的TaoToken密钥, cline.openAiBaseUrl: https://taotoken.net/api, cline.openAiModelId: claude-sonnet-4-20250514, cline.customInstructions: 优先检查工作区 .codebuddy/skills 目录下的 SKILL.md按其中定义的工作流执行任务。 }这里有几个点值得说明。cline.apiProvider设为openai是因为 TaoToken 提供的是 OpenAI 兼容接口Cline 用这个 provider 就能对接。cline.openAiModelId填你实际要用的模型标识不同模型在工具里的写法可能略有差异以控制台模型列表里的名称为准。cline.customInstructions这一行是给 Agent 的全局提示让它优先去扫描 Skill 目录这样 Skill 被自动发现的概率会更高。3.2 Claude Code 的 config.toml 配置Claude Code 的配置通常放在用户目录下的.claude/config.toml或者项目根目录的.claude/config.toml。加入以下内容[api] provider openai-compatible base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 model claude-sonnet-4-20250514 [agent] skill_dirs [.codebuddy/skills, .claude/skills] auto_load_skills trueskill_dirs告诉 Claude Code 去哪些目录找 SKILL.md。auto_load_skills打开后Agent 在启动时会扫描这些目录并把 Skill 注册进来。如果你把 Skill 放在项目里团队其他人拉下代码后也能直接用同一套流程。3.3 目录结构约定不管用哪个工具Skill 的目录结构建议统一成下面这样你的项目根目录/ ├── .codebuddy/ │ └── skills/ │ └── doc-to-tasks/ │ └── SKILL.md ├── .claude/ │ └── config.toml └── workspace/ └── weekly.md目录名doc-to-tasks是这个 Skill 的标识SKILL.md 里的name字段要和它保持一致。这样 Agent 在匹配时不会因为名称对不上而找不到。4. 写一个能复用的 SKILL.md现在进入核心部分。我们要写的 Skill 叫doc-to-tasks功能是把长文、周报、会议记录整理成摘要和可执行待办。下面这份是可以直接复制使用的完整内容--- name: doc-to-tasks description: 将长文、报告、周报或会议记录整理为简短摘要和可执行待办。当用户要求提炼文档重点、整理行动项或把文章转换为任务清单时使用。 --- # 长文转摘要和待办 ## 工作流 1. 获取用户提供的正文或文件路径。 2. 阅读完整内容识别主题、关键结论和明确的行动要求。 3. 生成不超过 200 字的摘要优先保留结论、决定和重要数据。 4. 提取最多 5 条待办每条以明确的动作动词开头。 5. 按“摘要 → 待办”结构输出。 6. 用户提供输出路径时写入文件否则直接返回结果。 7. 输出前检查内容是否忠于原文、待办是否可执行。 ## 输入 - 必填源文本或可读取的文件路径。 - 可选输出路径、摘要字数、待办数量上限。 ## 输出格式 # 摘要 摘要正文。 # 待办 - [ ] 动作 对象 必要的时间或责任信息 ## 约束 - 不臆造原文中没有的事实、负责人或截止日期。 - 无法从原文确认的信息标记为“待确认”。 - 待办必须具体、可执行避免“关注一下”“思考一下”等模糊表达。 - 原文没有明确行动项时如实说明不强行生成待办。这份文件里有四个关键部分缺一个都会让复用效果打折扣。YAML 头里的name和description决定 Agent 能不能在正确场景下找到这个 Skill。description不能只写“处理文档”那样会和翻译、润色、校对类 Skill 混淆。要写清楚处理对象、产出结果和典型触发场景比如“将会议记录或报告整理为摘要和可执行待办”。工作流部分定义执行顺序。注意第 7 步“输出前检查”很容易被忽略但它是让输出稳定的关键。没有这一步Agent 可能这次生成 3 条待办、下次生成 8 条格式也飘。输出格式部分给出模板。只写“生成摘要和待办”Agent 每次的排版可能都不一样给出# 摘要和# 待办的固定结构结果就统一了。约束部分写禁止事项。“不臆造负责人和截止日期”这条尤其重要否则 AI 很容易在待办里编出一个不存在的日期你拿去用就出问题。4.1 description 的写法公式description是触发匹配的核心。可以套这个公式处理对象 产出结果 典型触发场景。对比一下两种写法写法效果description: 处理文档范围过大无法区分摘要、翻译、校对description: 将长文、报告、周报或会议记录整理为简短摘要和可执行待办。当用户要求提炼文档重点、整理行动项或把文章转换为任务清单时使用。同时说明对象、产物和触发场景写的时候用用户真实会说的话比如“整理行动项”“提炼文档重点”而不是“执行文档摘要提取算法”这种机器语言。5. 验证请求确认 Skill 被加载和复用配置和文件都就位后需要一次可复现的验证。分三步走先确认模型通道通再确认 Skill 被发现最后确认 Skill 被正确执行。5.1 第一步确认模型通道在 Agent 对话框里发一条最简单的请求你好请回复“通道正常”四个字。如果返回了“通道正常”说明 TaoToken 的 Key 和 Base URL 配置没问题。如果报 401 或连接超时回到第 3 节检查 Key 是否复制完整、Base URL 是否写成了https://taotoken.net/api不要多加斜杠或路径。5.2 第二步确认 Skill 被发现在项目里准备一个测试文件workspace/weekly.md内容随意比如本周完成登录模块重构接口响应时间降低约 20%。支付模块仍有两个兼容性问题计划下周完成修复并进入回归测试。另外需要整理接口性能测试报告。然后发一条显式调用指令使用 doc-to-tasks 处理 workspace/weekly.md并把结果保存到 workspace/summary.md。显式指定 Skill 名称可以绕过语义匹配的不确定性适合首次验证。如果这条能跑通说明 Skill 文件被正确加载了。如果提示找不到 Skill检查三件事文件是否严格命名为SKILL.md大小写敏感、YAML 头是否在文件最上方且被---包围、name字段是否和目录名一致。5.3 第三步确认自动触发和复用显式调用通过后换成自然语言帮我把这份周报整理成摘要和待办。预期 Agent 会自动匹配到doc-to-tasks读取workspace/weekly.md输出类似下面的结果# 摘要 本周完成登录模块重构接口响应时间降低约 20%。支付模块仍有两个兼容性问题计划下周完成修复并进入回归测试。 # 待办 - [ ] 修复支付模块的两个兼容性问题 - [ ] 完成登录模块回归测试 - [ ] 整理接口性能测试报告如果输出结构一致、待办可执行、没有编造日期说明 Skill 被正确复用。这时候你可以再换一份会议记录测试确认同一套流程能处理不同输入。5.4 反向测试不该触发时不触发一个可靠的 Skill 还要在不相关场景保持克制。发一条翻译请求把这份英文报告翻译成中文。如果 Agent 没有套用“摘要 待办”的流程而是走了翻译逻辑说明description的边界划得清楚。如果它错误地触发了doc-to-tasks说明description写得太宽需要缩小输入类型和目标产物。6. 本篇常见错排查Skill 用起来之后最容易卡在下面几个地方。我按现象、原因、处理方式列出来方便你对照。6.1 Skill 没有被发现现象是显式调用时提示找不到 Skill。先检查路径是否为.codebuddy/skills/doc-to-tasks/SKILL.md注意SKILL.md必须全大写。再检查 YAML 头---必须单独占一行name和description的缩进不能乱。最后确认 Agent 工具的配置里skill_dirs包含了这个目录。改完后重开会话或重新加载工作区让客户端重新扫描。6.2 相关请求没有自动触发显式调用能工作但自然语言请求不触发。这通常是description没有覆盖用户真实表达。比如用户说“帮我理一下行动项”而description里只写了“生成待办”匹配就可能失败。处理方式是在description里补充同义表达比如“整理行动项”“提炼文档重点”“转换为任务清单”。改完后用正向测试重新验证。6.3 不相关任务也被触发翻译、润色、校对类请求错误地走了doc-to-tasks。这说明description过于宽泛。把“处理文档”改成“将会议记录或报告整理为摘要和可执行待办”明确输入类型是会议记录和报告产出是摘要和待办就能把翻译类请求排除掉。6.4 每次输出格式不一致待办数量忽多忽少排版每次不同。原因通常是 SKILL.md 里只写了“做什么”没写“做到什么程度算完成”。在输出格式部分给出固定模板在工作流最后加一步“输出前检查”并在约束里写明待办数量上限和摘要字数上限。这三处补齐后输出会明显稳定。6.5 模型返回 401 或超时这跟 Skill 无关是 Key 通道的问题。检查api_key是否以sk-开头且没有多余空格base_url是否为https://taotoken.net/api。如果用的是 Cline确认cline.apiProvider设为openai。如果还是不通去控制台重新生成一个 Key 再试。7. 把 Skill 接到长期编码工作流单次验证通过后你可以把这个模式扩展到更多场景。比如写一个code-reviewSkill 处理 PR 描述生成写一个bug-triageSkill 把报错日志整理成排查清单。每个 Skill 都是一个独立的 SKILL.md放在.codebuddy/skills/下按目录区分。如果你打算让 Agent 长期跑编码任务、自动调用多个 Skill可以考虑用 Coding Plan 来管理调用配额和通道入口在这里https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite需要查模型对话能力或调试接口时模型对话入口https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite接入文档和参数说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteClaude Code 相关配置参考https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_codeutm_campaignrewrite控制台管理 Key 和用量https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite回到最开始的问题聊天解决这一次Skill 沉淀下一次。你不需要一次写出完美的 SKILL.md先用自然语言把任务跑通确认输入、处理、输出都合理再把它固化成文件。之后每遇到一个重复流程就多写一个 Skill。积累下来你的 Agent 会越来越懂你的工作方式而不是每次都要你从头教一遍。