1. 为什么你的 Agent 装了 Skill 却像没装从 SKILL.md 规范说起很多人第一次接触 AI Agent 的 Skill 机制是在某个开源仓库里下载了一堆技能包往skills/目录一丢重启 Agent然后发现——它压根不调用。或者偶尔调用了输出的东西跟预期差了十万八千里。问题往往不在 Agent 本身而在于你写的SKILL.md没有遵守规范或者根本没有理解 Skill 的加载逻辑。Skill 本质上是一个“按需加载的专家模块”。Agent 在启动时并不会把所有技能的完整内容读进上下文它只扫描每个技能的元数据name description建立一个“能力地图”。当你的输入和某个技能的 description 匹配时Agent 才会加载该技能的完整指令和资源。这意味着description 写得好不好直接决定你的技能会不会被触发。我见过太多人把 description 写成“一个有用的工具”或者“帮助处理文件”这种描述在意图匹配阶段就是噪音Agent 根本不知道什么时候该用它。另一个常见误区是把 Skill 当成 Prompt 模板来写。Skill 不是一段静态的提示词它是一个包含角色定义、执行流程、工具调用、输出规范、错误处理的完整“操作手册”。你需要用祈使句告诉 Agent 每一步做什么在什么条件下走哪个分支遇到异常怎么回退。这跟写一份给新员工的 SOP 是一个道理——你不能只写“帮我处理一下数据”你得写“第一步读取 CSV第二步检查缺失值如果缺失率超过 30% 则输出警告并终止”。这篇内容面向的是想让 Agent 真正落地的开发者。我会从SKILL.md的结构规范讲起带你理解渐进式披露的设计哲学然后手把手用skill-creator创建一个可用的技能最后给出加载验证和常见报错排查。你不需要有 Agent 开发经验但需要能看懂 YAML 和 Markdown并且愿意动手试。在开始之前先明确一个概念Skill 的“渐进式披露”不是玄学它对应的是三层加载机制——元数据层负责触发指令层负责规划资源层负责执行。你写的每一部分内容都会在特定的阶段被 Agent 读取。理解了这个你才知道为什么SKILL.md的格式要求那么严格为什么name必须和文件夹一致为什么description有 1024 字符的上限。2. 前置准备TaoToken 接入与 skill-creator 获取在动手写 Skill 之前你需要一个能加载 Skill 的 Agent 环境。目前支持 Skill 机制的 Agent 包括 Claude Code、opencode、Cursor 等它们对 Skill 的加载路径和触发方式略有差异但核心逻辑一致。为了让后续的配置和验证有统一的入口我建议通过 TaoToken 来管理模型调用和 API Key这样你在测试 Skill 时不用反复切换配置。TaoToken 的定位是 AI 模型调用的统一接入层它兼容 OpenAI 风格的 API 格式同时支持 Claude 系列模型的调用。对于 Skill 开发来说最关键的是它能让你在本地 Agent 中稳定地调用模型并且可以通过 API Key 做权限和额度的管理。你不需要在多个平台之间来回切换也不用担心某个模型的接口突然不可用。首先访问 TaoToken 官网完成注册https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。注册完成后进入控制台创建 API Key。这个 Key 是你后续在 Agent 配置中填写的凭证格式通常以sk-开头。创建时建议给 Key 起一个容易识别的名字比如skill-dev-test方便后续排查问题时定位。拿到 Key 之后你需要确认两件事Base URL 和 Model ID。TaoToken 的 API 端点是不带 UTM 参数的干净地址https://taotoken.net/api 。Model ID 取决于你要调用的模型比如claude-sonnet-4-20250514或者gpt-4o。这三个要素——Base URL、API Key、Model ID——是任何 Agent 接入模型时的“三件套”缺一不可。如果你用的是 Claude Code它的配置文件通常在~/.claude/settings.json或者项目级的.claude/settings.json如果你用的是 opencode配置在~/.config/opencode/config.json或者项目级的.opencode/config.json。接下来获取skill-creator。这是 Anthropic 官方提供的一个“用来创建 Skill 的 Skill”它的作用是你用自然语言描述需求它帮你生成符合规范的SKILL.md和目录结构。下载地址在 Anthropic 的官方仓库https://github.com/anthropics/skills/tree/main/skills/skill-creator 。你可以直接 clone 整个仓库也可以只下载skill-creator文件夹。下载后把它放到你的 Agent 的全局 skills 目录下。以 opencode 为例全局 skills 目录通常是~/.config/opencode/skills/以 Claude Code 为例通常是~/.claude/skills/。放进去之后重启 Agentskill-creator就会被加载。如果你暂时不想下载skill-creator也可以手动创建 Skill 文件夹和SKILL.md但自动创建能帮你省去格式检查的麻烦尤其是 YAML frontmatter 的缩进和字段名容易写错。我建议先用skill-creator跑通一个完整流程再回头理解手动创建的细节。3. 可复制配置SKILL.md 模板与 skill-creator 配置片段这一节给你可以直接复制粘贴的配置。先看SKILL.md的完整模板这个模板遵循了 YAML Frontmatter Markdown Body 的结构字段名和格式都符合官方规范。你可以把下面的内容保存为SKILL.md放在你的技能文件夹根目录下。--- name: weekly-report-generator description: 根据项目 git log、todo 文件和用户输入生成本周项目周报。当用户说“生成本周周报”“总结本周进展”或“帮我写周报”时触发。 version: 1.0.0 author: your-name allowed-tools: - Bash - Read - Write license: MIT compatibility: Requires Python 3.11 and git metadata: category: productivity trigger-keywords: - 周报 - 本周进展 - 项目总结 --- # 项目周报生成器 ## 角色定义 你是一名严谨的项目管理助理擅长从多源数据中提取关键信息并按照标准模板生成结构化的项目周报。 ## 核心指令 请严格按照以下步骤执行任务 1. **收集数据** - 询问用户本周的时间范围默认本周一到周日 - 读取项目 git log提取本周的提交记录 - 检查项目根目录是否存在 problems.md、growth.md、knowledge.md 文件 - 如果上述文件不存在询问用户是否有额外内容需要补充 2. **处理数据** - 使用 scripts/git-analyzer.py 分析 git 提交提取提交数、参与人数、关键变更 - 使用 scripts/todo-parser.py 解析 todo 文件整理完成情况 - 使用 scripts/data-aggregator.py 聚合所有数据支持 --project-dir 参数指定项目目录 - 参考 references/data-extraction.md 了解详细的数据提取方法 3. **组织周报结构** - 参考 references/report-structure.md 了解周报的标准结构 - 将数据组织成以下模块数据统计、本周进展、本周遇到的问题、本周个人成长、相关知识分享、下周计划、风险与问题 4. **生成报告** - 使用 assets/report-template.html 作为模板 - 将结构化数据填充到模板中 - 生成 HTML 格式的周报文件weekly-report-YYYY-MM-DD.html - 使用 scripts/html-to-pdf.py 将 HTML 转换为 PDF ## 输出格式 - 必须包含数据统计、本周进展、问题与风险、下周计划 - 风格专业、简洁、数据驱动 - 文件命名weekly-report-YYYY-MM-DD.html 和 weekly-report-YYYY-MM-DD.pdf ## 示例 **用户输入**帮我生成本周的周报 **你的回答**正在收集本周数据……已读取 git log共 23 次提交5 位参与者。正在生成周报文件…… ## 错误处理 - 如果项目不是 git 仓库跳过 git log 分析提醒用户手动输入关键进展 - 如果没有 todo 文件提醒用户手动输入本周完成事项 - 如果 PDF 生成失败检查是否安装了 Chrome 或 Chromium并输出 HTML 文件作为备选这个模板里name必须和文件夹名称完全一致比如文件夹叫weekly-report-generatorname就写weekly-report-generator。description是触发匹配的核心我写了功能、触发场景和触发词这样 Agent 在意图识别时能更准确地匹配。allowed-tools声明了技能可以自动使用的工具避免每次调用脚本都弹确认。接下来是skill-creator的配置片段。如果你用的是 opencode在项目根目录创建.opencode/config.json内容如下{ model: claude-sonnet-4-20250514, provider: { baseURL: https://taotoken.net/api, apiKey: sk-your-taoToken-api-key }, skills: { directory: .opencode/skills, autoLoad: true } }如果你用的是 Claude Code配置文件在~/.claude/settings.json格式略有不同{ model: claude-sonnet-4-20250514, apiKey: sk-your-taoToken-api-key, baseURL: https://taotoken.net/api, skills: { path: ~/.claude/skills, enabled: true } }注意baseURL不要带 UTM 参数就用https://taotoken.net/api。apiKey替换成你在 TaoToken 控制台创建的那个 Key。model字段填你要调用的模型 ID如果你不确定当前有哪些模型可用可以访问模型对话页面查看https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。配置写好后把skill-creator文件夹放到.opencode/skills/或者~/.claude/skills/下。重启 Agent然后在输入框里输入/skill-creator如果配置正确Agent 会加载这个技能并等待你描述需求。你可以输入“使用这个创建一个 SKILL需求是根据 PRD 文档生成测试用例包含正常流程、边界条件和异常场景。”skill-creator会引导你完成后续步骤。4. 验证请求与成功结果从创建到加载的完整链路配置写好了技能也创建了怎么确认它真的被 Agent 加载并正确调用了这一节给你一套可复现的验证流程。我以 opencode 为例Claude Code 的操作逻辑类似只是路径和命令略有差异。第一步确认技能文件夹结构正确。在项目根目录下你的技能应该长这样.opencode/ └── skills/ └── weekly-report-generator/ ├── SKILL.md ├── scripts/ │ ├── git-analyzer.py │ ├── todo-parser.py │ └── data-aggregator.py ├── references/ │ ├── data-extraction.md │ └── report-structure.md └── assets/ └── report-template.htmlSKILL.md必须在技能文件夹的根目录不能嵌套在子文件夹里。scripts/、references/、assets/都是可选的但如果你在SKILL.md里引用了它们就必须保证路径正确。我踩过的坑之一是把references/写成了reference/Agent 加载时找不到文件直接报错退出。第二步重启 Agent。在项目目录下打开终端输入opencode启动。启动过程中Agent 会扫描.opencode/skills/下的所有技能读取每个SKILL.md的元数据。你可以在启动日志里看到类似Loaded skill: weekly-report-generator的输出。如果没有这行日志说明技能没有被扫描到检查文件夹路径和SKILL.md的 YAML 格式。第三步触发技能。在 Agent 输入框里输入“帮我生成本周的周报”。如果description匹配成功Agent 会加载weekly-report-generator的完整指令然后按照SKILL.md里的步骤执行。你会看到它先询问时间范围然后调用scripts/git-analyzer.py分析 git log接着读取references/report-structure.md最后生成 HTML 和 PDF 文件。第四步验证输出。检查项目根目录下是否生成了weekly-report-2025-06-15.html和对应的 PDF 文件。打开 HTML 文件确认内容包含数据统计、本周进展、问题与风险、下周计划等模块。如果 PDF 没有生成检查scripts/html-to-pdf.py的依赖是否安装比如weasyprint或者playwright。如果你用的是 Claude Code验证方式类似但触发命令可能是/weekly-report-generator或者直接自然语言触发。Claude Code 的技能加载日志在~/.claude/logs/下你可以用tail -f实时查看。如果技能没有被触发先检查description是否包含了用户可能说的关键词比如“周报”“本周进展”“项目总结”。description 写得太窄匹配不到写得太宽又会误触发。一个更直接的验证方法是手动调用技能。在 opencode 中输入/skills查看已加载的技能列表确认weekly-report-generator在列表中。然后输入/weekly-report-generator强制调用观察 Agent 是否按照SKILL.md的指令执行。如果强制调用成功但自然语言触发失败问题一定出在description的匹配逻辑上。5. 常见报错排查401、local proxy failed、reading choices、OAuth技能开发过程中报错主要集中在模型接入和技能加载两个环节。这一节列出我遇到过的真实报错和排查路径你可以对照自己的情况定位。报错一401 UnauthorizedError: 401 Unauthorized {error:{message:Invalid API key,type:invalid_request_error}}这个报错说明 API Key 无效或者没有正确传递。检查三个地方第一config.json里的apiKey字段是否填了完整的 Key有没有多余的空格或换行第二Key 是否已经过期或者被删除去 TaoToken 控制台的 API Keys 页面确认https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 第三baseURL是否写成了https://taotoken.net/api不要加尾部斜杠也不要带 UTM 参数。如果用的是 Claude Code检查settings.json里的apiKey字段名是否正确有些版本要求写成anthropicApiKey。报错二local proxy failedError: local proxy failed: connection refused这个报错通常出现在 Agent 尝试通过本地代理转发请求时。检查你的系统环境变量里是否有HTTP_PROXY或HTTPS_PROXY的设置如果有暂时取消掉再重启 Agent。另外确认baseURL是https://taotoken.net/api而不是http://localhost:xxxx之类的本地地址。如果你在 Docker 容器里运行 Agent检查容器的网络模式是否允许访问外部 API。报错三reading choicesError: reading choices: unexpected end of JSON input这个报错说明 API 返回的响应格式不符合预期通常是模型 ID 写错了或者请求体里的model字段和实际可用的模型不匹配。检查config.json里的model字段确认它和 TaoToken 支持的模型 ID 一致。你可以访问模型对话页面测试一下当前 Key 能调用哪些模型https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。如果模型 ID 正确但依然报错检查请求的max_tokens是否设置过大超出了模型的上下文限制。报错四OAuth token expiredError: OAuth token expired, please re-authenticate这个报错出现在 Claude Code 使用 OAuth 认证而不是 API Key 认证时。如果你已经配置了 TaoToken 的 API Key就不应该再走 OAuth 流程。检查settings.json里是否同时存在apiKey和oauthToken字段如果有删除oauthToken相关的配置。然后重启 Claude Code确保它读取的是 API Key 而不是缓存的 OAuth token。如果问题依旧删除~/.claude/下的缓存文件重新登录。报错五Skill not loadedWarning: Skill weekly-report-generator not found in skills directory这个报错说明 Agent 没有扫描到你的技能文件夹。检查三点第一技能文件夹是否放在了正确的 skills 目录下opencode 是.opencode/skills/Claude Code 是~/.claude/skills/第二SKILL.md的 YAML frontmatter 是否格式正确name字段是否和文件夹名称完全一致第三description字段是否为空空 description 会导致技能被跳过。你可以用cat SKILL.md | head -20快速检查 frontmatter 的前几行。排查完这些报错后如果你需要更详细的接入文档可以访问 TaoToken 的文档页面https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。文档里有完整的 API 参数说明和示例请求能帮你快速定位配置问题。6. 渐进式披露的工程实现与长期编码建议理解了SKILL.md的写法和验证流程之后你需要回头理解“渐进式披露”在工程上到底是怎么实现的。这不是一个抽象概念它直接决定了你的技能在什么阶段被加载、加载多少内容、以及如何影响 Agent 的推理路径。Agent 启动时只会把所有技能的name和description读进上下文形成一个“技能索引”。这个索引很小通常几百个技能也只占几千 token。当用户输入到达时Agent 的意图识别模块会拿用户输入和每个技能的description做匹配匹配度超过阈值的技能才会被“激活”。激活后Agent 读取该技能的完整SKILL.md正文把角色定义、核心指令、输出格式注入到当前对话的上下文中。此时Agent 的“思维框架”被临时重塑它不再用通用的方式回答问题而是按照技能定义的 SOP 执行。如果技能指令里引用了scripts/下的脚本Agent 会在需要执行确定性操作时调用这些脚本。脚本的运行结果会作为工具输出返回给 AgentAgent 再根据结果决定下一步。如果指令里引用了references/下的文档Agent 会在需要查阅详细规则时读取这些文档。这些文档不会在技能激活时全部加载而是按需读取这就是“渐进式”的含义——不是一次性把所有内容塞进上下文而是根据执行进度逐步加载。这种设计的好处是上下文利用率高。一个复杂的技能可能包含几千行的参考文档但 Agent 只在真正需要时才读取相关部分避免了上下文窗口被无关信息占满。坏处是对SKILL.md的指令清晰度要求极高因为 Agent 不知道你的“言外之意”它只能严格按照你写的步骤执行。如果你在指令里写“根据需要处理数据”Agent 会困惑如果你写“如果 CSV 文件缺失率超过 30%输出警告并终止”Agent 就能准确执行。对于长期做 Agent 开发的团队我建议把技能开发纳入版本管理。每个技能文件夹就是一个独立的代码仓库SKILL.md是接口文档scripts/是业务逻辑references/是知识库。技能之间的依赖关系通过description的触发词来协调避免多个技能同时被激活导致指令冲突。如果你需要频繁调用模型来测试技能可以考虑使用 Coding Plan 来管理调用额度https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。它适合需要长期、高频调用模型的开发场景比按次计费更划算。最后技能开发不是一劳永逸的事。Agent 的意图识别模型会更新用户的表达方式会变化你的description和触发词也需要迭代。建议每次修改SKILL.md后用一组固定的测试用例跑一遍确认技能依然能被正确触发和执行。测试用例可以包括自然语言触发、强制命令触发、边界条件触发、错误处理触发。只有这四类都通过技能才算真正可用。