1. 为什么你的 Claude 总是“答得对但干不对”Agent Skills 要解决的场景问题如果你用过 Claude Code 或者 claude.ai 处理稍微带点“公司规矩”的活大概率遇到过这种尴尬模型明明很聪明但输出的东西就是不符合你们团队的格式。比如让它生成一份周报它给你写成了散文让它审一段代码它把命名规范全按自己的喜好改了。你每次都得在对话开头粘贴一大段“请按以下格式输出……”粘完这次下次开新会话又得重来。这就是 Anthropic 在 2025 年 10 月正式推出 Agent Skills 的背景。Agent Skills 是一套智能体模块化能力封装标准它把领域流程、业务规则、脚本模板打包成一个独立文件夹让 Claude Agent 在需要的时候动态加载。说白了它把“通用大模型”变成“懂你规矩的领域专家智能体”。这套标准最早在 Claude Code 里落地后来逐步开放到 Claude API、claude.ai 以及 AWS Claude Platform 等环境。它适合谁我认为三类人最该上手一是天天用 Claude Code 写代码、但总在重复交代项目规范的开发者二是想把内部审批、报销、会议纪要这类流程固化下来的团队三是已经在用 MCP 接外部工具、但发现“工具会调了、流程还是乱的”那批人。Agent Skills 和 MCP 不是二选一而是互补——Skill 教 Agent 业务流程MCP 给 Agent 外部工具能力。这篇文章我会带你从零走一遍先理解 SKILL.md 的结构和渐进式加载机制再在本地 Claude 客户端里跑通一个可运行的技能示例最后说清楚怎么用统一的 Key/API 通道管理模型访问配置。全程可跟做命令和配置都能直接复制。2. SKILL.md 结构拆解与渐进式披露机制Anthropic Agent Skills 入门必读要理解 Agent Skills先记住一句话一个 Skill 就是一个文件夹入口文件固定叫 SKILL.md。这个文件夹里可以放指令、YAML 元数据、脚本、模板、参考文档。模型判断任务匹配时才会加载对应 Skill不会把所有内容一股脑塞进上下文窗口。这里的关键机制叫渐进式披露Progressive Disclosure分三级加载目的是控制上下文长度、避免上下文爆炸L1 元数据预加载SKILL.md 头部 YAML 里的 name 和 description。这部分常驻用于模型判断“要不要启用这个 skill”。所以 description 写得好不好直接决定触发准不准。L2 主指令触发后加载SKILL.md 正文写任务流程、约束、输出规范。只有 skill 被触发时才读入。L3 附属资源按需再加载scripts/ 里的脚本、templates/ 里的模板、references/ 里的参考文件。只有任务真正需要时才读进上下文。整个链路可以这样理解AgentClaude扫描 skills 目录 → 匹配元数据 → 触发后加载指令与附属资源 → 调用沙盒执行脚本或工具完成任务。一个最小完整的目录结构长这样my-report-skill/ # Skill 根目录技能名 ├─ SKILL.md # 必须入口YAML 头 Markdown 指令 ├─ templates/ │ └─ report-template.md # 输出模板可选 └─ scripts/ └─ parse_csv.py # 配套执行脚本可选SKILL.md 的最小模板如下注意头部---之间是 YAML 元数据供模型做匹配判断后面 Markdown 是给 Agent 阅读的工作指令--- name: report-generator description: 生成业务分析报告用户要求输出报告时自动启用。 version: 0.1 author: demo --- # 业务报告生成 Skill ## 触发条件 用户提出生成业务报告、数据分析报告请求时启用。 ## 执行流程 1. 收集输入数据 2. 使用 templates/report-template.md 作为输出格式 3. 输出必须包含摘要、数据结论、风险提示三部分。 ## 约束 禁止编造原始数据数据缺失时明确提示用户补充。这里有个容易踩的坑很多人把 Skill 当成“普通长 prompt”来写把所有内容全塞进 SKILL.md。结果上下文被撑爆触发还慢。正确做法是遵循渐进加载——大模板、脚本单独放子目录SKILL.md 里只写“什么时候用、按什么步骤、输出什么格式、禁止什么”。和普通 Prompt 的区别也值得说清楚。Prompt 是对话级别的每次对话重复粘贴一次性生效Agent Skills 是文件系统级的可复用资产一次编写、多会话自动调用支持脚本和附件资源还能做版本管理、团队共享。这就是为什么它更适合“有规矩”的场景。3. 本地环境准备与统一 Key/API 通道配置Claude Code 接入实操理解了结构接下来动手。本地调试 Agent Skills 最主要的载体是 Claude Code。技能存放路径是~/.claude/skills/把 skill 文件夹复制到这个目录Claude Code 就能自动发现。在开始之前先把模型访问配置理顺。我实测下来用统一的 Key/API 通道管理访问配置会省很多事尤其是你同时要跑 Claude Code、Cline、Codex 这类工具的时候。TaoToken 提供的就是这样一个统一入口官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。先拿 Key。打开控制台页面 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建你的 API Key。拿到之后Claude Code 的配置需要三件套Base URL、Key、Model ID。这三样缺一不可后面所有工具都按这个套路来。Claude Code 的配置通常写在 settings 文件里。下面是一个可复制的 settings 片段路径和字段名保持原样{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-5 } }如果你用的是 Cline 或者带 MCP 的客户端配置思路一样只是字段名不同。Cline 的 MCP 配置里同样要写全 Base URL、Key、Model ID 三件套{ mcpServers: { taotoken: { command: npx, args: [-y, taotoken/mcp-server], env: { TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_API_KEY: sk-你的Key, TAOTOKEN_MODEL: claude-sonnet-4-5 } } } }如果你用 Codex配置写在auth.json里同样三件套{ base_url: https://taotoken.net/api, api_key: sk-你的Key, model: claude-sonnet-4-5 }配置好之后先别急着写 Skill先验证通道通不通。这一步很关键因为后面 Skill 触发失败很多时候不是 Skill 写错了而是模型访问根本没连上。4. 从零写一个可运行 Skill 并验证调用SKILL.md 触发测试全流程现在开始写第一个真正能跑的 Skill。我建议从官方预置技能仓库入手先观察别人怎么写不要从零硬憋。官方仓库在 https://github.com/anthropics/skills 里面有 PDF 解析、Excel 处理、学术写作、Web 测试等大量现成 Skill。先克隆下来看看git clone https://github.com/anthropics/skills.git cd skills/skills ls你会看到一堆文件夹每个里面都有 SKILL.md。挑一个简单的读一读重点看它的 YAML 头怎么写 description、正文怎么分触发条件和执行流程。接下来我们做一个自己的小技能把 CSV 数据转成结构化报告。目录结构如下csv-report-skill/ ├─ SKILL.md ├─ templates/ │ └─ report-template.md └─ scripts/ └─ parse_csv.pySKILL.md 内容--- name: csv-report description: 当用户提供 CSV 文件并要求生成分析报告时启用自动解析数据并套用报告模板。 version: 0.1 author: demo --- # CSV 报告生成 Skill ## 触发条件 用户上传或指定 CSV 文件并要求生成分析报告、数据摘要时启用。 ## 执行流程 1. 调用 scripts/parse_csv.py 解析 CSV输出字段统计 2. 读取 templates/report-template.md 作为输出骨架 3. 按模板填充数据概览、关键指标、异常提示。 ## 约束 禁止编造 CSV 中不存在的字段数据为空时提示用户检查文件。scripts/parse_csv.py写一个最简解析import csv import sys def parse(path): with open(path, newline, encodingutf-8) as f: reader csv.DictReader(f) rows list(reader) print(f行数: {len(rows)}) if rows: print(f字段: {, .join(rows[0].keys())}) if __name__ __main__: parse(sys.argv[1])templates/report-template.md# 数据分析报告 ## 数据概览 行数、字段说明 ## 关键指标 核心数值 ## 异常提示 缺失值、异常值写完后把整个文件夹复制到 Claude Code 的技能目录cp -r csv-report-skill ~/.claude/skills/重启 Claude Code然后在一个会话里输入“我有个 sales.csv帮我生成分析报告。” 如果配置正确Claude 会识别到 csv-report 这个 skill 被触发读取 SKILL.md 正文按流程调用脚本、套用模板。验证成功的标志有三个一是 Claude 明确提到它在使用 csv-report 技能二是输出结构符合模板的三段式三是脚本被实际执行你能看到行数和字段输出。如果只输出了泛泛的分析、没有套模板说明 skill 没被触发回到第 5 节排查。5. 常见报错排查401、local proxy failed、reading choices 与 OAuth 问题Skill 跑不起来八成不是 SKILL.md 写错而是访问通道或配置出了问题。下面按真实报错逐条对照。401 Unauthorized最常见。说明 Key 无效或没带上。检查三件套里的 Key 是否复制完整有没有多余空格。如果你用的是统一通道确认ANTHROPIC_API_KEY或对应字段填的是控制台里创建的那个 Key。401 基本就是 Key 的问题别去改 Skill。local proxy failed / connection refused本地代理或网络层没通。先确认 Base URL 写的是https://taotoken.net/api不要多写斜杠或路径。然后确认你的客户端能正常访问这个地址。这类报错和 Skill 无关是通道层的问题。reading choices 相关报错通常出现在响应解析阶段说明返回体不是预期的模型响应格式。多数情况是 Model ID 写错了或者通道返回了错误页被当成响应解析。检查ANTHROPIC_MODEL或TAOTOKEN_MODEL是否填了有效的模型名比如claude-sonnet-4-5。OAuth 相关报错如果你之前用官方账号登录过客户端可能还在走 OAuth 流程和你新配的 Key 冲突。解决办法是清掉旧的登录态强制走 API Key 模式。Claude Code 里可以检查 settings 是否被旧配置覆盖。排查顺序建议固定下来先验证通道用模型对话页面发一条消息看能不能正常回再验证 Key换一个 Key 试最后才怀疑 Skill。模型对话入口在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。这两个页面能帮你快速定位是通道问题还是 Skill 问题。还有一个隐蔽的坑Skill 文件夹名和 SKILL.md 里的 name 不一致。虽然多数情况不报错但触发匹配会变差。保持两者一致description 里把触发场景写具体比如“用户提供 CSV 并要求报告时启用”而不是“处理数据”。6. 把 Skill 和 MCP 配合起来长期编码与 Agent 场景的落地建议很多人把 Agent Skills 和 MCP 搞混其实一句话能分清Skill 教 Agent 业务流程MCP 给 Agent 外部工具能力。Skill 是本地文件夹加 SKILL.md以自然语言为主告诉 Agent“该怎么做、输出什么格式、有什么业务约束”MCP 是服务端进程加标准协议接口连接数据库、API、本地命令行这些外部工具。Skill 可以指导 Agent 如何调用 MCP 工具MCP 提供 Skill 需要的外部能力。典型配合场景你写一个“代码评审 Skill”规定评审必须覆盖命名规范、异常处理、测试覆盖三块同时通过 MCP 接一个静态分析工具。Agent 触发 Skill 后按流程去调 MCP 工具拿分析结果再按 Skill 规定的格式输出。这样流程和工具就都齐了。如果你要长期跑编码或 Agent 任务建议用 Coding Plan 来管理额度入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。它比按次调用更适合持续性的开发场景。API Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 需要新增或轮换 Key 时从这里操作。最后给几条我踩过坑之后的实用建议。第一先复用官方 Skill从 https://github.com/anthropics/skills 拉下来观察写法别从零写。第二description 写清楚触发场景模型靠这个判断什么时候启用。第三复杂逻辑拆到外部脚本不要全塞进 SKILL.md遵循渐进加载。第四小步迭代先做简单 Skill 测触发再加脚本和资源。第五Skill 文件夹名和 name 保持一致减少匹配偏差。如果你在 Claude Code 里调试记得每次改完 SKILL.md 后重启客户端让它重新扫描 skills 目录。这个动作很小但能省掉很多“为什么改了没生效”的困惑。