1. 先搞清楚 SKILL 到底是什么Agent 技能包与 SKILL.md 结构全解析很多人第一次接触 Agent 技能体系时会把 SKILL 和 prompt、tool、MCP 混在一起用结果写出来的东西四不像。我先把概念掰开SKILL 是一个按需加载的 SOP 模块本质是「增强版提示词 可执行脚本 参考资料」的组合包。它解决的不是「模型能不能回答」而是「模型能不能按一套固定流程稳定地把多步骤任务做完」。你可以把 SKILL 理解成一本工具书封面写着这本书是干什么的元数据目录页告诉你先做什么后做什么SKILL.md 正文书里还夹着几把专用工具scripts/和一堆附录资料references/。Agent 平时不会把整本书背下来只在判断「这个任务需要这本书」时才翻开翻到某一步需要附录了再去读附录。这就是所谓的渐进式披露——上下文很贵能晚加载就晚加载。对比一下几种形态会更清楚。传统 prompt 是一次性指令你问什么它答什么复用性极低tool 是原子化接口比如读文件、发请求只干一件事MCP 提供的是统一的数据与动作来源把外部服务接进来而 SKILL 承载的是完整任务 SOP比如「把一份 Excel 转成 Markdown 并生成配图说明」这种多步骤流程。它们不是替代关系而是层次不同SKILL 的正文里可以指示 Agent 去调用某个 tool也可以让脚本去访问某个 MCP 暴露的能力。那 SKILL 能不能自己取数据能但不合适。就像瑞士军刀能切菜可没人拿它当菜刀使。取数据这种原子动作交给 tool 或 MCP 更稳SKILL 负责的是「什么时候取、取完怎么处理、处理完按什么格式输出」这套编排逻辑。一个标准 SKILL 的目录长这样你可以直接照着建skill-name/ ├── SKILL.md # 必须元数据 正文指令 ├── scripts/ # 可选可执行脚本 │ ├── init_skill.py │ └── validator.sh ├── references/ # 可选外部知识与规范 │ ├── REFERENCE.md │ └── api-schema.json └── assets/ # 可选静态资源 ├── template.html └── diagram.png四个部分各司其职。SKILL.md 是灵魂决定 Agent 是否调用、怎么执行scripts/ 是机械手臂Agent 不读代码内容只用 bash 工具启动脚本再读结果references/ 是外置大脑任务进行到特定步骤才被 read 工具加载assets/ 放模板和图片这类静态物料。适合谁适合那些已经把某个流程跑通、想把它固化下来反复用的开发者——你不需要每次都在对话里重新解释一遍规则。2. 接入前的准备在 TaoToken 上拿到可用的 Base URL 与 Key在动手写 SKILL 之前得先有一个能稳定跑 Agent 的模型入口否则你写完没法验证。我这边用的是 TaoToken 的 API 接入方式官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 注意这个地址后面不加任何查询参数。第一步打开控制台创建密钥。控制台入口是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 登录后在 API Keys 页面点新建复制那串以 sk- 开头的 Key存到本地环境变量里别直接写进代码提交。API Keys 直达页是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 后面排障时你还会回到这里核对 Key 是否失效。第二步确认你要用的模型 ID。不同模型对工具调用的支持程度不一样SKILL 里如果涉及脚本执行和文件读取建议选工具调用能力完整的模型。模型列表可以在模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 里先试一轮确认能正常返回再写进配置。第三步把三件套记牢Base URL、API Key、Model ID。这三样在后面的 settings、auth.json、MCP 配置里会反复出现任何一处写错都会导致 401 或模型找不到。我建议你在本地建一个.env文件统一管理# .env 仅本地使用务必加入 .gitignore TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_API_KEYsk-你的密钥 TAOTOKEN_MODEL你的模型ID如果你打算长期跑编码类 Agent 任务比如让 SKILL 驱动代码生成和校验可以看下 Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它更适合高频调用场景。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到参数不确定时以文档为准。这里提醒一句Key 只放在服务端或本地环境变量不要写进 SKILL.md 正文也不要提交到公开仓库。SKILL 是会被 Agent 读取的文本密钥写进去等于公开。需要脚本访问 API 时让脚本从环境变量读取SKILL.md 里只写「调用 scripts/xxx.py密钥从环境变量 TAOTOKEN_API_KEY 读取」这样的指令。3. 可复制配置SKILL.md 声明、scripts 脚本与 references 组织这一节是重头戏我按「元数据 → 正文 → 脚本 → 参考资料」的顺序给你可直接复制的片段路径和原文保持一致。先写 SKILL.md 的元数据部分用---包裹这部分会常驻系统提示词是 Agent 路由决策的唯一依据--- name: excel-to-md-report description: 将用户提供的 Excel 文件转换为 Markdown 表格并生成一份包含字段说明的报告。适用于数据整理、周报生成、表格迁移等场景。当用户提到Excel 转 Markdown表格整理成文档把 xlsx 变成 md时加载本技能。 ---description 要写清楚三件事做什么、为什么、什么时候用。别写「一个处理表格的技能」这种模糊描述Agent 判断不出来就不会调用。正文指令部分给出清晰步骤和脚本调用方式# 角色定义 你是一位数据整理专家负责把 Excel 数据转成结构化 Markdown 文档。 ## 触发条件 当用户要求转换 Excel、整理表格或生成数据报告时加载本技能。 ## 工作流程 1. 确认用户提供的文件路径存在若不存在则提示用户补充。 2. 执行 python scripts/parse_excel.py --input 文件路径 --output ./out.md。 3. 读取脚本输出的 out.md检查表格行列数是否与源文件一致。 4. 在转换前先读取 references/report_rules.md 获取报告格式规范。 5. 按规范在表格后追加字段说明段落。 ## 规则 - 因为表格列名可能含特殊字符转换时统一做转义处理避免 Markdown 渲染错乱。 - 空单元格输出为空字符串不要填 N/A保持与源数据一致。注意正文里那句「先读取 references/report_rules.md」——这就是渐进式加载的触发点Agent 执行到第 4 步才会去读这个文件前面几步不占用上下文。scripts/ 下的脚本示例Agent 不会读它的内容只负责启动# scripts/parse_excel.py import argparse, os import pandas as pd def main(): parser argparse.ArgumentParser() parser.add_argument(--input, requiredTrue) parser.add_argument(--output, requiredTrue) args parser.parse_args() df pd.read_excel(args.input) with open(args.output, w, encodingutf-8) as f: f.write(df.to_markdown(indexFalse)) print(frows{len(df)}, cols{len(df.columns)}) if __name__ __main__: main()references/report_rules.md 里放格式规范比如字段说明的模板、单位约定、排序规则。这些内容只在需要时被读取平时不占 token。如果你用的是 Claude Code 这类客户端配置走 settings 文件把三件套写进去{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的密钥, ANTHROPIC_MODEL: 你的模型ID } }如果你用 Cline 配 MCP配置片段长这样Base URL、Key、Model ID 三件套一个都不能少{ mcpServers: { taotoken: { command: npx, args: [-y, your-mcp-server], env: { BASE_URL: https://taotoken.net/api, API_KEY: sk-你的密钥, MODEL_ID: 你的模型ID } } } }Codex 用户则改 auth.json同样三件套齐全{ base_url: https://taotoken.net/api, api_key: sk-你的密钥, model: 你的模型ID }写完这些目录结构应该是完整的四层。你可以用tree skill-name/检查一遍确认 SKILL.md 在根目录、脚本有可执行权限chmod x scripts/*.sh、references 文件名和正文里引用的一致。文件名不一致是最常见的坑正文写report_rules.md实际文件叫report-rule.mdAgent 读不到就会卡住。4. 验证请求与成功结果跑通一次完整调用链配置写完不算完得实际跑一遍确认链路通。验证分三层先验 API 通不通再验 SKILL 能否被路由最后验脚本和 references 是否按预期加载。第一层用 curl 直接打 API确认 Key 和 Base URL 正确curl -s https://taotoken.net/api/v1/messages \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: $TAOTOKEN_MODEL, max_tokens: 64, messages: [{role: user, content: 回复 ok}] }成功时返回 JSON 里能看到content字段和正常的文本。如果返回 401说明 Key 有问题返回 404多半是 Base URL 写错或路径不对。这一步过了说明接入层没问题。第二层把 SKILL 目录挂到你的 Agent 客户端里发一条触发指令比如「把这个 Excel 转成 Markdown./data/sample.xlsx」。观察 Agent 的行为它应该先判断需要加载 excel-to-md-report 这个技能然后按正文步骤执行。你可以在日志里看到它调用了 bash 启动 parse_excel.py脚本输出rows120, cols8这样的结果接着它读取 out.md 并核对行列数。第三层确认 references 是按需加载的。正常表现是Agent 执行到「读取 report_rules.md」那一步才发起 read 调用而不是一上来就把整个 references 目录读一遍。如果你看到它在第一步就把所有参考资料塞进上下文说明你的正文指令写得太笼统或者客户端不支持渐进式加载需要调整指令措辞明确「在第 N 步再读取」。成功的结果长这样终端里脚本打印行列数Agent 返回的最终消息里包含转换后的 Markdown 表格和字段说明段落格式符合 report_rules.md 的规范。整个过程你不需要手动干预也不需要重复解释规则。实测下来第一次跑通大概要调两三次指令措辞主要是让 Agent 准确理解「什么时候读哪个文件」。验证模型本身是否正常可以顺手在模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 发一条同样的指令做对照排除是客户端问题还是模型问题。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth跑不通的时候别慌大部分错误集中在几个固定位置。我按真实报错逐条给你对照。401 Unauthorized最常见。先检查 Key 是否复制完整有没有多空格再确认环境变量名和代码里读的是不是同一个比如你设了TAOTOKEN_API_KEY脚本里读的却是API_KEY。还有一种情况是 Key 被删了或过期回 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 重新生成一个换上。注意 Base URL 末尾不要多加/v1之外的路径写错也会表现为鉴权失败。local proxy failed这个报错通常出现在客户端配置了本地转发但目标地址不可达。检查你的 settings 或 MCP 配置里 Base URL 是不是写成了带多余端口的地址正确写法就是https://taotoken.net/api。另外确认本机网络能正常访问该域名用curl -I https://taotoken.net/api看返回状态码。如果客户端有「使用系统代理」的开关关掉再试避免请求被本地转发层拦截。reading choices 相关报错多出现在解析模型返回结构时比如脚本里硬编码了response[choices][0]但实际返回结构不是这个形状。先打印完整响应体看字段名再改取值逻辑。这类错误和 SKILL 本身无关是脚本对返回格式假设错了。建议脚本里加一层容错取不到 choices 时打印原始 JSON 并退出非零码方便定位。OAuth 相关报错如果你用的客户端走 OAuth 流程而不是直接填 Key报错往往提示 token 无效或回调失败。这种情况优先改用 API Key 直连方式把三件套写进 settings 或 auth.json绕开 OAuth 环节。确认配置里ANTHROPIC_AUTH_TOKEN和ANTHROPIC_BASE_URL成对出现缺一个就会走到默认的 OAuth 路径上去。还有一个隐蔽的坑SKILL.md 里引用的脚本路径是相对路径但 Agent 执行时的工作目录可能不是 SKILL 根目录。解决办法是在正文里写清楚「在 SKILL 根目录下执行」或者脚本内部用os.path.dirname(__file__)定位自身位置再拼路径。文件名大小写也要注意Linux 下Report_Rules.md和report_rules.md是两个文件。排障顺序建议固定先 curl 验 API再验客户端配置最后验 SKILL 内部引用。每层单独确认别一上来就怀疑模型。接入细节以文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 为准遇到没见过的报错先去文档搜关键词。6. 把 SKILL 用起来从单技能到可复用能力包一个 SKILL 跑通之后真正的价值在于复用和组合。你可以把多个 SKILL 放在同一个技能目录下Agent 根据 description 自动路由用户不需要记住每个技能叫什么。比如「Excel 转 Markdown」「PDF 提取文本」「图片生成说明」三个技能并存用户说「把这份 PDF 整理成带图的报告」Agent 会依次加载相关技能脚本各干各的references 各读各的上下文只在需要时增长。写 description 时多解释「为什么」而不是用命令口吻。别写「你必须先读规则文件」改成「因为报告格式有统一规范转换前先读取 references/report_rules.md 可以保证输出一致」。Agent 理解了原因遇到边界情况时判断更稳。给出改前改后的对比示例也比纯规则描述有效得多——具体例子比「必须」两个字管用一万倍。长期跑编码和 Agent 任务的话Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 在调用频率和稳定性上更合适只是偶尔验证模型行为用模型对话页就够。密钥管理和新建 Key 都在控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 完成接入参数有疑问查文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。最后给你一个自查清单建完 SKILL 逐项打勾SKILL.md 元数据用---包裹且 name/description 齐全正文有触发条件、工作流程、规则三段scripts 下脚本有可执行权限且路径与正文一致references 文件名与正文引用逐字匹配三件套在配置里成对出现curl 能通触发指令能路由到技能脚本输出行列数与源文件一致references 在预期步骤才被读取。全过一遍这个 SKILL 就算可用了。