1. 为什么你的 AI 代理总是“差口气”很多人用 Claude 或其它大模型做自动化任务时都会遇到同一个尴尬模型很聪明但每次让它干具体活比如“把这个 PDF 里的表单字段抽出来填到模板里”它要么漏字段要么格式跑偏要么把整段 PDF 内容硬塞进上下文token 烧得飞快结果还不稳定。问题不在模型本身而在于我们一直用“一次性对话”的方式驱动它。你给它的提示词再长也只是一次性的指令没有结构化的知识封装没有可复用的执行路径更没有按需加载的机制。Claude Skills 就是来解决这个问题的。简单说Claude Skills 是一套让 AI 代理按需加载“技能包”的机制。每个技能包是一个标准目录核心是SKILL.md文件里面用 YAML Frontmatter 声明技能名称和触发描述正文写执行步骤还可以捆绑脚本、参考文档和静态资源。代理启动时只预加载所有技能的 name 和 description判断当前任务匹配哪个技能后才读取完整内容。这就是“渐进式披露”既省上下文又让代理在特定领域表现得更专业。它适合谁适合那些不想每次重复写长提示词、希望把多步任务固化下来、让大模型自动执行确定性流程的开发者。你可以把它理解成给 AI 代理写“入职手册”新员工不用你每天口头交代手册里写清楚什么场景做什么、怎么做、遇到问题怎么办。这篇文章我会带你从零搭一个可用的SKILL.md骨架配好 TaoToken 统一 Key 接入 AI 工具的settings.json然后实际验证 Skills 加载和代理调用是否生效。全程可复制踩过的坑我也会标出来。2. TaoToken 前置统一 Key 接入 AI 工具在真正写 Skills 之前得先把模型接入层理顺。你可能会用 Claude Code、Cursor、Continue 或者自己写的 Agent 脚本如果每个工具都单独配一套 Key 和 endpoint管理起来很乱。TaoToken 的作用就是提供一个统一的 API 入口你申请一个 Key然后在各个 AI 工具的配置里指向同一个地址即可。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基础地址是 https://taotoken.net/api 。注意 API 地址后面不加 UTM 参数直接用于配置。你需要先拿到 API Key。进入控制台创建 Key 的入口在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建好之后复制保存后面配置里要用。这里要区分两个概念TaoToken 是统一接入层Claude Skills 是代理能力扩展机制。前者解决“怎么连上模型”后者解决“连上之后怎么让模型按你的流程干活”。两者配合你才能在一个稳定的接入环境里测试 Skills 是否生效。如果你主要做长期编码或 Agent 任务可以关注 Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 里面有适合持续开发场景的配置说明。模型对话调试入口在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。Claude Code 相关配置参考 https://taotoken.net/claudecode?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。3. 可复制配置SKILL.md 骨架与 settings.json3.1 SKILL.md 完整骨架先建目录。推荐结构如下my-skill/ ├── SKILL.md ├── scripts/ │ └── extract_fields.py ├── references/ │ └── field_schema.md └── assets/ └── template.htmlSKILL.md分两部分YAML Frontmatter 和 Markdown 正文。下面是一个可直接复制的骨架我以“PDF 表单字段抽取”为例--- name: pdf-form-extractor description: 当用户需要从 PDF 文件中提取表单字段并填充到 HTML 模板时使用此技能。适用于批量处理发票、申请表等结构化文档。 license: MIT allowed-tools: - Bash - Read - Write model: claude-sonnet-4-20250514 version: 1.0.0 --- # PDF 表单字段抽取技能 ## 概述 本技能用于从 PDF 中提取表单字段按 schema 校验后填充到 HTML 模板。适用于需要确定性输出的批量文档处理场景。 ## 前置条件 - 已安装 Python 3.10 - 已安装 pdfplumber 和 jinja2 - 待处理 PDF 放在 {baseDir}/input/ 目录下 ## 操作步骤 ### 步骤 1扫描输入目录 使用 Bash 工具列出 {baseDir}/input/ 下所有 PDF 文件确认待处理列表。 ### 步骤 2调用抽取脚本 执行以下命令 bash python {baseDir}/scripts/extract_fields.py --input {baseDir}/input/ --schema {baseDir}/references/field_schema.md步骤 3校验字段读取脚本输出的 JSON对照 {baseDir}/references/field_schema.md 检查必填字段是否齐全。缺失字段记录到日志。步骤 4填充模板使用抽取结果渲染 {baseDir}/assets/template.html输出到 {baseDir}/output/。输出格式每个 PDF 生成一个同名 HTML 文件另生成一份 summary.json 记录处理状态。错误处理PDF 无法解析跳过并记录文件名到 error.log字段缺失用空字符串占位在 summary.json 中标记 warning脚本执行失败检查 Python 依赖是否安装示例输入invoice_001.pdf 输出output/invoice_001.html summary.json相关资源scripts/extract_fields.py字段抽取脚本references/field_schema.md字段定义与校验规则assets/template.html输出模板几个关键点。name 用 kebab-case简洁唯一。description 是触发判定的核心要写清楚“什么时候用”用行动导向的语言。allowed-tools 列出该技能可自动使用的工具避免每次弹审批。model 可选复杂任务可以指定更强的模型。正文控制在 5000 字以内细节放外部文件。 ### 3.2 settings.json 接入示例 如果你用 Claude Code 或类似支持 settings.json 的工具可以这样配置 TaoToken 接入 json { apiKey: 你的_TaoToken_API_Key, baseUrl: https://taotoken.net/api, model: claude-sonnet-4-20250514, skills: { enabled: true, directories: [ ./skills/pdf-form-extractor, ./skills/brand-guidelines ] }, permissions: { allow: [ Bash(python:*), Read, Write ] } }把apiKey换成你在 TaoToken 控制台创建的那个 Key。baseUrl固定为https://taotoken.net/api。skills.directories指向你本地技能目录支持多个技能叠加。permissions.allow里的工具要和SKILL.md中allowed-tools对应否则代理调用时会被拦截。如果你用的是其它编辑器或自建 Agent配置字段名可能不同但核心就三样API Key、baseUrl、技能目录路径。接入文档里有各工具的详细说明遇到字段对不上可以去查。4. 验证请求Skills 加载与代理调用是否生效配置写完不代表生效得实际验证。分两步先确认 Skills 被正确加载再确认代理在任务中真的调用了技能。4.1 验证 Skills 加载启动你的 AI 工具后在对话里输入列出当前已加载的所有 skills包括 name 和 description。如果配置正确代理会返回类似已加载技能 1. pdf-form-extractor - 当用户需要从 PDF 文件中提取表单字段并填充到 HTML 模板时使用此技能... 2. brand-guidelines - 当用户需要检查品牌文案合规性时使用此技能...如果返回为空说明技能目录没被扫描到。检查settings.json里的skills.directories路径是否正确以及每个技能目录下是否有SKILL.md文件。路径建议用相对路径避免硬编码绝对路径。4.2 验证代理调用加载确认后发一个会触发技能的任务帮我处理 input/ 目录下的 PDF提取表单字段并填充模板。观察代理的执行过程。正常情况下它会先匹配到pdf-form-extractor技能然后按SKILL.md里的步骤依次执行扫描目录、调用脚本、校验字段、填充模板。你可以在输出里看到它读取了references/field_schema.md和assets/template.html这说明渐进式披露在工作它没有一次性把所有文件塞进上下文。如果代理没有调用技能而是自己瞎编流程检查description是否写得太模糊。触发判定只看 name 和 description描述里要包含用户可能说的关键词比如“PDF”“表单”“提取”“填充模板”。4.3 用模型对话快速验证如果你只想先验证模型接入是否正常可以打开模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 发一条简单请求确认 Key 和 baseUrl 配置无误。模型对话通了再排查 Skills 配置能少走弯路。5. 本篇常见错排查5.1 SKILL.md 的 YAML 格式错误最常见的问题是 Frontmatter 的 YAML 语法写错。比如description里用了冒号但没加引号或者缩进用了 Tab。YAML 对缩进敏感统一用两个空格。如果代理报“无法解析技能元数据”先检查---开头和结尾是否成对中间字段是否合法。5.2 description 写得太泛导致不触发有人把description写成“处理文档”结果代理永远不调用。触发判定是语义匹配描述要具体到场景和动作。对比一下差处理文档相关任务。 好当用户需要从 PDF 文件中提取表单字段并填充到 HTML 模板时使用此技能。后者包含“PDF”“表单字段”“提取”“填充模板”这些用户可能说的词匹配概率高得多。5.3 allowed-tools 与 permissions 不匹配SKILL.md里声明了Bash但settings.json的permissions.allow里没有Bash(python:*)代理执行脚本时会被拦截表现为“技能加载了但执行到某步卡住”。两边要对应上。如果你不确定先把permissions.allow放宽一点测试跑通后再收紧。5.4 脚本路径硬编码SKILL.md里引用脚本时不要写/home/user/project/scripts/extract.py这种绝对路径。用{baseDir}变量代理会自动注入技能根目录。硬编码路径换台机器就失效而且容易暴露本地目录结构。5.5 上下文过载导致技能被忽略如果SKILL.md正文写了几万字代理可能在预加载阶段就消耗大量上下文反而影响触发判定。正文控制在 5000 字以内长文档放references/用文件名引用。渐进式披露的意义就是按需加载别把该放附录的内容塞进目录。5.6 多技能叠加时的优先级冲突当你同时启用多个技能且它们的description有重叠时代理可能选错。解决办法是在描述里加区分词比如一个写“PDF 表单字段抽取”另一个写“PDF 文本摘要生成”避免都用“PDF 处理”这种泛词。如果冲突严重可以用disable-model-invocation: true让某个技能只能手动触发。6. 把 Skills 用起来从单次对话到可复用能力写到这里你已经有了一个可复制的SKILL.md骨架、一份 TaoToken 接入的settings.json示例以及验证加载和调用的具体动作。接下来就是把它用到实际任务里。我的建议是先从一个小技能开始比如“把 Markdown 转成带样式的 HTML”或者“检查代码里的 TODO 并生成清单”。技能不用大关键是跑通“定义→加载→触发→执行→输出”这个闭环。跑通一个之后你会发现后面加技能就是复制目录、改SKILL.md、调脚本的事。如果你要做长期编码或 Agent 开发Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 里有持续任务的配置思路。接入过程中遇到 Key 或 endpoint 问题去 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 检查 Key 状态或者翻接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 对照字段。最后提醒一句Skills 的触发判定只依赖 name 和 description这两个字段值得你反复打磨。我试过把 description 改了三版才让代理稳定触发别指望一次写对。跑起来看日志调描述这才是让大模型真正为你打工的路径。
1. 为什么你的 AI 代理总是“差口气”很多人用 Claude 或其它大模型做自动化任务时都会遇到同一个尴尬模型很聪明但每次让它干具体活比如“把这个 PDF 里的表单字段抽出来填到模板里”它要么漏字段要么格式跑偏要么把整段 PDF 内容硬塞进上下文token 烧得飞快结果还不稳定。问题不在模型本身而在于我们一直用“一次性对话”的方式驱动它。你给它的提示词再长也只是一次性的指令没有结构化的知识封装没有可复用的执行路径更没有按需加载的机制。Claude Skills 就是来解决这个问题的。简单说Claude Skills 是一套让 AI 代理按需加载“技能包”的机制。每个技能包是一个标准目录核心是SKILL.md文件里面用 YAML Frontmatter 声明技能名称和触发描述正文写执行步骤还可以捆绑脚本、参考文档和静态资源。代理启动时只预加载所有技能的 name 和 description判断当前任务匹配哪个技能后才读取完整内容。这就是“渐进式披露”既省上下文又让代理在特定领域表现得更专业。它适合谁适合那些不想每次重复写长提示词、希望把多步任务固化下来、让大模型自动执行确定性流程的开发者。你可以把它理解成给 AI 代理写“入职手册”新员工不用你每天口头交代手册里写清楚什么场景做什么、怎么做、遇到问题怎么办。这篇文章我会带你从零搭一个可用的SKILL.md骨架配好 TaoToken 统一 Key 接入 AI 工具的settings.json然后实际验证 Skills 加载和代理调用是否生效。全程可复制踩过的坑我也会标出来。2. TaoToken 前置统一 Key 接入 AI 工具在真正写 Skills 之前得先把模型接入层理顺。你可能会用 Claude Code、Cursor、Continue 或者自己写的 Agent 脚本如果每个工具都单独配一套 Key 和 endpoint管理起来很乱。TaoToken 的作用就是提供一个统一的 API 入口你申请一个 Key然后在各个 AI 工具的配置里指向同一个地址即可。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基础地址是 https://taotoken.net/api 。注意 API 地址后面不加 UTM 参数直接用于配置。你需要先拿到 API Key。进入控制台创建 Key 的入口在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建好之后复制保存后面配置里要用。这里要区分两个概念TaoToken 是统一接入层Claude Skills 是代理能力扩展机制。前者解决“怎么连上模型”后者解决“连上之后怎么让模型按你的流程干活”。两者配合你才能在一个稳定的接入环境里测试 Skills 是否生效。如果你主要做长期编码或 Agent 任务可以关注 Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 里面有适合持续开发场景的配置说明。模型对话调试入口在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。Claude Code 相关配置参考 https://taotoken.net/claudecode?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。3. 可复制配置SKILL.md 骨架与 settings.json3.1 SKILL.md 完整骨架先建目录。推荐结构如下my-skill/ ├── SKILL.md ├── scripts/ │ └── extract_fields.py ├── references/ │ └── field_schema.md └── assets/ └── template.htmlSKILL.md分两部分YAML Frontmatter 和 Markdown 正文。下面是一个可直接复制的骨架我以“PDF 表单字段抽取”为例--- name: pdf-form-extractor description: 当用户需要从 PDF 文件中提取表单字段并填充到 HTML 模板时使用此技能。适用于批量处理发票、申请表等结构化文档。 license: MIT allowed-tools: - Bash - Read - Write model: claude-sonnet-4-20250514 version: 1.0.0 --- # PDF 表单字段抽取技能 ## 概述 本技能用于从 PDF 中提取表单字段按 schema 校验后填充到 HTML 模板。适用于需要确定性输出的批量文档处理场景。 ## 前置条件 - 已安装 Python 3.10 - 已安装 pdfplumber 和 jinja2 - 待处理 PDF 放在 {baseDir}/input/ 目录下 ## 操作步骤 ### 步骤 1扫描输入目录 使用 Bash 工具列出 {baseDir}/input/ 下所有 PDF 文件确认待处理列表。 ### 步骤 2调用抽取脚本 执行以下命令 bash python {baseDir}/scripts/extract_fields.py --input {baseDir}/input/ --schema {baseDir}/references/field_schema.md步骤 3校验字段读取脚本输出的 JSON对照 {baseDir}/references/field_schema.md 检查必填字段是否齐全。缺失字段记录到日志。步骤 4填充模板使用抽取结果渲染 {baseDir}/assets/template.html输出到 {baseDir}/output/。输出格式每个 PDF 生成一个同名 HTML 文件另生成一份 summary.json 记录处理状态。错误处理PDF 无法解析跳过并记录文件名到 error.log字段缺失用空字符串占位在 summary.json 中标记 warning脚本执行失败检查 Python 依赖是否安装示例输入invoice_001.pdf 输出output/invoice_001.html summary.json相关资源scripts/extract_fields.py字段抽取脚本references/field_schema.md字段定义与校验规则assets/template.html输出模板几个关键点。name 用 kebab-case简洁唯一。description 是触发判定的核心要写清楚“什么时候用”用行动导向的语言。allowed-tools 列出该技能可自动使用的工具避免每次弹审批。model 可选复杂任务可以指定更强的模型。正文控制在 5000 字以内细节放外部文件。 ### 3.2 settings.json 接入示例 如果你用 Claude Code 或类似支持 settings.json 的工具可以这样配置 TaoToken 接入 json { apiKey: 你的_TaoToken_API_Key, baseUrl: https://taotoken.net/api, model: claude-sonnet-4-20250514, skills: { enabled: true, directories: [ ./skills/pdf-form-extractor, ./skills/brand-guidelines ] }, permissions: { allow: [ Bash(python:*), Read, Write ] } }把apiKey换成你在 TaoToken 控制台创建的那个 Key。baseUrl固定为https://taotoken.net/api。skills.directories指向你本地技能目录支持多个技能叠加。permissions.allow里的工具要和SKILL.md中allowed-tools对应否则代理调用时会被拦截。如果你用的是其它编辑器或自建 Agent配置字段名可能不同但核心就三样API Key、baseUrl、技能目录路径。接入文档里有各工具的详细说明遇到字段对不上可以去查。4. 验证请求Skills 加载与代理调用是否生效配置写完不代表生效得实际验证。分两步先确认 Skills 被正确加载再确认代理在任务中真的调用了技能。4.1 验证 Skills 加载启动你的 AI 工具后在对话里输入列出当前已加载的所有 skills包括 name 和 description。如果配置正确代理会返回类似已加载技能 1. pdf-form-extractor - 当用户需要从 PDF 文件中提取表单字段并填充到 HTML 模板时使用此技能... 2. brand-guidelines - 当用户需要检查品牌文案合规性时使用此技能...如果返回为空说明技能目录没被扫描到。检查settings.json里的skills.directories路径是否正确以及每个技能目录下是否有SKILL.md文件。路径建议用相对路径避免硬编码绝对路径。4.2 验证代理调用加载确认后发一个会触发技能的任务帮我处理 input/ 目录下的 PDF提取表单字段并填充模板。观察代理的执行过程。正常情况下它会先匹配到pdf-form-extractor技能然后按SKILL.md里的步骤依次执行扫描目录、调用脚本、校验字段、填充模板。你可以在输出里看到它读取了references/field_schema.md和assets/template.html这说明渐进式披露在工作它没有一次性把所有文件塞进上下文。如果代理没有调用技能而是自己瞎编流程检查description是否写得太模糊。触发判定只看 name 和 description描述里要包含用户可能说的关键词比如“PDF”“表单”“提取”“填充模板”。4.3 用模型对话快速验证如果你只想先验证模型接入是否正常可以打开模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 发一条简单请求确认 Key 和 baseUrl 配置无误。模型对话通了再排查 Skills 配置能少走弯路。5. 本篇常见错排查5.1 SKILL.md 的 YAML 格式错误最常见的问题是 Frontmatter 的 YAML 语法写错。比如description里用了冒号但没加引号或者缩进用了 Tab。YAML 对缩进敏感统一用两个空格。如果代理报“无法解析技能元数据”先检查---开头和结尾是否成对中间字段是否合法。5.2 description 写得太泛导致不触发有人把description写成“处理文档”结果代理永远不调用。触发判定是语义匹配描述要具体到场景和动作。对比一下差处理文档相关任务。 好当用户需要从 PDF 文件中提取表单字段并填充到 HTML 模板时使用此技能。后者包含“PDF”“表单字段”“提取”“填充模板”这些用户可能说的词匹配概率高得多。5.3 allowed-tools 与 permissions 不匹配SKILL.md里声明了Bash但settings.json的permissions.allow里没有Bash(python:*)代理执行脚本时会被拦截表现为“技能加载了但执行到某步卡住”。两边要对应上。如果你不确定先把permissions.allow放宽一点测试跑通后再收紧。5.4 脚本路径硬编码SKILL.md里引用脚本时不要写/home/user/project/scripts/extract.py这种绝对路径。用{baseDir}变量代理会自动注入技能根目录。硬编码路径换台机器就失效而且容易暴露本地目录结构。5.5 上下文过载导致技能被忽略如果SKILL.md正文写了几万字代理可能在预加载阶段就消耗大量上下文反而影响触发判定。正文控制在 5000 字以内长文档放references/用文件名引用。渐进式披露的意义就是按需加载别把该放附录的内容塞进目录。5.6 多技能叠加时的优先级冲突当你同时启用多个技能且它们的description有重叠时代理可能选错。解决办法是在描述里加区分词比如一个写“PDF 表单字段抽取”另一个写“PDF 文本摘要生成”避免都用“PDF 处理”这种泛词。如果冲突严重可以用disable-model-invocation: true让某个技能只能手动触发。6. 把 Skills 用起来从单次对话到可复用能力写到这里你已经有了一个可复制的SKILL.md骨架、一份 TaoToken 接入的settings.json示例以及验证加载和调用的具体动作。接下来就是把它用到实际任务里。我的建议是先从一个小技能开始比如“把 Markdown 转成带样式的 HTML”或者“检查代码里的 TODO 并生成清单”。技能不用大关键是跑通“定义→加载→触发→执行→输出”这个闭环。跑通一个之后你会发现后面加技能就是复制目录、改SKILL.md、调脚本的事。如果你要做长期编码或 Agent 开发Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 里有持续任务的配置思路。接入过程中遇到 Key 或 endpoint 问题去 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 检查 Key 状态或者翻接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 对照字段。最后提醒一句Skills 的触发判定只依赖 name 和 description这两个字段值得你反复打磨。我试过把 description 改了三版才让代理稳定触发别指望一次写对。跑起来看日志调描述这才是让大模型真正为你打工的路径。
