1. 为什么你的 Agent 越写越像“万能工具人”我见过太多团队在构建 AI Agent 时踩同一个坑把代码审查、数据分析、文档生成、邮件处理、日程管理全部塞进一个 system prompt结果 prompt 膨胀到上万 token每次调用都在烧钱而且每个任务都做得马马虎虎。更麻烦的是改一个功能可能影响整体团队协作时谁也不敢动那段“祖传 prompt”。Claude Skills 给出的解法很直接不要造一个全能巨型 Agent而是让 Agent 拥有一组可组合的专业技能需要时按需加载。它的核心机制叫渐进式加载Progressive Disclosure分三级Level 1 元数据总是加载约 100 token/SkillLevel 2 的 SKILL.md 在技能被触发时才读取Level 3 的脚本和参考资料按需调用脚本代码本身不进入上下文只有输出消耗 token。这篇文章面向想让 Agent 具备“自学”能力的开发者我会给出可复制的 SKILL.md 骨架模板、TaoToken 统一 Key/API 通道的接入步骤并演示一次完整的技能加载与触发验证。你不需要先成为 Anthropic 内部专家跟着做就能跑通。2. 前置准备用 TaoToken 统一 Key 打通模型通道在写 SKILL.md 之前先把模型调用通道理顺。很多开发者的痛点是不同模型、不同 Agent 框架各要一套 Key切换环境时配置散落各处。TaoToken 提供统一 Key 和 API 通道官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 端点为 https://taotoken.net/api不加 UTM。你需要先拿到 API Key。登录后进入控制台在 API Keys 页面创建一个新 Key建议按项目命名比如claude-skills-demo方便后续排查。创建后立即复制保存页面刷新后不会再完整显示。拿到 Key 后把它写进环境变量不要硬编码在代码里export TAOTOKEN_API_KEYsk-你的实际Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用的是 Python可以这样初始化客户端。注意 base_url 要指向 TaoToken 的 API 端点模型名按你实际开通的填写import os from anthropic import Anthropic client Anthropic( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], ) resp client.messages.create( modelclaude-3-5-sonnet-20241022, max_tokens512, messages[{role: user, content: 用一句话说明什么是渐进式加载}], ) print(resp.content[0].text)这一步能跑通说明你的 Key 和通道没问题。如果报 401先检查 Key 是否复制完整如果报连接错误检查 base_url 是否写成了带 UTM 的官网地址——API 调用只认 https://taotoken.net/api。3. 可复制配置SKILL.md 骨架与目录结构Skill 的本质是一个目录核心是 SKILL.md。它的 YAML frontmatter 决定 Level 1 元数据正文决定 Level 2 指令引用的脚本和文档构成 Level 3。下面是一个可直接复制的骨架我以“日志排障专家”为例你可以替换成自己的领域。目录结构建议这样组织log-triage-skill/ ├── SKILL.md ├── ADVANCED.md ├── scripts/ │ ├── parse_log.py │ └── summarize.py └── schemas/ └── error_codes.jsonSKILL.md 的 frontmatter 最关键的是 description它决定 Claude 何时触发这个 Skill。写法要包含“做什么”和“何时用”--- name: log-triage-expert description: 分析应用日志、定位错误码、聚合异常堆栈。当用户提到日志、报错、异常、error code、stack trace 或需要排查线上问题时使用。 --- # 日志排障专家 ## 概述 面向线上故障排查提供日志解析、错误聚合、根因初筛能力。 ## 快速开始 先用解析脚本把原始日志转成结构化 JSON bash python scripts/parse_log.py app.log --output parsed.json脚本会输出错误码分布和 Top 异常堆栈只有这份摘要进入上下文。进阶需要关联错误码含义时查看 ADVANCED.md 和 schemas/error_codes.json。最佳实践先看错误码分布再钻取单个堆栈时间窗口对齐发布记录聚合后再判断是否为同一根因这里有个设计要点SKILL.md 正文不要写太长把详细内容拆到 ADVANCED.md。因为 Level 2 是触发时加载的写得太长会吃掉上下文而 ADVANCED.md 属于 Level 3只有真正需要时才读取。 脚本部分同样遵循“代码不进上下文”的原则。parse_log.py 可以写几百行复杂逻辑Claude 只通过 bash 执行它拿到的只有 stdout python #!/usr/bin/env python3 import json import sys from collections import Counter def parse(path): codes Counter() stacks Counter() with open(path, encodingutf-8) as f: for line in f: if ERROR in line: parts line.split() for p in parts: if p.startswith(E) and p[1:].isdigit(): codes[p] 1 stacks[line.strip()[:120]] 1 return { error_codes: codes.most_common(10), top_stacks: stacks.most_common(5), } if __name__ __main__: result parse(sys.argv[1]) print(json.dumps(result, ensure_asciiFalse, indent2))这个脚本无论多复杂进入上下文的只有最后那段 JSON通常不到 100 token。这就是 Skills 相比“让模型现场生成代码”的最大优势确定性加零上下文占用。4. 验证请求一次技能加载与触发的完整演示配置写好后必须验证 Skill 是否真的被触发、加载层级是否符合预期。我用一段会命中日志排障场景的请求来演示import os from anthropic import Anthropic client Anthropic( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], ) resp client.messages.create( modelclaude-3-5-sonnet-20241022, max_tokens1024, tools[{type: code_execution, container_id: log-triage-expert}], messages[{ role: user, content: app.log 里出现大量 E5003 报错帮我定位一下根因 }], ) print(resp.content[0].text)预期行为分三步。第一启动时 Level 1 元数据已加载Claude 知道存在 log-triage-expert 这个技能。第二用户请求命中 description 中的“报错”“日志”Claude 读取 SKILL.md学到标准流程是先跑 parse_log.py。第三Claude 执行脚本只有脚本输出的错误码分布进入上下文然后基于摘要给出根因初筛。验证成功的标志有三个响应里出现了对错误码分布的引用执行过程调用了 parse_log.py 而不是现场生成解析代码整体 token 消耗明显低于把全部日志塞进 prompt 的方式。你可以对比一下传统方式把 2MB 日志直接贴进对话轻松上万 tokenSkills 方式只有脚本输出的几百 token 摘要。如果想让验证更直观可以在脚本里加一行 stderr 日志观察它是否被执行python scripts/parse_log.py app.log --output parsed.json 2debug.log cat debug.log看到 debug.log 有内容说明脚本确实被调用了而不是模型在“假装”分析。5. 本篇常见错排查第一个高频错误是 Skill 不触发。九成情况出在 description 写得太泛比如只写“日志处理工具”。Claude 判断是否加载靠的是语义匹配description 里必须包含用户可能说的触发词。改成“当用户提到日志、报错、异常、stack trace 时使用”之后命中率会明显上升。第二个错误是 SKILL.md 写成了百科全书。有人把几千行文档全塞进正文结果 Level 2 一加载就爆上下文渐进式加载的优势荡然无存。正确做法是正文只留流程和索引细节拆到 ADVANCED.md、REFERENCE.md让它们留在 Level 3。第三个错误是脚本路径写相对路径。Claude 执行 bash 时的工作目录不一定是你以为的那个建议在 SKILL.md 里写清完整调用方式或者用$(dirname $0)这类方式定位。实测下来路径问题导致的“脚本找不到”占了排障时间的一大半。第四个错误是 API 通道配置混淆。官网地址带 UTM 参数API 端点不带两者不能混用。如果你在代码里把 base_url 写成了官网链接会直接连接失败。正确端点是 https://taotoken.net/api。Key 相关操作在 API Keys 页面完成接入细节可对照接入文档。第五个错误是忽略脚本输出的体积。脚本虽然不占上下文但如果它 print 了一万行日志输出照样会撑爆窗口。养成习惯脚本只输出结构化摘要原始数据写文件需要时再按需读取。6. 把 Skill 用起来从验证到长期编码跑通一次验证只是开始。如果你打算把 Skills 用在长期编码或 Agent 工作流里建议把常用能力拆成独立 Skill 目录每个目录单一职责团队按目录分工开发。这样新增能力时只需加一个 Skill不用动主 prompt。对于需要持续调用模型、跑长任务的场景可以了解 Coding Plan它更适合长期编码和 Agent 类负载。日常调试模型行为、快速验证 Skill 触发是否符合预期用模型对话就够了。Key 的创建和管理统一在 API Keys 页面接入参数和示例参考接入文档。最后留一个实用习惯每次改完 SKILL.md先跑一遍触发验证确认 description 命中、Level 2 加载、Level 3 按需调用这三步都正常再提交到团队仓库。Skill 的渐进式加载不是玄学它就是把“人类查手册”的机制搬进了 Agent你只要把手册的目录写清楚Agent 自然知道什么时候翻哪一页。
1. 为什么你的 Agent 越写越像“万能工具人”我见过太多团队在构建 AI Agent 时踩同一个坑把代码审查、数据分析、文档生成、邮件处理、日程管理全部塞进一个 system prompt结果 prompt 膨胀到上万 token每次调用都在烧钱而且每个任务都做得马马虎虎。更麻烦的是改一个功能可能影响整体团队协作时谁也不敢动那段“祖传 prompt”。Claude Skills 给出的解法很直接不要造一个全能巨型 Agent而是让 Agent 拥有一组可组合的专业技能需要时按需加载。它的核心机制叫渐进式加载Progressive Disclosure分三级Level 1 元数据总是加载约 100 token/SkillLevel 2 的 SKILL.md 在技能被触发时才读取Level 3 的脚本和参考资料按需调用脚本代码本身不进入上下文只有输出消耗 token。这篇文章面向想让 Agent 具备“自学”能力的开发者我会给出可复制的 SKILL.md 骨架模板、TaoToken 统一 Key/API 通道的接入步骤并演示一次完整的技能加载与触发验证。你不需要先成为 Anthropic 内部专家跟着做就能跑通。2. 前置准备用 TaoToken 统一 Key 打通模型通道在写 SKILL.md 之前先把模型调用通道理顺。很多开发者的痛点是不同模型、不同 Agent 框架各要一套 Key切换环境时配置散落各处。TaoToken 提供统一 Key 和 API 通道官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 端点为 https://taotoken.net/api不加 UTM。你需要先拿到 API Key。登录后进入控制台在 API Keys 页面创建一个新 Key建议按项目命名比如claude-skills-demo方便后续排查。创建后立即复制保存页面刷新后不会再完整显示。拿到 Key 后把它写进环境变量不要硬编码在代码里export TAOTOKEN_API_KEYsk-你的实际Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用的是 Python可以这样初始化客户端。注意 base_url 要指向 TaoToken 的 API 端点模型名按你实际开通的填写import os from anthropic import Anthropic client Anthropic( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], ) resp client.messages.create( modelclaude-3-5-sonnet-20241022, max_tokens512, messages[{role: user, content: 用一句话说明什么是渐进式加载}], ) print(resp.content[0].text)这一步能跑通说明你的 Key 和通道没问题。如果报 401先检查 Key 是否复制完整如果报连接错误检查 base_url 是否写成了带 UTM 的官网地址——API 调用只认 https://taotoken.net/api。3. 可复制配置SKILL.md 骨架与目录结构Skill 的本质是一个目录核心是 SKILL.md。它的 YAML frontmatter 决定 Level 1 元数据正文决定 Level 2 指令引用的脚本和文档构成 Level 3。下面是一个可直接复制的骨架我以“日志排障专家”为例你可以替换成自己的领域。目录结构建议这样组织log-triage-skill/ ├── SKILL.md ├── ADVANCED.md ├── scripts/ │ ├── parse_log.py │ └── summarize.py └── schemas/ └── error_codes.jsonSKILL.md 的 frontmatter 最关键的是 description它决定 Claude 何时触发这个 Skill。写法要包含“做什么”和“何时用”--- name: log-triage-expert description: 分析应用日志、定位错误码、聚合异常堆栈。当用户提到日志、报错、异常、error code、stack trace 或需要排查线上问题时使用。 --- # 日志排障专家 ## 概述 面向线上故障排查提供日志解析、错误聚合、根因初筛能力。 ## 快速开始 先用解析脚本把原始日志转成结构化 JSON bash python scripts/parse_log.py app.log --output parsed.json脚本会输出错误码分布和 Top 异常堆栈只有这份摘要进入上下文。进阶需要关联错误码含义时查看 ADVANCED.md 和 schemas/error_codes.json。最佳实践先看错误码分布再钻取单个堆栈时间窗口对齐发布记录聚合后再判断是否为同一根因这里有个设计要点SKILL.md 正文不要写太长把详细内容拆到 ADVANCED.md。因为 Level 2 是触发时加载的写得太长会吃掉上下文而 ADVANCED.md 属于 Level 3只有真正需要时才读取。 脚本部分同样遵循“代码不进上下文”的原则。parse_log.py 可以写几百行复杂逻辑Claude 只通过 bash 执行它拿到的只有 stdout python #!/usr/bin/env python3 import json import sys from collections import Counter def parse(path): codes Counter() stacks Counter() with open(path, encodingutf-8) as f: for line in f: if ERROR in line: parts line.split() for p in parts: if p.startswith(E) and p[1:].isdigit(): codes[p] 1 stacks[line.strip()[:120]] 1 return { error_codes: codes.most_common(10), top_stacks: stacks.most_common(5), } if __name__ __main__: result parse(sys.argv[1]) print(json.dumps(result, ensure_asciiFalse, indent2))这个脚本无论多复杂进入上下文的只有最后那段 JSON通常不到 100 token。这就是 Skills 相比“让模型现场生成代码”的最大优势确定性加零上下文占用。4. 验证请求一次技能加载与触发的完整演示配置写好后必须验证 Skill 是否真的被触发、加载层级是否符合预期。我用一段会命中日志排障场景的请求来演示import os from anthropic import Anthropic client Anthropic( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], ) resp client.messages.create( modelclaude-3-5-sonnet-20241022, max_tokens1024, tools[{type: code_execution, container_id: log-triage-expert}], messages[{ role: user, content: app.log 里出现大量 E5003 报错帮我定位一下根因 }], ) print(resp.content[0].text)预期行为分三步。第一启动时 Level 1 元数据已加载Claude 知道存在 log-triage-expert 这个技能。第二用户请求命中 description 中的“报错”“日志”Claude 读取 SKILL.md学到标准流程是先跑 parse_log.py。第三Claude 执行脚本只有脚本输出的错误码分布进入上下文然后基于摘要给出根因初筛。验证成功的标志有三个响应里出现了对错误码分布的引用执行过程调用了 parse_log.py 而不是现场生成解析代码整体 token 消耗明显低于把全部日志塞进 prompt 的方式。你可以对比一下传统方式把 2MB 日志直接贴进对话轻松上万 tokenSkills 方式只有脚本输出的几百 token 摘要。如果想让验证更直观可以在脚本里加一行 stderr 日志观察它是否被执行python scripts/parse_log.py app.log --output parsed.json 2debug.log cat debug.log看到 debug.log 有内容说明脚本确实被调用了而不是模型在“假装”分析。5. 本篇常见错排查第一个高频错误是 Skill 不触发。九成情况出在 description 写得太泛比如只写“日志处理工具”。Claude 判断是否加载靠的是语义匹配description 里必须包含用户可能说的触发词。改成“当用户提到日志、报错、异常、stack trace 时使用”之后命中率会明显上升。第二个错误是 SKILL.md 写成了百科全书。有人把几千行文档全塞进正文结果 Level 2 一加载就爆上下文渐进式加载的优势荡然无存。正确做法是正文只留流程和索引细节拆到 ADVANCED.md、REFERENCE.md让它们留在 Level 3。第三个错误是脚本路径写相对路径。Claude 执行 bash 时的工作目录不一定是你以为的那个建议在 SKILL.md 里写清完整调用方式或者用$(dirname $0)这类方式定位。实测下来路径问题导致的“脚本找不到”占了排障时间的一大半。第四个错误是 API 通道配置混淆。官网地址带 UTM 参数API 端点不带两者不能混用。如果你在代码里把 base_url 写成了官网链接会直接连接失败。正确端点是 https://taotoken.net/api。Key 相关操作在 API Keys 页面完成接入细节可对照接入文档。第五个错误是忽略脚本输出的体积。脚本虽然不占上下文但如果它 print 了一万行日志输出照样会撑爆窗口。养成习惯脚本只输出结构化摘要原始数据写文件需要时再按需读取。6. 把 Skill 用起来从验证到长期编码跑通一次验证只是开始。如果你打算把 Skills 用在长期编码或 Agent 工作流里建议把常用能力拆成独立 Skill 目录每个目录单一职责团队按目录分工开发。这样新增能力时只需加一个 Skill不用动主 prompt。对于需要持续调用模型、跑长任务的场景可以了解 Coding Plan它更适合长期编码和 Agent 类负载。日常调试模型行为、快速验证 Skill 触发是否符合预期用模型对话就够了。Key 的创建和管理统一在 API Keys 页面接入参数和示例参考接入文档。最后留一个实用习惯每次改完 SKILL.md先跑一遍触发验证确认 description 命中、Level 2 加载、Level 3 按需调用这三步都正常再提交到团队仓库。Skill 的渐进式加载不是玄学它就是把“人类查手册”的机制搬进了 Agent你只要把手册的目录写清楚Agent 自然知道什么时候翻哪一页。
