1. 从官方 PDF 示例看 Claude Skills 的目录结构Claude Skills也叫 Agent Skills本质上就是一个文件夹里面放一份SKILL.md再加上若干可选的脚本和参考文档。智能体启动时只读取每个技能的 name 和 description判断当前任务该不该触发它真正需要时才把SKILL.md正文读进上下文再按需加载附加文件。这套机制叫渐进式信息披露是理解整个技能体系的关键。官方示例里最典型的是 PDF 处理技能。它的目录长这样pdf/ ├── SKILL.md ├── reference.md ├── forms.md └── scripts/ └── extract_form_fields.pySKILL.md是入口reference.md放通用参考forms.md只在填表单场景才被读取scripts/里的 Python 脚本负责确定性的字段提取。这种拆分不是随便定的而是围绕「什么时候需要什么信息」来组织。你如果做过前端组件拆分会发现思路很像公共逻辑抽出去场景专属逻辑单独放按需引入。为什么目录结构值得单独拿出来讲因为很多人第一次写技能会把所有内容堆进SKILL.md结果上下文被塞满模型反而抓不住重点。官方示例给出的信号很明确SKILL.md只放「怎么判断该用我」和「核心操作步骤」细节全部外链。这样即使技能越写越多单个技能的加载成本依然可控。我建议你在本地建一个skills/根目录每个技能一个子文件夹名字用短横线小写比如pdf-forms、excel-report。文件夹名和SKILL.md里的 name 保持一致后续排查问题时一眼就能对上。目录结构定好之后接下来才是SKILL.md本身怎么写。2. SKILL.md 的 YAML 元数据与正文写法SKILL.md分两部分开头的 YAML 前置元数据和下面的 Markdown 正文。元数据只有两个必填项name 和 description。别看只有两个字段它们决定了技能会不会被触发是整个技能里最需要反复打磨的地方。一个可直接复制的模板如下--- name: pdf-forms description: 读取 PDF 文件、提取表单字段并填写表单。当用户需要处理 PDF 表单、提取字段或批量填写时使用。 --- # PDF 表单处理 ## 何时使用 当任务涉及 PDF 表单的读取、字段提取或填写时按以下步骤操作。 ## 操作步骤 1. 确认目标 PDF 路径存在。 2. 运行 scripts/extract_form_fields.py 提取字段脚本输出 JSON。 3. 根据 JSON 中的字段名构造填写内容。 4. 填写完成后回读校验。 ## 附加参考 - 通用 PDF 结构说明见 reference.md。 - 表单填写细则见 forms.md仅在填写场景读取。description 的写法有个实用技巧把「做什么」和「什么时候用」都写进去。官方示例的描述里既有功能说明也有触发条件。模型判断是否加载技能靠的就是这句话写得含糊就会出现该触发时不触发、不该触发时乱触发的情况。正文部分我习惯按「何时使用 / 操作步骤 / 附加参考」三段来写。操作步骤要具体到可执行比如「运行某个脚本」「读取某个文件」而不是「分析 PDF 内容」这种模糊表述。附加参考里明确写出文件名模型才知道去哪里找第三层信息。还有一个容易忽略的点如果技能里带了脚本要在正文里说清楚模型是「直接运行脚本」还是「把脚本读进上下文当参考」。这两种用法对模型的行为影响很大。确定性任务优先直接运行需要模型理解逻辑时才读进上下文。把这条写明白能省掉很多调试时间。3. 通过 TaoToken 统一 Key 与 API 通道接入技能写好了得让智能体真正跑起来。如果你在多个客户端之间切换每个都单独配 Key 会很乱。我一般用 TaoToken 做统一入口一个 Key 走通模型对话、编码计划和 API 调用。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。以 Claude Code 为例配置文件通常放在用户目录下的 settings 里。一个可复制的 JSON 片段如下{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的TaoToken Key, ANTHROPIC_MODEL: claude-sonnet-4-5 } }如果你用的是 Codex 系的工具配置写在auth.json里三件套同样是 Base URL、Key、Model ID{ base_url: https://taotoken.net/api, api_key: 你的TaoToken Key, model: claude-sonnet-4-5 }Cline 或 Roo 这类插件走 MCP 配置时也是同样的三件套思路把 Base URL 指向https://taotoken.net/api填入 Key再指定 Model ID 即可。三者的区别只在配置文件位置和字段名核心参数完全一致。这里要提醒一句Base URL 后面不要自己加/v1之类的路径按上面写的原样填。我见过有人手动补路径导致 404排查半天才发现是多写了一截。Key 的获取在控制台的 API Keys 页面模型对话入口可以用来先验证通道是否通。配好之后不要急着上复杂技能先用一个最小请求确认链路没问题。4. 本地加载技能并验证请求成功配置好通道后把技能文件夹放到智能体约定的技能目录下。不同客户端的技能目录不一样Claude Code 一般放在项目根目录的.claude/skills/下每个技能一个子文件夹。放好之后重启会话让智能体重新扫描技能元数据。验证分两步。第一步确认技能被识别第二步确认技能被正确触发。第一步发一条能命中 description 的消息比如「帮我看看这个 PDF 表单里有哪些字段」。如果技能被加载你会在工具调用记录里看到它读取了pdf/SKILL.md。这一步没出现读取动作说明 description 没匹配上回去改描述。第二步观察它是否按需读取了forms.md。如果任务只是提取字段它不应该读forms.md如果任务是填写表单它才应该读。这个行为能验证你的渐进式披露设计是否生效。一个成功的请求结果大概是这样模型先调用 Bash 工具读取SKILL.md然后运行scripts/extract_form_fields.py拿到 JSON 输出最后把字段列表整理给你。整个过程你不需要手动喂任何上下文技能自己完成了加载。如果脚本报错先单独在终端跑一遍确认脚本本身没问题再排查是不是路径写错了。技能里的相对路径是相对于技能文件夹的不是相对于项目根目录这点很容易搞混。5. 常见报错排查401、local proxy failed 与 OAuth接入过程中最常见的几类报错我按实际遇到的频率排一下。401 未授权基本是 Key 的问题。先确认 Key 有没有复制完整前后有没有多余空格。如果 Key 没问题检查 Base URL 是不是写成了带路径的形式。还有一种情况是 Key 过期或额度用尽去控制台的 API Keys 页面确认状态。local proxy failed 通常出现在本地代理配置冲突时。如果你本机开了其他网络工具可能会拦截请求。排查方法是先关掉其他工具只保留 TaoToken 的配置再发一次请求。如果通了说明是端口或代理冲突调整一下即可。reading choices这类报错一般和响应格式有关。有些客户端期望特定的返回结构如果模型 ID 填错返回结构对不上就会报这个。确认 Model ID 和客户端要求的一致比如 Claude Code 用claude-sonnet-4-5别填成别的系列。OAuth 相关报错多出现在需要登录授权的客户端。如果你用的是 API Key 模式就不该走 OAuth 流程。检查配置里是不是混入了 OAuth 字段把它删掉只保留 Base URL、Key、Model ID 三件套。技能本身不触发不算报错但很常见。九成是 description 写得太泛或太窄。把 description 改成「做什么 什么时候用」的结构再重启会话试试。如果还是不触发把技能文件夹名和 name 字段对齐有时候是命名不一致导致扫描不到。6. 把技能拼成乐高的实践建议技能真正的价值在于组合。单个 PDF 技能只能处理 PDF但如果你再写一个「报表生成」技能、一个「数据校验」技能三者串起来就能完成一条完整流水线。每个技能只管自己那一段通过SKILL.md里的引用关系互相衔接。我的做法是给每个技能写一句「上游输入」和「下游输出」的说明放在正文开头。这样组合的时候一眼就能看出哪个技能接哪个。比如 PDF 技能输出 JSON 字段报表技能接收 JSON 生成表格数据校验技能再对表格做检查。三个技能各自独立拼起来就是一条链。技能多了之后建议建一个索引文件列出所有技能的名称、描述和依赖关系。这个索引不放进任何技能的上下文只给你自己看。维护技能库和維護代码库一样索引能帮你快速定位该改哪个。最后说一个实际踩过的坑不要在一个技能里塞太多职责。我一开始把 PDF 读取、字段提取、表单填写、结果导出全写进一个技能结果SKILL.md越写越长模型加载后反而抓不住重点。拆成三个技能后每个都短小清晰触发准确率明显提升。技能就该像乐高积木一块只做一件事拼装的事交给组合逻辑。如果你还没开始建议先从官方 PDF 示例入手把目录结构和SKILL.md写法跑通一遍再动手写自己的第一个技能。通道配置用 TaoToken 统一管好后面加技能就只是往skills/目录里放文件夹的事。
Claude Skills（Agent Skills）官方示例拆解：用 SKILL.md 把智能体技能拼成乐高
1. 从官方 PDF 示例看 Claude Skills 的目录结构Claude Skills也叫 Agent Skills本质上就是一个文件夹里面放一份SKILL.md再加上若干可选的脚本和参考文档。智能体启动时只读取每个技能的 name 和 description判断当前任务该不该触发它真正需要时才把SKILL.md正文读进上下文再按需加载附加文件。这套机制叫渐进式信息披露是理解整个技能体系的关键。官方示例里最典型的是 PDF 处理技能。它的目录长这样pdf/ ├── SKILL.md ├── reference.md ├── forms.md └── scripts/ └── extract_form_fields.pySKILL.md是入口reference.md放通用参考forms.md只在填表单场景才被读取scripts/里的 Python 脚本负责确定性的字段提取。这种拆分不是随便定的而是围绕「什么时候需要什么信息」来组织。你如果做过前端组件拆分会发现思路很像公共逻辑抽出去场景专属逻辑单独放按需引入。为什么目录结构值得单独拿出来讲因为很多人第一次写技能会把所有内容堆进SKILL.md结果上下文被塞满模型反而抓不住重点。官方示例给出的信号很明确SKILL.md只放「怎么判断该用我」和「核心操作步骤」细节全部外链。这样即使技能越写越多单个技能的加载成本依然可控。我建议你在本地建一个skills/根目录每个技能一个子文件夹名字用短横线小写比如pdf-forms、excel-report。文件夹名和SKILL.md里的 name 保持一致后续排查问题时一眼就能对上。目录结构定好之后接下来才是SKILL.md本身怎么写。2. SKILL.md 的 YAML 元数据与正文写法SKILL.md分两部分开头的 YAML 前置元数据和下面的 Markdown 正文。元数据只有两个必填项name 和 description。别看只有两个字段它们决定了技能会不会被触发是整个技能里最需要反复打磨的地方。一个可直接复制的模板如下--- name: pdf-forms description: 读取 PDF 文件、提取表单字段并填写表单。当用户需要处理 PDF 表单、提取字段或批量填写时使用。 --- # PDF 表单处理 ## 何时使用 当任务涉及 PDF 表单的读取、字段提取或填写时按以下步骤操作。 ## 操作步骤 1. 确认目标 PDF 路径存在。 2. 运行 scripts/extract_form_fields.py 提取字段脚本输出 JSON。 3. 根据 JSON 中的字段名构造填写内容。 4. 填写完成后回读校验。 ## 附加参考 - 通用 PDF 结构说明见 reference.md。 - 表单填写细则见 forms.md仅在填写场景读取。description 的写法有个实用技巧把「做什么」和「什么时候用」都写进去。官方示例的描述里既有功能说明也有触发条件。模型判断是否加载技能靠的就是这句话写得含糊就会出现该触发时不触发、不该触发时乱触发的情况。正文部分我习惯按「何时使用 / 操作步骤 / 附加参考」三段来写。操作步骤要具体到可执行比如「运行某个脚本」「读取某个文件」而不是「分析 PDF 内容」这种模糊表述。附加参考里明确写出文件名模型才知道去哪里找第三层信息。还有一个容易忽略的点如果技能里带了脚本要在正文里说清楚模型是「直接运行脚本」还是「把脚本读进上下文当参考」。这两种用法对模型的行为影响很大。确定性任务优先直接运行需要模型理解逻辑时才读进上下文。把这条写明白能省掉很多调试时间。3. 通过 TaoToken 统一 Key 与 API 通道接入技能写好了得让智能体真正跑起来。如果你在多个客户端之间切换每个都单独配 Key 会很乱。我一般用 TaoToken 做统一入口一个 Key 走通模型对话、编码计划和 API 调用。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。以 Claude Code 为例配置文件通常放在用户目录下的 settings 里。一个可复制的 JSON 片段如下{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的TaoToken Key, ANTHROPIC_MODEL: claude-sonnet-4-5 } }如果你用的是 Codex 系的工具配置写在auth.json里三件套同样是 Base URL、Key、Model ID{ base_url: https://taotoken.net/api, api_key: 你的TaoToken Key, model: claude-sonnet-4-5 }Cline 或 Roo 这类插件走 MCP 配置时也是同样的三件套思路把 Base URL 指向https://taotoken.net/api填入 Key再指定 Model ID 即可。三者的区别只在配置文件位置和字段名核心参数完全一致。这里要提醒一句Base URL 后面不要自己加/v1之类的路径按上面写的原样填。我见过有人手动补路径导致 404排查半天才发现是多写了一截。Key 的获取在控制台的 API Keys 页面模型对话入口可以用来先验证通道是否通。配好之后不要急着上复杂技能先用一个最小请求确认链路没问题。4. 本地加载技能并验证请求成功配置好通道后把技能文件夹放到智能体约定的技能目录下。不同客户端的技能目录不一样Claude Code 一般放在项目根目录的.claude/skills/下每个技能一个子文件夹。放好之后重启会话让智能体重新扫描技能元数据。验证分两步。第一步确认技能被识别第二步确认技能被正确触发。第一步发一条能命中 description 的消息比如「帮我看看这个 PDF 表单里有哪些字段」。如果技能被加载你会在工具调用记录里看到它读取了pdf/SKILL.md。这一步没出现读取动作说明 description 没匹配上回去改描述。第二步观察它是否按需读取了forms.md。如果任务只是提取字段它不应该读forms.md如果任务是填写表单它才应该读。这个行为能验证你的渐进式披露设计是否生效。一个成功的请求结果大概是这样模型先调用 Bash 工具读取SKILL.md然后运行scripts/extract_form_fields.py拿到 JSON 输出最后把字段列表整理给你。整个过程你不需要手动喂任何上下文技能自己完成了加载。如果脚本报错先单独在终端跑一遍确认脚本本身没问题再排查是不是路径写错了。技能里的相对路径是相对于技能文件夹的不是相对于项目根目录这点很容易搞混。5. 常见报错排查401、local proxy failed 与 OAuth接入过程中最常见的几类报错我按实际遇到的频率排一下。401 未授权基本是 Key 的问题。先确认 Key 有没有复制完整前后有没有多余空格。如果 Key 没问题检查 Base URL 是不是写成了带路径的形式。还有一种情况是 Key 过期或额度用尽去控制台的 API Keys 页面确认状态。local proxy failed 通常出现在本地代理配置冲突时。如果你本机开了其他网络工具可能会拦截请求。排查方法是先关掉其他工具只保留 TaoToken 的配置再发一次请求。如果通了说明是端口或代理冲突调整一下即可。reading choices这类报错一般和响应格式有关。有些客户端期望特定的返回结构如果模型 ID 填错返回结构对不上就会报这个。确认 Model ID 和客户端要求的一致比如 Claude Code 用claude-sonnet-4-5别填成别的系列。OAuth 相关报错多出现在需要登录授权的客户端。如果你用的是 API Key 模式就不该走 OAuth 流程。检查配置里是不是混入了 OAuth 字段把它删掉只保留 Base URL、Key、Model ID 三件套。技能本身不触发不算报错但很常见。九成是 description 写得太泛或太窄。把 description 改成「做什么 什么时候用」的结构再重启会话试试。如果还是不触发把技能文件夹名和 name 字段对齐有时候是命名不一致导致扫描不到。6. 把技能拼成乐高的实践建议技能真正的价值在于组合。单个 PDF 技能只能处理 PDF但如果你再写一个「报表生成」技能、一个「数据校验」技能三者串起来就能完成一条完整流水线。每个技能只管自己那一段通过SKILL.md里的引用关系互相衔接。我的做法是给每个技能写一句「上游输入」和「下游输出」的说明放在正文开头。这样组合的时候一眼就能看出哪个技能接哪个。比如 PDF 技能输出 JSON 字段报表技能接收 JSON 生成表格数据校验技能再对表格做检查。三个技能各自独立拼起来就是一条链。技能多了之后建议建一个索引文件列出所有技能的名称、描述和依赖关系。这个索引不放进任何技能的上下文只给你自己看。维护技能库和維護代码库一样索引能帮你快速定位该改哪个。最后说一个实际踩过的坑不要在一个技能里塞太多职责。我一开始把 PDF 读取、字段提取、表单填写、结果导出全写进一个技能结果SKILL.md越写越长模型加载后反而抓不住重点。拆成三个技能后每个都短小清晰触发准确率明显提升。技能就该像乐高积木一块只做一件事拼装的事交给组合逻辑。如果你还没开始建议先从官方 PDF 示例入手把目录结构和SKILL.md写法跑通一遍再动手写自己的第一个技能。通道配置用 TaoToken 统一管好后面加技能就只是往skills/目录里放文件夹的事。