1. 当 Agent 能力越堆越多为什么反而变笨了如果你最近在 Claude Code、Cursor 或者 OpenCode 里给 AI Agent 加过能力大概率遇到过这个场景一开始只挂两三个工具Agent 干活又快又准后来你把团队里所有脚本、规范、模板都塞进系统提示词结果它开始答非所问明明该调用 A 技能却调了 B甚至把不相关的流程也硬套进来。问题不在模型而在组织方式。所有能力都平铺在上下文里Agent 每次启动都要把全部内容读一遍token 消耗暴涨注意力被稀释调用自然混乱。这就像你给一个新员工一本没有目录、没有章节、所有内容糊在一起的万字手册他找一条报销规则要翻半小时。Agent Skills 想解决的就是这件事。它把能力拆成一个个独立文件夹每个文件夹里放一份SKILL.md作为入口Agent 启动时只读每个技能的name和description相当于先看目录等任务真正匹配到某个技能才加载完整正文。这个机制叫渐进式上下文加载Progressive Disclosure是 Skills 区别于普通提示词模板的核心。这篇面向已经在用 Claude Code 等工具、想让 Agent 能力可维护的开发者。我会先讲清楚SKILL.md的目录骨架再给出技能注册配置的可复制片段最后演示新增一个技能后怎么验证 Agent 能正确命中它。全程围绕“带目录说明书”这个思路展开不堆概念。2. 前置准备TaoToken 接入与 Skills 运行环境在动手写技能之前得先让 Claude Code 这类工具能稳定跑起来。我自己的做法是通过 TaoToken 统一接入模型好处是 API Key 和接入地址集中管理后面切换模型或做多技能验证时不用反复改配置。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数配置时直接填这个。你需要先拿到 API Key。登录后进入控制台在 API Keys 页面创建一个新 Key复制保存。这个 Key 就是后面settings.json里的ANTHROPIC_AUTH_TOKEN。Claude Code 的配置目录在用户主目录下的~/.claude/。如果目录不存在就手动创建。核心是settings.json它负责告诉 Claude Code 用哪个后端、超时多久、是否关闭非必要流量。下面是我实测可用的配置片段{ env: { ANTHROPIC_AUTH_TOKEN: 你的 TaoToken API Key, ANTHROPIC_BASE_URL: https://taotoken.net/api, API_TIMEOUT_MS: 3000000, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: 1 } }这里ANTHROPIC_BASE_URL填 TaoToken 的 API 地址API_TIMEOUT_MS设大一点因为技能执行时可能涉及脚本运行和多次模型往返超时太短会中途断掉。CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC设为 1 可以关掉一些非必要的遥测请求让日志更干净。另外还要处理首次登录引导。在~/.claude.json里加上{ hasCompletedOnboarding: true }这样启动时不会卡在登录流程。配置完成后在终端执行claude能正常进入对话就说明后端通了。如果这一步报 401 或连接超时先检查 Key 是否复制完整、API 地址有没有多带斜杠。提示TaoToken 的接入文档在 https://taotoken.net/doc 里面有各语言 SDK 和常见报错说明配置卡住时可以先翻这里。3. SKILL.md 目录骨架与技能注册配置Skills 的本质是一个文件夹SKILL.md是必须的入口文件其余目录都是可选的资源。一个标准的技能目录长这样my-skill/ ├── SKILL.md # 必须元数据 执行说明 ├── scripts/ # 可选可执行脚本 ├── references/ # 可选参考文档 └── assets/ # 可选模板与资源SKILL.md的结构分两部分顶部的 YAML frontmatter 和下面的 Markdown 正文。frontmatter 负责技能发现与匹配正文负责执行说明。骨架如下--- name: bill-analysis description: 读取账单截图OCR 提取文字清洗后导出报销用 CSV。当用户需要汇总账单、生成报销单时使用。 --- # 账单分析 ## 何时使用 当用户提供账单图片或文件夹路径并要求汇总、报销、导出表格时使用本技能。 ## 执行步骤 1. 读取输入路径下的 png、jpg、pdf 文件 2. 调用 OCR 提取文字 3. 抽取商户名称、消费日期、金额、支付方式 4. 去重并导出 CSV表头为序号 | 商户名称 | 消费日期 | 金额(元) | 支付方式 | 备注 ## 注意事项 - 金额统一保留两位小数 - 日期格式统一为 YYYY-MM-DD - 无法识别的条目单独列出不要丢弃name和description是 Agent 启动时唯一会读到的字段所以 description 要写清楚“做什么”和“什么时候用”这是命中率的关键。正文只在技能被激活后才加载可以写得很细。技能注册有两种方式。一种是放在 Claude Code 默认扫描的技能目录下通常是~/.claude/skills/每个技能一个子文件夹。另一种是在项目根目录建.claude/skills/只对当前项目生效。我一般把通用技能放全局项目专属的放项目里。注册后可以用一个清单文件做索引方便自己管理{ skills: [ { name: bill-analysis, path: ~/.claude/skills/bill-analysis, enabled: true }, { name: commit-work, path: ~/.claude/skills/commit-work, enabled: true } ] }这个清单不是 Claude Code 强制要求的但当你技能多了以后用它来记录哪些启用、哪些停用比翻目录快得多。4. 验证请求新增技能后 Agent 能否正确命中写完技能不算完得验证 Agent 真的会在合适的时候调用它。我新增一个“日志分析”技能来演示完整流程。先创建目录和文件mkdir -p ~/.claude/skills/log-analysis然后写入SKILL.md--- name: log-analysis description: 分析应用日志文件统计错误类型、出现频次和首次出现时间。当用户提供 .log 文件并要求排查错误、统计异常时使用。 --- # 日志分析 ## 何时使用 用户提供日志文件路径要求统计错误、定位异常、分析频次时使用。 ## 执行步骤 1. 读取指定 .log 文件 2. 用正则匹配 ERROR、WARN、FATAL 级别行 3. 按错误信息聚合统计出现次数 4. 记录每条错误的首次出现时间 5. 输出 Markdown 表格错误信息 | 级别 | 次数 | 首次出现 ## 注意事项 - 大文件按行流式读取避免一次性载入内存 - 时间戳格式不统一时先归一化保存后重启 Claude Code让它重新扫描技能目录。然后发一条测试请求帮我分析 /tmp/app.log统计里面的错误类型和出现次数如果命中成功Agent 会先说明它要使用 log-analysis 技能然后按步骤执行最后输出一张错误统计表。如果它没有调用技能而是自己临时写了一段分析逻辑说明 description 没匹配上需要调整措辞把用户可能说的关键词日志、错误、统计、排查都覆盖进去。再测一个反向用例确认不会误触发帮我分析一下这段 Python 代码的性能这条请求里没有日志文件也没有排查错误的需求Agent 不应该调用 log-analysis。如果它调用了说明 description 写得太宽泛需要加上“当用户提供 .log 文件时”这类限定条件。实测下来命中率主要取决于 description 的精准度。我的经验是把“做什么”和“触发条件”分开写触发条件里尽量包含用户的原话词汇。5. 本篇常见错排查技能不生效时按下面几个方向逐个排查。技能没被扫描到。检查目录层级是否正确。Claude Code 扫描的是~/.claude/skills/下的直接子目录每个子目录里必须有SKILL.md。如果你把技能放在~/.claude/skills/foo/bar/SKILL.md它可能扫不到。用ls ~/.claude/skills/*/SKILL.md确认每个技能入口都在。frontmatter 格式错误。YAML 对缩进和冒号很敏感。name和description必须顶格冒号后面要有空格。如果 description 里含冒号要用引号包起来。可以用在线 YAML 校验工具过一遍或者直接看 Claude Code 启动日志里有没有解析报错。description 匹配不上。这是最常见的问题。Agent 只靠 name 和 description 做匹配正文它看不到。所以 description 要写成“用户会怎么描述这个需求”的样子而不是“这个技能技术上做了什么”。比如写“当用户需要汇总账单、生成报销单时使用”比写“基于 OCR 的账单处理”命中率高得多。技能之间互相抢。如果两个技能的 description 覆盖了相似场景Agent 可能随机选一个。解决办法是在 description 里加排他条件比如“仅当输入为图片时使用”“仅当涉及 Git 提交时使用”。脚本执行失败。如果技能正文里调用了scripts/下的脚本要确认脚本有执行权限依赖也装好了。Skills 比 MCP 更依赖本地环境脚本路径写相对路径时基准目录是技能文件夹本身不是项目根目录。改了 SKILL.md 不生效。Claude Code 在启动时加载技能元数据改完要重启。如果只想快速验证可以退出当前会话重新进。注意排查时优先看 Claude Code 的启动输出它会打印加载了哪些技能。如果某个技能没出现在列表里问题一定在目录结构或 frontmatter而不是 description。6. 把技能组织成可检索的目录才是长期解法回到开头那个问题能力堆叠后 Agent 变笨根因是上下文没有分层。Skills 用SKILL.md做入口、用 frontmatter 做索引、用渐进式加载做按需读取本质上是给 Agent 装了一份带目录的说明书。目录负责“找得到”正文负责“做得好”两者分开上下文就不会膨胀。如果你打算把这套东西用在长期编码或 Agent 工作流里建议配合 Coding Plan 来管理调用额度入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。日常验证模型对技能的理解是否到位可以直接在模型对话里试地址是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。需要新建或轮换 Key 时去 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。我自己的习惯是每加一个技能先写 description再写正文最后一定跑一遍正向和反向用例。description 改三遍以上是常事但改完之后 Agent 的调用准确率会明显不一样。技能多了以后维护那份清单文件比什么都重要它就是你这份说明书的目录页。
Agent Skills 实战：用 SKILL.md 给 AI Agent 装一份可检索的“带目录说明书”
1. 当 Agent 能力越堆越多为什么反而变笨了如果你最近在 Claude Code、Cursor 或者 OpenCode 里给 AI Agent 加过能力大概率遇到过这个场景一开始只挂两三个工具Agent 干活又快又准后来你把团队里所有脚本、规范、模板都塞进系统提示词结果它开始答非所问明明该调用 A 技能却调了 B甚至把不相关的流程也硬套进来。问题不在模型而在组织方式。所有能力都平铺在上下文里Agent 每次启动都要把全部内容读一遍token 消耗暴涨注意力被稀释调用自然混乱。这就像你给一个新员工一本没有目录、没有章节、所有内容糊在一起的万字手册他找一条报销规则要翻半小时。Agent Skills 想解决的就是这件事。它把能力拆成一个个独立文件夹每个文件夹里放一份SKILL.md作为入口Agent 启动时只读每个技能的name和description相当于先看目录等任务真正匹配到某个技能才加载完整正文。这个机制叫渐进式上下文加载Progressive Disclosure是 Skills 区别于普通提示词模板的核心。这篇面向已经在用 Claude Code 等工具、想让 Agent 能力可维护的开发者。我会先讲清楚SKILL.md的目录骨架再给出技能注册配置的可复制片段最后演示新增一个技能后怎么验证 Agent 能正确命中它。全程围绕“带目录说明书”这个思路展开不堆概念。2. 前置准备TaoToken 接入与 Skills 运行环境在动手写技能之前得先让 Claude Code 这类工具能稳定跑起来。我自己的做法是通过 TaoToken 统一接入模型好处是 API Key 和接入地址集中管理后面切换模型或做多技能验证时不用反复改配置。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数配置时直接填这个。你需要先拿到 API Key。登录后进入控制台在 API Keys 页面创建一个新 Key复制保存。这个 Key 就是后面settings.json里的ANTHROPIC_AUTH_TOKEN。Claude Code 的配置目录在用户主目录下的~/.claude/。如果目录不存在就手动创建。核心是settings.json它负责告诉 Claude Code 用哪个后端、超时多久、是否关闭非必要流量。下面是我实测可用的配置片段{ env: { ANTHROPIC_AUTH_TOKEN: 你的 TaoToken API Key, ANTHROPIC_BASE_URL: https://taotoken.net/api, API_TIMEOUT_MS: 3000000, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: 1 } }这里ANTHROPIC_BASE_URL填 TaoToken 的 API 地址API_TIMEOUT_MS设大一点因为技能执行时可能涉及脚本运行和多次模型往返超时太短会中途断掉。CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC设为 1 可以关掉一些非必要的遥测请求让日志更干净。另外还要处理首次登录引导。在~/.claude.json里加上{ hasCompletedOnboarding: true }这样启动时不会卡在登录流程。配置完成后在终端执行claude能正常进入对话就说明后端通了。如果这一步报 401 或连接超时先检查 Key 是否复制完整、API 地址有没有多带斜杠。提示TaoToken 的接入文档在 https://taotoken.net/doc 里面有各语言 SDK 和常见报错说明配置卡住时可以先翻这里。3. SKILL.md 目录骨架与技能注册配置Skills 的本质是一个文件夹SKILL.md是必须的入口文件其余目录都是可选的资源。一个标准的技能目录长这样my-skill/ ├── SKILL.md # 必须元数据 执行说明 ├── scripts/ # 可选可执行脚本 ├── references/ # 可选参考文档 └── assets/ # 可选模板与资源SKILL.md的结构分两部分顶部的 YAML frontmatter 和下面的 Markdown 正文。frontmatter 负责技能发现与匹配正文负责执行说明。骨架如下--- name: bill-analysis description: 读取账单截图OCR 提取文字清洗后导出报销用 CSV。当用户需要汇总账单、生成报销单时使用。 --- # 账单分析 ## 何时使用 当用户提供账单图片或文件夹路径并要求汇总、报销、导出表格时使用本技能。 ## 执行步骤 1. 读取输入路径下的 png、jpg、pdf 文件 2. 调用 OCR 提取文字 3. 抽取商户名称、消费日期、金额、支付方式 4. 去重并导出 CSV表头为序号 | 商户名称 | 消费日期 | 金额(元) | 支付方式 | 备注 ## 注意事项 - 金额统一保留两位小数 - 日期格式统一为 YYYY-MM-DD - 无法识别的条目单独列出不要丢弃name和description是 Agent 启动时唯一会读到的字段所以 description 要写清楚“做什么”和“什么时候用”这是命中率的关键。正文只在技能被激活后才加载可以写得很细。技能注册有两种方式。一种是放在 Claude Code 默认扫描的技能目录下通常是~/.claude/skills/每个技能一个子文件夹。另一种是在项目根目录建.claude/skills/只对当前项目生效。我一般把通用技能放全局项目专属的放项目里。注册后可以用一个清单文件做索引方便自己管理{ skills: [ { name: bill-analysis, path: ~/.claude/skills/bill-analysis, enabled: true }, { name: commit-work, path: ~/.claude/skills/commit-work, enabled: true } ] }这个清单不是 Claude Code 强制要求的但当你技能多了以后用它来记录哪些启用、哪些停用比翻目录快得多。4. 验证请求新增技能后 Agent 能否正确命中写完技能不算完得验证 Agent 真的会在合适的时候调用它。我新增一个“日志分析”技能来演示完整流程。先创建目录和文件mkdir -p ~/.claude/skills/log-analysis然后写入SKILL.md--- name: log-analysis description: 分析应用日志文件统计错误类型、出现频次和首次出现时间。当用户提供 .log 文件并要求排查错误、统计异常时使用。 --- # 日志分析 ## 何时使用 用户提供日志文件路径要求统计错误、定位异常、分析频次时使用。 ## 执行步骤 1. 读取指定 .log 文件 2. 用正则匹配 ERROR、WARN、FATAL 级别行 3. 按错误信息聚合统计出现次数 4. 记录每条错误的首次出现时间 5. 输出 Markdown 表格错误信息 | 级别 | 次数 | 首次出现 ## 注意事项 - 大文件按行流式读取避免一次性载入内存 - 时间戳格式不统一时先归一化保存后重启 Claude Code让它重新扫描技能目录。然后发一条测试请求帮我分析 /tmp/app.log统计里面的错误类型和出现次数如果命中成功Agent 会先说明它要使用 log-analysis 技能然后按步骤执行最后输出一张错误统计表。如果它没有调用技能而是自己临时写了一段分析逻辑说明 description 没匹配上需要调整措辞把用户可能说的关键词日志、错误、统计、排查都覆盖进去。再测一个反向用例确认不会误触发帮我分析一下这段 Python 代码的性能这条请求里没有日志文件也没有排查错误的需求Agent 不应该调用 log-analysis。如果它调用了说明 description 写得太宽泛需要加上“当用户提供 .log 文件时”这类限定条件。实测下来命中率主要取决于 description 的精准度。我的经验是把“做什么”和“触发条件”分开写触发条件里尽量包含用户的原话词汇。5. 本篇常见错排查技能不生效时按下面几个方向逐个排查。技能没被扫描到。检查目录层级是否正确。Claude Code 扫描的是~/.claude/skills/下的直接子目录每个子目录里必须有SKILL.md。如果你把技能放在~/.claude/skills/foo/bar/SKILL.md它可能扫不到。用ls ~/.claude/skills/*/SKILL.md确认每个技能入口都在。frontmatter 格式错误。YAML 对缩进和冒号很敏感。name和description必须顶格冒号后面要有空格。如果 description 里含冒号要用引号包起来。可以用在线 YAML 校验工具过一遍或者直接看 Claude Code 启动日志里有没有解析报错。description 匹配不上。这是最常见的问题。Agent 只靠 name 和 description 做匹配正文它看不到。所以 description 要写成“用户会怎么描述这个需求”的样子而不是“这个技能技术上做了什么”。比如写“当用户需要汇总账单、生成报销单时使用”比写“基于 OCR 的账单处理”命中率高得多。技能之间互相抢。如果两个技能的 description 覆盖了相似场景Agent 可能随机选一个。解决办法是在 description 里加排他条件比如“仅当输入为图片时使用”“仅当涉及 Git 提交时使用”。脚本执行失败。如果技能正文里调用了scripts/下的脚本要确认脚本有执行权限依赖也装好了。Skills 比 MCP 更依赖本地环境脚本路径写相对路径时基准目录是技能文件夹本身不是项目根目录。改了 SKILL.md 不生效。Claude Code 在启动时加载技能元数据改完要重启。如果只想快速验证可以退出当前会话重新进。注意排查时优先看 Claude Code 的启动输出它会打印加载了哪些技能。如果某个技能没出现在列表里问题一定在目录结构或 frontmatter而不是 description。6. 把技能组织成可检索的目录才是长期解法回到开头那个问题能力堆叠后 Agent 变笨根因是上下文没有分层。Skills 用SKILL.md做入口、用 frontmatter 做索引、用渐进式加载做按需读取本质上是给 Agent 装了一份带目录的说明书。目录负责“找得到”正文负责“做得好”两者分开上下文就不会膨胀。如果你打算把这套东西用在长期编码或 Agent 工作流里建议配合 Coding Plan 来管理调用额度入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。日常验证模型对技能的理解是否到位可以直接在模型对话里试地址是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。需要新建或轮换 Key 时去 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。我自己的习惯是每加一个技能先写 description再写正文最后一定跑一遍正向和反向用例。description 改三遍以上是常事但改完之后 Agent 的调用准确率会明显不一样。技能多了以后维护那份清单文件比什么都重要它就是你这份说明书的目录页。
