1. 从一次 Agent 翻车说起为什么需要 Claude Skills你可能遇到过这种场景给 Agent 写了一段很长的系统提示把公司内部的报销流程、代码规范、客服话术全塞进去结果它回答简单问题时也要背着几千 Token 的“背景包袱”一旦流程更新还得整段重写。更麻烦的是多个 Agent 想复用同一套领域知识只能靠复制粘贴改一处漏三处。Claude Skills 就是冲着这个痛点来的。它是 Anthropic 推出的模块化能力扩展方案核心思路是“文件系统封装 渐进式披露”把领域 SOP、操作指令、辅助脚本打包成一个文件夹Agent 启动时只加载几十个 Token 的元数据真正匹配到场景才去读完整指令需要跑脚本时脚本代码甚至不进上下文只拿回执行结果。一句话概括Claude Skills 让 Agent 从“背着一整本手册干活”变成“先看目录用到哪章翻哪章”。它适合谁适合正在做 Agent 项目、被上下文长度和知识复用折磨的开发者也适合想把团队内部流程沉淀成可复用资产的工程团队。它和 MCP 不是替代关系——MCP 解决“能调用什么工具”Skills 解决“懂什么流程”两者拼起来才是完整的工业级 Agent 能力栈。下面我从 SKILL.md 的结构讲起拆开加载流程再给一份可复制的模板和本地验证步骤让你在自己的项目里跑通一个最小技能。2. SKILL.md 结构拆解与渐进式披露机制2.1 一个 Skill 文件夹长什么样每个 Skill 就是一个独立文件夹支持嵌套子技能形成层级化知识体系。典型结构如下pdf-skill/ ├── SKILL.md # 元数据YAML 头 核心指令 ├── FORMS.md # 扩展指令表单填写高级指南 ├── REFERENCE.md # API 参考文档 └── scripts/ └── fill_form.py # 可执行脚本表单填写工具SKILL.md 是入口头部用 YAML 写元数据正文写操作流程。元数据里最关键的是name和description因为 Agent 就是靠这两项判断“这个技能适不适合当前任务”。2.2 渐进式披露的三层加载这是 Claude Skills 最核心的机制理解它才能理解为什么 Token 能省下来。第一层是元数据始终加载。Agent 启动时把所有 Skill 的 name、description、tags 读进上下文每个大约 100 Token。作用是快速匹配场景——用户提到“PDF 提取”Agent 就能关联到pdf-processing这个技能。第二层是核心指令触发时加载。Agent 判断场景匹配后通过 Bash 工具读取 SKILL.md 正文拿到具体操作步骤和基础 SOP。这时候才真正把“怎么做”读进来。第三层是资源与代码按需加载。执行过程中需要高级功能时才去读 FORMS.md 或执行 scripts 里的脚本。关键点在于脚本代码永远不进上下文Agent 只拿到执行结果比如“表单填写成功”。这一步把 Token 消耗压到了最低。三层下来一个复杂 Skill 的上下文占用从“数千 Token”压缩到“百级”而且 Agent 只看到当前需要的知识不会被无关信息干扰。2.3 与 MCP 的协作边界很多人会问有了 MCP 为什么还要 Skills其实两者分工很清楚。对比维度Claude SkillsMCP核心定位内部领域知识包SOP、流程、规则外部工具连接标准API、服务、数据库作用范围解决“Agent 懂什么”解决“Agent 能调用什么”运行环境沙盒 VM 文件系统跨平台通用协议典型场景PDF 处理、导购 SOP、表单规则调用 Jira、Stripe、商品数据库 API协同逻辑是Skills 告诉 Agent“做事的步骤”MCP 提供“做事的工具”。比如导购场景Skill 里写“先问预算再匹配商品”的 SOPMCP 负责去商品数据库查数据。两者结合Agent 才既有知识又有工具。3. 可复制的 SKILL.md 模板与本地配置3.1 最小 SKILL.md 模板下面这份模板可以直接复制改掉 name 和 description 就能用。注意 YAML 头必须用---包裹description 要写清楚“什么时候用”这是 Agent 匹配场景的唯一依据。--- name: pdf-processing description: 提取PDF文件中的文本和表格填写表单合并文档。当处理PDF文件或用户提及PDF、表单或文档提取时使用。 tags: [pdf, document, text-extraction] --- # PDF处理技能 ## 快速入门 使用 pdfplumber 提取PDF文本 python import pdfplumber with pdfplumber.open(document.pdf) as pdf: text pdf.pages[0].extract_text() print(text)高级功能如需填写表单参阅 FORMS.md 如需执行批量处理运行scripts/fill_form.py脚本。### 3.2 在 Claude Code 中挂载 Skill 如果你用 Claude Code把 Skill 文件夹放到项目根目录的 .claude/skills/ 下即可。Claude Code 启动时会自动扫描这个目录加载所有 SKILL.md 的元数据。 bash mkdir -p .claude/skills/pdf-skill # 把上面的 SKILL.md 写入该目录3.3 通过 API 接入时的配置如果你是通过 API 调用需要把 Skill 目录挂载到沙盒环境。以 TaoToken 的 API 为例Base URL 填https://taotoken.net/apiKey 在控制台生成Model ID 按你用的模型填。三件套缺一不可{ base_url: https://taotoken.net/api, api_key: sk-你的Key, model: claude-sonnet-4-20250514 }如果你用 Cline 或 CC Switch 这类工具配置项名称可能不同但核心就是 Base URL、Key、Model ID 三个字段。Cline 的 MCP 配置里还要额外指定 skills 目录路径确保 Agent 能读到 SKILL.md。3.4 第三方 Agent 的适配思路不是所有 Agent 都跑在 Claude 沙盒里。开源项目 openskills 提供了通用实现核心思路是把 Skills 写入AGENTS.md通过 Bash 命令openskills read [skill-name]调用。Python 里可以这样封装import subprocess def call_skill(skill_name: str) - str: result subprocess.run( [openskills, read, skill_name], capture_outputTrue, textTrue ) return result.stdout这样 Qwen Code、Codex 等 Agent 也能复用同一套 Skill 定义。4. 本地验证跑通一个最小技能示例4.1 准备测试文件先造一个简单的 PDF 测试文件或者直接用任意 PDF。然后写一个最小的 Skillmkdir -p demo-skills/hello-skill cat demo-skills/hello-skill/SKILL.md EOF --- name: hello-skill description: 当用户要求打招呼或测试技能加载时使用。 tags: [demo, hello] --- # 打招呼技能 ## 步骤 1. 读取用户名字 2. 输出 你好{名字}技能加载成功 EOF4.2 触发技能加载在 Claude Code 里输入“帮我测试一下 hello-skill”Agent 会先匹配元数据发现 description 里有“测试技能加载”于是读取 SKILL.md 正文按步骤执行。你应该看到类似输出你好测试者技能加载成功4.3 验证渐进式披露是否生效打开 Claude Code 的调试日志观察 Token 消耗。启动时只加载了元数据大约 100 Token触发后才加载正文。如果你在 SKILL.md 里引用了一个大文件比如 REFERENCE.md只有 Agent 真正去读它时才会产生 Token 消耗。这就是渐进式披露的实际效果。4.4 用脚本验证第三层加载在 Skill 里加一个脚本观察脚本代码是否进入上下文mkdir -p demo-skills/hello-skill/scripts cat demo-skills/hello-skill/scripts/greet.py EOF import sys name sys.argv[1] if len(sys.argv) 1 else world print(f你好{name}脚本执行成功) EOF然后在 SKILL.md 里加一行“如需脚本打招呼运行scripts/greet.py”。触发后Agent 只会拿到“脚本执行成功”这个结果脚本源码不会出现在上下文里。5. 常见报错与排查对照5.1 401 Unauthorized最常见的原因是 Key 没填对或过期。检查你的 API Key 是否完整复制有没有多余空格。如果用 TaoToken去控制台重新生成一个 Key确认 Base URL 是https://taotoken.net/api注意不要多加斜杠。5.2 local proxy failed这个报错通常出现在本地代理配置上。检查你的环境变量HTTP_PROXY、HTTPS_PROXY是否指向了不可用的地址。如果你没配代理直接清空这两个变量再试。另外确认防火墙没有拦截本地端口。5.3 reading choices 相关报错如果报错信息里出现reading choices多半是模型返回格式和客户端解析不匹配。检查你的 Model ID 是否写对比如claude-sonnet-4-20250514不能写成claude-sonnet-4。另外确认 API 版本头anthropic-version是否设置正确。5.4 OAuth 相关报错Claude Code 走 OAuth 登录时如果报 token 失效先退出再重新登录。如果是 API 模式确认没有同时启用 OAuth 和 API Key两者会冲突。CC Switch 里切换配置后记得重启终端。5.5 Skill 不触发如果 Agent 没有加载你的 Skill先检查 SKILL.md 的 YAML 头格式。---必须是文件第一行name和description不能缺。description 要写清楚触发场景太模糊 Agent 匹配不到。另外确认 Skill 目录在 Agent 扫描路径下比如 Claude Code 的.claude/skills/。6. 把 Skill 用起来从最小示例到工作流跑通最小示例后你可以按业务流程拆分多个 Skill。比如导购场景拆成三个参数收集、商品匹配、推荐话术。每个 Skill 独立封装更新匹配规则只改02-product-matching不影响其他环节。新增售后咨询就加一个04-after-sales不用重构 Agent 核心逻辑。这种模块化带来的好处是知识复用和上下文优化。实测下来分层加载能让单轮对话的 Token 占用降低六成左右参数收集、匹配规则这些冗余知识不会一直堆在上下文里。如果你想把 Skill 接入自己的项目先去 TaoToken 控制台拿一个 API Key然后对照接入文档把 Base URL、Key、Model ID 三件套配好。想先验证模型效果可以直接在模型对话里试如果是长期编码或 Agent 项目Coding Plan 更划算。配置过程中遇到报错对照第 5 节的排查清单基本能解决。最后留一个实用技巧SKILL.md 的 description 字段值得多花几分钟打磨。它是 Agent 匹配场景的唯一入口写清楚“什么时候用”比写“这个技能是什么”更重要。我试过把 description 从“PDF 处理”改成“当用户上传 PDF 或要求提取表格时使用”触发准确率明显提升。