1. 从通用助手到专业助手Agent Skills 到底解决了什么问题如果你最近在折腾 Claude、Claude Code 或者基于大模型搭自己的 AI 助手大概率会遇到一个很尴尬的场景模型本身很聪明但一到具体业务就“不专业”。比如你让它按公司规范生成一份周报它写得头头是道格式却完全不对你让它处理一批 PDF 表单它能读懂内容却没法稳定地把字段填进去。问题不在于模型能力不够而在于它缺少程序性知识——也就是“这件事在我们这里具体该怎么做”的那套流程。Agent Skills 就是冲着这个痛点来的。简单说一个 Skill 就是一个包含SKILL.md文件的目录里面可以放指令、脚本和资源。Agent 在启动时只会把每个 Skill 的name和description预加载进系统提示词只有当它判断当前任务和某个 Skill 相关时才会去读取完整的SKILL.md甚至进一步读取目录里捆绑的其他文件。这套机制叫渐进式披露progressive disclosure是 Agent Skills 最核心的设计。它适合谁我梳理了三类人第一类是想把重复性事务日报、周报、数据清洗、格式转换交给 AI 自动跑的开发者第二类是在做垂直领域 AI 助手、需要把行业知识“喂”给模型的团队第三类是想减少 token 消耗、又不想牺牲专业度的个人开发者。我试过把一套固定的文档处理流程封装成 Skill实测下来上下文占用比每次手动贴一大段提示词低了不少而且行为更稳定。这篇文章不会停留在概念层面。我会带你从零写出一个可用的SKILL.md给出完整的目录结构和配置片段然后一步步在 Claude 环境里加载它并验证渐进式披露是否真的生效。中间会穿插我踩过的坑和常见报错排查尽量让你照着做就能跑通。2. 前置准备TaoToken 接入与 SKILL.md 规范速览在动手写 Skill 之前得先把模型调用这条链路打通。因为 Skill 本身只是“知识包”真正执行任务、读取文件、运行脚本的还是背后的 Agent 和模型。我这边用的是 TaoToken 提供的接入方式它兼容 Anthropic 的接口协议配置起来比较直接适合拿来跑 Claude Code 这类支持 Agent Skills 的环境。先说清楚 TaoToken 在这里的角色它是一个模型接入服务你通过它拿到 API Key 和 Base URL就能在本地工具里调用 Claude 系列模型。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。注意 API 地址后面不加 UTM 参数直接用它就行。拿到 Key 之后你需要准备三样东西我把它叫做“三件套”Base URL、API Key、Model ID。这三者在后面配置 Claude Code 或者 Cline 之类的工具时都会用到。Model ID 要填你实际调用的模型名称比如claude-sonnet-4-5这类具体以你账号里可用的为准。接下来是SKILL.md的规范。一个合法的 Skill 目录最小结构长这样my-skill/ ├── SKILL.md ├── reference.md # 可选第三层细节 ├── forms.md # 可选按场景拆分 └── scripts/ └── extract.py # 可选可执行代码SKILL.md必须以 YAML Frontmatter 开头里面至少包含两个字段--- name: pdf-form-filler description: 当用户需要读取 PDF 表单字段并填写内容时使用。适用于合同、申请表等结构化 PDF 的自动化处理。 ---这里有个关键点name和description是第一层渐进式披露的内容它们会在 Agent 启动时被预加载到系统提示词里。也就是说模型在还没读你 Skill 正文之前就靠这两行判断“这个任务要不要触发这个 Skill”。所以description写得越具体、越贴近真实触发场景命中率越高。我见过不少人把 description 写成“一个处理 PDF 的工具”结果模型根本不知道什么时候该用它。正文部分就是第二层写具体的操作指令、步骤、注意事项。如果内容太长可以拆到reference.md、forms.md这些额外文件里在正文中用文件名引用它们这就是第三层及更深层。模型只有在需要时才会去读这些文件从而控制上下文占用。注意Skill 目录名和name字段建议保持一致方便管理和排查。description里不要堆砌关键词写清楚“什么场景下用”比写“功能列表”更有效。3. 可复制配置SKILL.md 目录结构与 Claude Code 接入片段这一节直接给可复制的内容。先看一个完整的 Skill 目录示例我以“周报生成器”为例这个场景足够日常也方便你验证渐进式披露。目录结构weekly-report-skill/ ├── SKILL.md ├── templates.md └── scripts/ └── collect_git_log.shSKILL.md内容--- name: weekly-report-generator description: 当用户需要根据本周的代码提交记录、任务清单生成结构化周报时使用。适用于研发团队的周报自动化场景。 --- # 周报生成器 ## 使用步骤 1. 先运行 scripts/collect_git_log.sh 收集本周的 git 提交记录。 2. 读取 templates.md 中的周报模板。 3. 按照模板结构把提交记录归类到「本周完成」「进行中」「风险与阻塞」三个板块。 4. 输出 Markdown 格式的周报不要添加额外解释。 ## 注意事项 - 提交记录里如果出现 fix、hotfix 字样归入「本周完成」并标注修复类型。 - 如果某个任务没有对应提交但用户口头提到也要纳入「进行中」。 - 模板中的占位符必须全部替换不允许保留 {{}}。templates.md内容# 周报模板 ## 本周完成 - {{item}} ## 进行中 - {{item}} ## 风险与阻塞 - {{item}}scripts/collect_git_log.sh内容#!/bin/bash # 收集最近7天的 git 提交记录 git log --since7 days ago --prettyformat:%h %s --no-merges注意脚本要给执行权限chmod x scripts/collect_git_log.sh。接下来是 Claude Code 的接入配置。Claude Code 支持通过环境变量或者配置文件指定 Base URL 和 API Key。我推荐用配置文件的方式路径是~/.claude/settings.json不同版本可能略有差异以你本地实际为准。配置片段如下{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的_API_Key, ANTHROPIC_MODEL: claude-sonnet-4-5 } }如果你用的是 Cline 或者支持 MCP 的工具配置逻辑类似核心还是那三件套Base URL 填https://taotoken.net/apiAPI Key 填你申请到的Model ID 填可用模型名。有些工具会要求你单独填ANTHROPIC_AUTH_TOKEN那就把 Key 填进去效果一样。Skill 的安装位置Claude Code 一般会从项目根目录的.claude/skills/或者用户目录的~/.claude/skills/读取。你把weekly-report-skill整个目录放进去就行mkdir -p ~/.claude/skills cp -r weekly-report-skill ~/.claude/skills/放好之后重启 Claude Code让它在启动时重新加载 Skill 元数据。这一步很关键因为name和description是在启动阶段注入系统提示词的不重启不会生效。提示如果你在团队里共享 Skill建议把 Skill 目录纳入 git 管理但不要把 API Key 写进任何 Skill 文件里。Key 只放在本地环境变量或 settings.json 中。4. 验证请求确认渐进式披露真的生效配置写完怎么确认 Skill 被正确加载、渐进式披露真的在工作我分三步来验证。第一步检查元数据是否注入。启动 Claude Code 后随便问一个和 Skill 无关的问题比如“今天天气怎么样”。然后在对话里输入/context或者查看系统提示词相关的调试信息不同版本命令可能不同有的用/debug。你应该能在系统提示词里看到类似这样的片段Available skills: - weekly-report-generator: 当用户需要根据本周的代码提交记录、任务清单生成结构化周报时使用...如果看不到说明 Skill 没被加载。先检查目录位置对不对再检查SKILL.md的 Frontmatter 格式有没有写错比如---是不是成对出现、缩进有没有问题。第二步触发 Skill 并观察读取行为。输入一句会命中 description 的话比如“帮我根据这周的 git 提交生成一份周报”。这时候模型应该会调用 Bash 工具去读取SKILL.md。你可以在工具调用记录里看到类似Reading file: ~/.claude/skills/weekly-report-skill/SKILL.md这就是第二层披露被触发的证据。如果模型直接开始瞎编周报没有去读文件说明 description 的触发词不够准或者模型没把这句话和 Skill 关联起来。可以试着把 description 改得更贴近你的实际说法。第三步验证第三层按需加载。继续观察模型读完SKILL.md后应该会去读templates.md因为正文里明确引用了它。工具调用记录里会出现Reading file: ~/.claude/skills/weekly-report-skill/templates.md同时它可能会运行collect_git_log.sh。如果这些文件没有被读取模型就自己编了一个模板那说明正文里的引用不够明确或者模型判断不需要。你可以在正文里把引用写得更强制比如“必须读取 templates.md 后再生成”。一个成功的验证结果应该长这样模型先读SKILL.md再读templates.md运行脚本拿到提交记录最后输出一份结构完整的周报三个板块齐全没有残留占位符。整个过程里reference.md这类没被引用的文件不会被读取这就是渐进式披露在控制上下文。我实测下来最容易出问题的环节是 description 的写法。很多人把它当成功能说明书写“支持 PDF 处理、表单填写、数据提取”但模型需要的是“什么时候用”。改成“当用户需要填写 PDF 表单字段时使用”之后触发率明显提升。5. 常见报错排查401、local proxy failed、reading choices 与 OAuth这一节对照真实报错来排查。我把踩过的坑按现象分类你可以直接对号入座。401 Unauthorized。这是最常见的接入错误基本是 Key 或 Base URL 的问题。先确认ANTHROPIC_API_KEY填的是 TaoToken 给你的 Key没有多余空格再确认ANTHROPIC_BASE_URL是https://taotoken.net/api注意结尾不要多加/v1或者斜杠有些工具会自动拼接路径多写反而 404 或 401。如果用的是 settings.json检查 JSON 格式有没有语法错误比如少了个逗号工具会静默忽略整个配置。local proxy failed / connection refused。这个报错通常出现在你本地开了某个转发工具但端口没对上。Claude Code 默认直连 Base URL如果你在中间加了本地代理要确保代理进程在跑、端口一致。排查方法是先用 curl 直接测接口curl -X POST 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-5,max_tokens:64,messages:[{role:user,content:hi}]}如果 curl 能通说明链路没问题问题在工具配置如果 curl 也不通那就是 Key 或网络本身的问题。reading choices / unexpected token in JSON。这类报错一般出现在模型返回内容被截断或者格式不对时。常见原因是max_tokens设得太小模型还没输出完就被切断解析 JSON 时自然失败。把max_tokens调大比如 4096 或 8192。另一个原因是 Skill 里的脚本输出了非 JSON 内容模型却按 JSON 解析。检查你的脚本输出确保格式和 Skill 正文里声明的一致。OAuth / authentication failed。有些工具默认走 OAuth 登录流程而不是 API Key。如果你用的是 API Key 接入需要在工具设置里明确选择“API Key”模式关掉 OAuth。Claude Code 里可以通过claude config或者直接改 settings.json 来指定认证方式。如果工具同时支持两种优先用 API Key配置更可控。Skill 不触发。这个不算报错但很常见。排查顺序先确认 Skill 目录在正确位置再确认SKILL.mdFrontmatter 格式正确然后确认 description 写的是触发场景而不是功能列表。最后重启工具让元数据重新加载。如果还是不触发可以在对话里直接说“使用 weekly-report-generator 这个 Skill”强制模型去读看看是不是 Skill 本身有问题。注意排查时优先用 curl 验证接口连通性这一步能排除掉大部分“到底是网络问题还是配置问题”的纠结。接口通了再回头查工具配置和 Skill 文件。6. 继续深入把 Skill 用起来并持续迭代写到这里一个最小可用的 Agent Skill 已经跑通了。但真正让 Skill 产生价值的是持续迭代。我自己的做法是每次用 Skill 完成任务后如果发现模型走了弯路就把那个弯路记下来补进SKILL.md的注意事项里如果某个步骤反复用到就把它抽成脚本放进scripts/。这样 Skill 会越来越贴合你的实际工作流。关于渐进式披露还有一个实践技巧把互斥的上下文拆到不同文件里。比如“填写表单”和“提取文本”是两种不同场景就分别放到forms.md和extract.md在正文里按条件引用。这样模型在只做提取任务时不会把表单填写的指令也读进上下文token 消耗更省。如果你想把 Skill 分享给团队建议在目录里加一个README.md说明用途和依赖但注意README.md不会被自动加载它只是给人看的。真正的加载入口始终是SKILL.md。后续如果要做更复杂的 Agent比如让模型自己创建和评估 Skill可以关注 Claude Agent SDK 和相关的开发者文档。TaoToken 这边也提供了模型对话、Coding Plan、API Keys 管理等入口需要验证模型效果或者长期跑编码任务时可以用上模型对话验证https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite长期编码与 Agent 场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite控制台与 API Keyshttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite最后留一个我常用的检查清单每次新建 Skill 后过一遍Frontmatter 的 name 和 description 是否写清楚触发场景正文步骤是否可执行、无歧义引用的额外文件是否真实存在脚本是否有执行权限安装后是否重启工具。这五步走完基本不会出大问题。