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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 端点是 https://taotoken.net/api ，注意这个地址后面不加任何查询参数。
第一步，打开控制台创建密钥。控制台入口是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，登录后在 API Keys 页面点新建，复制那串以 sk- 开头的 Key，存到本地环境变量里，别直接写进代码提交。API Keys 直达页是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，后面排障时你还会回到这里核对 Key 是否失效。
第二步，确认你要用的模型 ID。不同模型对工具调用的支持程度不一样，SKILL 里如果涉及脚本执行和文件读取，建议选工具调用能力完整的模型。模型列表可以在模型对话页 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite 里先试一轮，确认能正常返回再写进配置。
第三步，把三件套记牢：Base URL、API Key、Model ID。这三样在后面的 settings、auth.json、MCP 配置里会反复出现，任何一处写错都会导致 401 或模型找不到。我建议你在本地建一个.env文件统一管理：
# .env 仅本地使用，务必加入 .gitignore TAOTOKEN_BASE_URL=https://taotoken.net/api TAOTOKEN_API_KEY=sk-你的密钥 TAOTOKEN_MODEL=你的模型ID如果你打算长期跑编码类 Agent 任务，比如让 SKILL 驱动代码生成和校验，可以看下 Coding Plan 页面 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，它更适合高频调用场景。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，遇到参数不确定时以文档为准。
这里提醒一句：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", required=True) parser.add_argument("--output", required=True) args = parser.parse_args() df = pd.read_excel(args.input) with open(args.output, "w", encoding="utf-8") as f: f.write(df.to_markdown(index=False)) print(f"rows={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.md，Agent 读不到就会卡住。
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，脚本输出rows=120, cols=8这样的结果，接着它读取 out.md 并核对行列数。
第三层，确认 references 是按需加载的。正常表现是：Agent 执行到「读取 report_rules.md」那一步才发起 read 调用，而不是一上来就把整个 references 目录读一遍。如果你看到它在第一步就把所有参考资料塞进上下文，说明你的正文指令写得太笼统，或者客户端不支持渐进式加载，需要调整指令措辞，明确「在第 N 步再读取」。
成功的结果长这样：终端里脚本打印行列数，Agent 返回的最终消息里包含转换后的 Markdown 表格和字段说明段落，格式符合 report_rules.md 的规范。整个过程你不需要手动干预，也不需要重复解释规则。实测下来，第一次跑通大概要调两三次指令措辞，主要是让 Agent 准确理解「什么时候读哪个文件」。
验证模型本身是否正常，可以顺手在模型对话页 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite 发一条同样的指令做对照，排除是客户端问题还是模型问题。
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_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 重新生成一个换上。注意 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_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 为准，遇到没见过的报错先去文档搜关键词。
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_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 在调用频率和稳定性上更合适；只是偶尔验证模型行为，用模型对话页就够。密钥管理和新建 Key 都在控制台 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite 完成，接入参数有疑问查文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。
最后给你一个自查清单，建完 SKILL 逐项打勾：SKILL.md 元数据用---包裹且 name/description 齐全；正文有触发条件、工作流程、规则三段；scripts 下脚本有可执行权限且路径与正文一致；references 文件名与正文引用逐字匹配；三件套在配置里成对出现；curl 能通；触发指令能路由到技能；脚本输出行列数与源文件一致；references 在预期步骤才被读取。全过一遍，这个 SKILL 就算可用了。
