1. 先搞清楚 ClaudeCode Skills 到底解决了什么问题ClaudeCode Skills 是 Anthropic 在 2025 年 10 月随 Agent Skill 文档一起推出的机制本质是一个带SKILL.md的文件夹让 Claude 在需要时动态发现并加载专业知识。它能做什么把「填 PDF 表单」「按团队规范生成代码」「跑一套固定脚本」这类流程化经验打包成可复用资源让通用 Agent 变成你所在领域的专用 Agent。适合谁想自建 Skill 的开发者、需要把重复操作沉淀下来的团队以及被「每次都要重新解释一遍需求」折磨过的人。我最初接触它时踩过一个坑以为 Skill 就是把一大段提示词塞进文件结果 Claude 要么不触发要么把整个文件读进上下文Token 哗哗地烧。后来才明白Skill 的核心不是「写得多」而是「分层写」——用 YAML 元数据做索引用SKILL.md做正文用捆绑文件做附录让 Claude 按需读取。这套设计叫渐进式披露Progressive Disclosure也是本文要拆透的主线。下面我会从SKILL.md的文件结构讲起把 YAML 字段逐个拆开再给一份可复制的骨架最后演示一次注册与调用的验证动作。全程围绕 ClaudeCode、Skills、Agent Skill、SKILL.md、YAML 这几个关键词展开你可以边看边动手。2. TaoToken 前置给 ClaudeCode 配一个稳定的接入点在自建 Skill 之前得先让 ClaudeCode 能正常跑起来。我实测下来用 TaoToken 作为接入层比较省心它提供兼容 Anthropic 的 API 端点配置一次就能在 ClaudeCode 里直接调用模型。你需要先拿到 API Key。打开 https://taotoken.net/api-keys 创建密钥注意这个页面是控制台的一部分创建后记得复制保存页面刷新后就看不到了。拿到 Key 之后在 ClaudeCode 的配置里指向 TaoToken 的 API 地址。官方文档在 https://taotoken.net/doc 里面有各客户端的接入说明。核心就是把 base URL 改成https://taotoken.net/api再把 Key 填进去。注意API 地址不要加 UTM 参数直接写https://taotoken.net/api即可加了反而可能导致请求异常。如果你还没决定用哪个模型可以先到 https://taotoken.net/models 看看模型对话能力确认 Claude 系列模型可用后再继续。对于长期做编码和 Agent 开发的场景https://taotoken.net/coding-plan 里有更划算的套餐适合高频调用。配置完成后用一条最简单的请求验证连通性curl https://taotoken.net/api/v1/messages \ -H x-api-key: 你的API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 128, messages: [{role: user, content: 回复 OK 两个字母}] }返回里出现OK就说明链路通了。这一步别跳过后面 Skill 调试时如果出问题你能快速判断是接入层还是 Skill 本身的问题。3. SKILL.md 的文件结构与 YAML 字段拆解3.1 一个 Skill 就是一个目录Skill 的最小单位是一个目录目录里必须有一个SKILL.md文件。这个文件必须以 YAML 前置元数据开头用---包裹。元数据里有两个必填字段name和description。Claude 在任务开始时会把每个已安装 Skill 的name和description预加载到系统提示词里。这就是渐进式披露的第一层——Claude 靠这两个字段判断「当前任务要不要用这个 Skill」。如果判断相关它才会去读SKILL.md的正文也就是第二层信息。3.2 YAML 字段逐个看字段是否必填作用写法建议name必填Skill 的唯一标识小写字母加连字符如pdf-form-fillerdescription必填触发判断依据写清「做什么 什么时候用」越具体越好version可选版本号语义化版本如1.0.0author可选作者信息团队内部可写负责人tags可选分类标签便于管理和检索description是最容易被写废的字段。很多人写成「处理 PDF」结果 Claude 根本不知道什么时候该触发。正确的写法是描述场景「当用户需要填写 PDF 表单、提取表单字段或批量处理 PDF 文档时使用」。把触发条件写进去命中率会明显提升。3.3 嵌套结构把臃肿的 SKILL.md 拆开当 Skill 变复杂单个SKILL.md会变得臃肿而且有些信息只在特定场景才用得上。这时可以在 Skill 目录里捆绑其他文件在SKILL.md里按名称引用。这些引用构成第三层或更高层信息Claude 按需读取。一个典型的 PDF Skill 目录长这样pdf-skill/ ├── SKILL.md # 主指令含 YAML 元数据 ├── FORMS.md # 表单填写指南仅填表时读取 ├── REFERENCE.md # API 详细参考仅查接口时读取 └── scripts/ └── fill_form.py # 工具脚本独立执行这样设计的好处是Claude 只在填表单时读FORMS.md核心的SKILL.md保持简洁。就像一本手册先看目录再看章节最后翻附录不需要每次都把整本书读完。3.4 代码引用让脚本独立执行Skill 里可以放代码Claude 能自行决定把脚本当工具执行。比如 PDF Skill 里有个 Python 脚本读取表单字段Claude 不需要把脚本全文或 PDF 内容加载进上下文脚本单独跑只把返回结果并入 Skill 流程。因为代码固定这个工作流一致且可重复。注意脚本执行意味着 Skill 有了实际操作能力安全边界要提前想清楚别让脚本去碰生产库或敏感文件。4. 可复制的 SKILL.md 骨架与 YAML 配置下面这份骨架你可以直接复制改掉name和description就能用。我以一个「代码规范检查」Skill 为例演示完整结构。--- name: code-style-checker description: 当用户需要检查代码风格、生成符合团队规范的代码或询问命名与格式约定时使用。适用于 Python 和 JavaScript 项目。 version: 1.0.0 author: your-team tags: - code-quality - linting --- # 代码规范检查 Skill ## 何时使用 当任务涉及以下场景时加载本 Skill - 用户要求检查代码是否符合团队规范 - 用户要求生成新代码需要遵循命名和格式约定 - 用户询问某个写法是否规范 ## 核心规范 ### 命名约定 - 变量和函数使用 snake_casePython或 camelCaseJavaScript - 类名使用 PascalCase - 常量使用 UPPER_SNAKE_CASE ### 格式约定 - 缩进统一 4 空格Python或 2 空格JavaScript - 单行不超过 100 字符 - 导入语句按标准库、第三方、本地分组 ## 详细参考 需要查看完整规则时读取 REFERENCE.md。 需要运行自动检查时执行 scripts/check_style.py。 ## 输出格式 检查结果按以下格式返回 文件:行号 - 问题类型 - 建议修改对应的REFERENCE.md放完整规则表scripts/check_style.py放检查脚本。这样SKILL.md保持精简细节按需加载。YAML 部分有几个细节要注意description里不要换行写成一行如果确实很长用折叠写法。name不要用大写或空格否则加载可能失败。5. 注册与调用验证一次完整的 Skill 触发5.1 放置 Skill 目录把 Skill 目录放到 ClaudeCode 能识别的位置。通常是在项目根目录下的.claude/skills/里或者用户级的~/.claude/skills/。以项目级为例mkdir -p .claude/skills/code-style-checker # 把 SKILL.md、REFERENCE.md、scripts/ 放进去 ls -R .claude/skills/code-style-checker输出应该能看到SKILL.md和捆绑文件。5.2 验证元数据被加载启动 ClaudeCode发一条能触发 Skill 的消息比如「帮我检查这段 Python 代码的风格」。观察 Claude 的行为如果它先读取了SKILL.md再按需读取REFERENCE.md说明渐进式披露在工作。你也可以在对话里直接问 Claude「你现在加载了哪些 Skill」它应该能列出code-style-checker及其description。5.3 验证脚本执行如果 Skill 里有脚本发一条需要跑脚本的消息比如「运行自动检查」。Claude 应该调用scripts/check_style.py并把返回结果并入回答。这一步验证的是代码引用路径是否通。5.4 上下文窗口的变化触发 Skill 时上下文窗口的顺序大致是核心系统提示词 → 各 Skill 的元数据 → 用户消息 → Claude 读取SKILL.md→ 按需读取捆绑文件 → 执行任务。你可以通过观察 Claude 的读取动作来确认这个顺序。如果它一上来就把所有文件读光说明description写得太宽泛或者SKILL.md里引用太多。6. 本篇常见错排查Skill 不触发九成是description写得太泛。改成「当用户需要 X 时使用」这种场景化描述。另外检查name是否符合小写连字符规范。YAML 解析失败---必须是文件第一行前面不能有空行或注释。字段值里有冒号时要用引号包起来比如description: 检查代码: 风格与格式。捆绑文件读不到SKILL.md里引用文件要用相对路径且文件名大小写要一致。Linux 环境下Forms.md和forms.md是两个文件。脚本执行报错确认脚本有可执行权限路径相对于 Skill 目录。Python 脚本记得在文件头写 shebang或者让 Claude 用python scripts/xxx.py调用。Token 消耗异常检查是不是把大段内容塞进了SKILL.md正文。该拆到REFERENCE.md的就拆出去让 Claude 按需读取。接入层报错如果 Skill 本身没问题但请求失败回到第 2 节检查 TaoToken 的 API 地址和 Key。接入文档在 https://taotoken.net/doc 对照排查。7. 继续深入从验证到长期使用Skill 调通之后下一步是迭代。让 Claude 在完成任务时把重复操作和常见错误记录下来转成可复用的 Skill 代码和上下文。如果它偏离了方向让它自我反思问题在哪这个过程能帮你发现 Claude 实际需要的上下文是什么。安全上别偷懒。Skill 赋予 Claude 新能力也意味着恶意 Skill 可能引入漏洞或诱导数据外泄。只从可信来源安装从不可信来源拿到的 Skill使用前把文件内容、代码依赖、捆绑资源都读一遍尤其注意有没有让 Claude 连接外部网络资源的指令。如果你打算长期做编码和 Agent 开发可以到 https://taotoken.net/coding-plan 看看套餐高频调用下更划算。模型能力确认用 https://taotoken.net/models 接入细节查 https://taotoken.net/doc 密钥管理在 https://taotoken.net/api-keys 。把这几个入口存好后面调试 Skill 会反复用到。
ClaudeCode Skills 原理解读：从 SKILL.md 到 YAML 配置的完整拆解
1. 先搞清楚 ClaudeCode Skills 到底解决了什么问题ClaudeCode Skills 是 Anthropic 在 2025 年 10 月随 Agent Skill 文档一起推出的机制本质是一个带SKILL.md的文件夹让 Claude 在需要时动态发现并加载专业知识。它能做什么把「填 PDF 表单」「按团队规范生成代码」「跑一套固定脚本」这类流程化经验打包成可复用资源让通用 Agent 变成你所在领域的专用 Agent。适合谁想自建 Skill 的开发者、需要把重复操作沉淀下来的团队以及被「每次都要重新解释一遍需求」折磨过的人。我最初接触它时踩过一个坑以为 Skill 就是把一大段提示词塞进文件结果 Claude 要么不触发要么把整个文件读进上下文Token 哗哗地烧。后来才明白Skill 的核心不是「写得多」而是「分层写」——用 YAML 元数据做索引用SKILL.md做正文用捆绑文件做附录让 Claude 按需读取。这套设计叫渐进式披露Progressive Disclosure也是本文要拆透的主线。下面我会从SKILL.md的文件结构讲起把 YAML 字段逐个拆开再给一份可复制的骨架最后演示一次注册与调用的验证动作。全程围绕 ClaudeCode、Skills、Agent Skill、SKILL.md、YAML 这几个关键词展开你可以边看边动手。2. TaoToken 前置给 ClaudeCode 配一个稳定的接入点在自建 Skill 之前得先让 ClaudeCode 能正常跑起来。我实测下来用 TaoToken 作为接入层比较省心它提供兼容 Anthropic 的 API 端点配置一次就能在 ClaudeCode 里直接调用模型。你需要先拿到 API Key。打开 https://taotoken.net/api-keys 创建密钥注意这个页面是控制台的一部分创建后记得复制保存页面刷新后就看不到了。拿到 Key 之后在 ClaudeCode 的配置里指向 TaoToken 的 API 地址。官方文档在 https://taotoken.net/doc 里面有各客户端的接入说明。核心就是把 base URL 改成https://taotoken.net/api再把 Key 填进去。注意API 地址不要加 UTM 参数直接写https://taotoken.net/api即可加了反而可能导致请求异常。如果你还没决定用哪个模型可以先到 https://taotoken.net/models 看看模型对话能力确认 Claude 系列模型可用后再继续。对于长期做编码和 Agent 开发的场景https://taotoken.net/coding-plan 里有更划算的套餐适合高频调用。配置完成后用一条最简单的请求验证连通性curl https://taotoken.net/api/v1/messages \ -H x-api-key: 你的API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 128, messages: [{role: user, content: 回复 OK 两个字母}] }返回里出现OK就说明链路通了。这一步别跳过后面 Skill 调试时如果出问题你能快速判断是接入层还是 Skill 本身的问题。3. SKILL.md 的文件结构与 YAML 字段拆解3.1 一个 Skill 就是一个目录Skill 的最小单位是一个目录目录里必须有一个SKILL.md文件。这个文件必须以 YAML 前置元数据开头用---包裹。元数据里有两个必填字段name和description。Claude 在任务开始时会把每个已安装 Skill 的name和description预加载到系统提示词里。这就是渐进式披露的第一层——Claude 靠这两个字段判断「当前任务要不要用这个 Skill」。如果判断相关它才会去读SKILL.md的正文也就是第二层信息。3.2 YAML 字段逐个看字段是否必填作用写法建议name必填Skill 的唯一标识小写字母加连字符如pdf-form-fillerdescription必填触发判断依据写清「做什么 什么时候用」越具体越好version可选版本号语义化版本如1.0.0author可选作者信息团队内部可写负责人tags可选分类标签便于管理和检索description是最容易被写废的字段。很多人写成「处理 PDF」结果 Claude 根本不知道什么时候该触发。正确的写法是描述场景「当用户需要填写 PDF 表单、提取表单字段或批量处理 PDF 文档时使用」。把触发条件写进去命中率会明显提升。3.3 嵌套结构把臃肿的 SKILL.md 拆开当 Skill 变复杂单个SKILL.md会变得臃肿而且有些信息只在特定场景才用得上。这时可以在 Skill 目录里捆绑其他文件在SKILL.md里按名称引用。这些引用构成第三层或更高层信息Claude 按需读取。一个典型的 PDF Skill 目录长这样pdf-skill/ ├── SKILL.md # 主指令含 YAML 元数据 ├── FORMS.md # 表单填写指南仅填表时读取 ├── REFERENCE.md # API 详细参考仅查接口时读取 └── scripts/ └── fill_form.py # 工具脚本独立执行这样设计的好处是Claude 只在填表单时读FORMS.md核心的SKILL.md保持简洁。就像一本手册先看目录再看章节最后翻附录不需要每次都把整本书读完。3.4 代码引用让脚本独立执行Skill 里可以放代码Claude 能自行决定把脚本当工具执行。比如 PDF Skill 里有个 Python 脚本读取表单字段Claude 不需要把脚本全文或 PDF 内容加载进上下文脚本单独跑只把返回结果并入 Skill 流程。因为代码固定这个工作流一致且可重复。注意脚本执行意味着 Skill 有了实际操作能力安全边界要提前想清楚别让脚本去碰生产库或敏感文件。4. 可复制的 SKILL.md 骨架与 YAML 配置下面这份骨架你可以直接复制改掉name和description就能用。我以一个「代码规范检查」Skill 为例演示完整结构。--- name: code-style-checker description: 当用户需要检查代码风格、生成符合团队规范的代码或询问命名与格式约定时使用。适用于 Python 和 JavaScript 项目。 version: 1.0.0 author: your-team tags: - code-quality - linting --- # 代码规范检查 Skill ## 何时使用 当任务涉及以下场景时加载本 Skill - 用户要求检查代码是否符合团队规范 - 用户要求生成新代码需要遵循命名和格式约定 - 用户询问某个写法是否规范 ## 核心规范 ### 命名约定 - 变量和函数使用 snake_casePython或 camelCaseJavaScript - 类名使用 PascalCase - 常量使用 UPPER_SNAKE_CASE ### 格式约定 - 缩进统一 4 空格Python或 2 空格JavaScript - 单行不超过 100 字符 - 导入语句按标准库、第三方、本地分组 ## 详细参考 需要查看完整规则时读取 REFERENCE.md。 需要运行自动检查时执行 scripts/check_style.py。 ## 输出格式 检查结果按以下格式返回 文件:行号 - 问题类型 - 建议修改对应的REFERENCE.md放完整规则表scripts/check_style.py放检查脚本。这样SKILL.md保持精简细节按需加载。YAML 部分有几个细节要注意description里不要换行写成一行如果确实很长用折叠写法。name不要用大写或空格否则加载可能失败。5. 注册与调用验证一次完整的 Skill 触发5.1 放置 Skill 目录把 Skill 目录放到 ClaudeCode 能识别的位置。通常是在项目根目录下的.claude/skills/里或者用户级的~/.claude/skills/。以项目级为例mkdir -p .claude/skills/code-style-checker # 把 SKILL.md、REFERENCE.md、scripts/ 放进去 ls -R .claude/skills/code-style-checker输出应该能看到SKILL.md和捆绑文件。5.2 验证元数据被加载启动 ClaudeCode发一条能触发 Skill 的消息比如「帮我检查这段 Python 代码的风格」。观察 Claude 的行为如果它先读取了SKILL.md再按需读取REFERENCE.md说明渐进式披露在工作。你也可以在对话里直接问 Claude「你现在加载了哪些 Skill」它应该能列出code-style-checker及其description。5.3 验证脚本执行如果 Skill 里有脚本发一条需要跑脚本的消息比如「运行自动检查」。Claude 应该调用scripts/check_style.py并把返回结果并入回答。这一步验证的是代码引用路径是否通。5.4 上下文窗口的变化触发 Skill 时上下文窗口的顺序大致是核心系统提示词 → 各 Skill 的元数据 → 用户消息 → Claude 读取SKILL.md→ 按需读取捆绑文件 → 执行任务。你可以通过观察 Claude 的读取动作来确认这个顺序。如果它一上来就把所有文件读光说明description写得太宽泛或者SKILL.md里引用太多。6. 本篇常见错排查Skill 不触发九成是description写得太泛。改成「当用户需要 X 时使用」这种场景化描述。另外检查name是否符合小写连字符规范。YAML 解析失败---必须是文件第一行前面不能有空行或注释。字段值里有冒号时要用引号包起来比如description: 检查代码: 风格与格式。捆绑文件读不到SKILL.md里引用文件要用相对路径且文件名大小写要一致。Linux 环境下Forms.md和forms.md是两个文件。脚本执行报错确认脚本有可执行权限路径相对于 Skill 目录。Python 脚本记得在文件头写 shebang或者让 Claude 用python scripts/xxx.py调用。Token 消耗异常检查是不是把大段内容塞进了SKILL.md正文。该拆到REFERENCE.md的就拆出去让 Claude 按需读取。接入层报错如果 Skill 本身没问题但请求失败回到第 2 节检查 TaoToken 的 API 地址和 Key。接入文档在 https://taotoken.net/doc 对照排查。7. 继续深入从验证到长期使用Skill 调通之后下一步是迭代。让 Claude 在完成任务时把重复操作和常见错误记录下来转成可复用的 Skill 代码和上下文。如果它偏离了方向让它自我反思问题在哪这个过程能帮你发现 Claude 实际需要的上下文是什么。安全上别偷懒。Skill 赋予 Claude 新能力也意味着恶意 Skill 可能引入漏洞或诱导数据外泄。只从可信来源安装从不可信来源拿到的 Skill使用前把文件内容、代码依赖、捆绑资源都读一遍尤其注意有没有让 Claude 连接外部网络资源的指令。如果你打算长期做编码和 Agent 开发可以到 https://taotoken.net/coding-plan 看看套餐高频调用下更划算。模型能力确认用 https://taotoken.net/models 接入细节查 https://taotoken.net/doc 密钥管理在 https://taotoken.net/api-keys 。把这几个入口存好后面调试 Skill 会反复用到。
