1. 从一次“重复解释代码”说起Agent Skills 到底解决什么问题如果你最近在 Claude Code 里反复粘贴同一段提示词比如“帮我解释这段代码先打比方再画流程图”那你已经踩到了 Agent Skills 想解决的核心痛点。Claude Code 是 Anthropic 推出的命令行编程助手而 Agent Skills 是它的一套“能力插件标准”把一段 Prompt 封装成 Markdown 文件让 Claude 在合适场景自动识别并调用。适合谁适合刚接触 Claude Code、想让 AI 记住自己编码规范、又不想每次都手打长提示词的开发者。传统做法是把提示词存在笔记里用的时候复制粘贴。问题是提示词越写越长上下文越占越多团队里每个人写法还不一样。Agent Skills 的思路很像把 Prompt 变成函数——SKILL.md是函数体description字段是函数名加文档注释Claude 通过语义匹配决定“什么时候调这个函数”。你写一次之后只要用户输入命中描述Claude 就会弹出确认并加载整份指令。这篇文章会带你走完一条完整链路先理解 Skill 的目录结构和生命周期再手写一个可用的SKILL.md接着配置settings.json最后在 Claude Code 里加载并验证它真的生效。全程命令可复制遇到不触发的情况也有排查表。如果你还没拿到可用的 API Key可以先去 TaoToken 的 API Keys 页面创建一个后面验证模型和接入都会用到。2. 前置准备TaoToken 接入与 Claude Code 环境确认在写 Skill 之前先把“Claude Code 能正常跑起来”这件事确认掉。Claude Code 需要模型服务支撑TaoToken 提供兼容的 API 接入方式你可以在控制台创建 Key再把它配置到环境变量里。这一步不是注册教程而是确保后面验证 Skill 时不会因为鉴权失败误判成 Skill 没生效。先确认本机 Claude Code 版本终端执行claude --version如果提示命令不存在说明还没安装或 PATH 没配好。安装完成后配置 API 地址与 Key。TaoToken 的 API 端点是https://taotoken.net/api注意这里不加任何查询参数。写入环境变量export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY你的_TaoToken_Key把这两行放进~/.zshrc或~/.bashrc可以持久化。Key 的创建入口在 TaoToken 控制台的 API Keys 页面建议给不同项目建不同 Key方便后面按项目排查调用量。配置完成后跑一次最小请求确认链路通claude -p 用一句话说明什么是 Markdown frontmatter能正常返回内容说明模型服务已通。此时再进入 Skill 环节任何“Skill 不触发”的问题都能排除掉鉴权因素。这里有个容易忽略的点ANTHROPIC_BASE_URL末尾不要带斜杠也不要手动拼/v1Claude Code 会自己处理路径拼接多写反而会 404。3. 可复制配置SKILL.md 骨架与 settings.json 片段Agent Skills 的载体是目录加 Markdown 文件。作用域分两层项目级放在仓库的.claude/skills/下团队共享个人级放在~/.claude/skills/下跨项目生效。先建一个个人级 Skill用来解释代码mkdir -p ~/.claude/skills/explain-with-diagram cd ~/.claude/skills/explain-with-diagram新建SKILL.md骨架如下。注意 frontmatter 必须是文件最开头---不能有前导空格--- name: explain-with-diagram description: 用 ASCII 图和类比解释代码。当用户问“这段代码怎么工作”“解释一下这个函数”时自动触发。 allowed-tools: [Read, Grep] --- ## 指令 1. 先用一个生活化类比说明这段代码在做什么 2. 画一张 ASCII 流程图标出数据流向 3. 逐行讲解关键语句跳过样板代码 4. 指出一个最容易踩的坑 5. 全程口语化不要用“综上所述”这类词description是触发开关写得越具体语义匹配越准。allowed-tools是白名单这里只给Read和Grep意味着这个 Skill 只能读文件、搜内容不能写文件避免误操作。如果你希望 Skill 能执行脚本可以在同目录放scripts/文件夹并在指令里写明调用方式Claude 只在需要时才读取这些资源这就是所谓的渐进披露能省 token。接着配置settings.json。项目级配置放在仓库根目录的.claude/settings.json个人级放在~/.claude/settings.json。一个最小片段{ skills: { enabled: true, directories: [ ~/.claude/skills, .claude/skills ] } }directories数组的顺序决定优先级越靠前越优先。团队协作时把.claude/skills/提交进仓库新同学拉下来就能用同一套规范。个人实验性的 Skill 放家目录不污染项目。改完配置后需要重启 Claude Code 会话配置才会重新加载。4. 验证请求加载 Skill 并确认它真的生效配置写完不代表生效必须验证。退出当前 Claude Code 会话再重新进入claude进入交互界面后输入查询指令What Skills are available?如果返回列表里出现explain-with-diagram说明 Skill 已被发现。这一步对应生命周期里的 Discovery 阶段启动时 Claude 只加载所有 Skill 的name和description不读正文所以速度很快。接下来做 Activation 验证。打开任意一个源文件比如claude 打开 src/utils/parse.js然后问这段代码怎么工作当你的提问和description语义相似度超过阈值时Claude 会弹出确认框询问是否使用explain-with-diagramSkill。确认后进入 Execution 阶段整份SKILL.md被塞进上下文Claude 按里面的五条指令输出——先类比、再 ASCII 图、逐行讲解、点出坑、口语化。你能明显看到输出结构和默认回答不同这就是 Skill 生效的直接证据。如果想让验证更可控可以临时把description改成一个独特短语比如“当用户输入‘图解一下’时触发”然后在会话里输入“图解一下这段代码”观察确认框是否出现。验证通过后再改回自然描述。实测下来description里同时包含触发场景和具体动词命中率最高。5. 本篇常见错排查Skill 不触发、加载失败、权限被拒即使步骤都对也可能遇到问题。下面这张表覆盖了最常见的几类症状按顺序排查基本能定位。症状大概率原因处理方式Skill 完全不触发description太泛缺少具体动词和关键词改成“当用户问 XX 时触发”加入场景词加载失败、列表里没有YAML frontmatter 语法错误比如冒号后没空格用在线 YAML linter 校验确认---成对脚本权限被拒同目录脚本没有执行权限chmod x scripts/*.py插件 Skill 突然消失缓存未刷新rm -rf ~/.claude/plugins/cache后重启改了配置没反应会话没重启配置未重载退出claude再进项目级 Skill 不生效目录层级放错不在.claude/skills/下确认路径为repo/.claude/skills/name/SKILL.md还有一个隐蔽的坑SKILL.md文件名必须全大写写成skill.md在部分系统上不会被识别。另外name字段建议用短横线连接的小写英文和目录名保持一致避免中文或空格导致解析异常。如果你在settings.json里同时配了项目级和个人级目录注意优先级顺序同名 Skill 会以靠前目录的为准。排查时建议开一个干净会话只保留一个 Skill 做最小验证排除多个 Skill 之间description语义重叠导致的互相干扰。确认单个能触发后再逐步加回其他 Skill。6. 把 Skill 用起来从个人实验到团队共享单个 Skill 跑通后你可以按同样的结构扩展。比如写一个“提交信息规范”Skilldescription写成“当用户要求生成 git commit message 时触发”指令里规定格式和字数再写一个“接口文档生成”Skill把模板放在同目录的template.md里主文件保持精简用时再读模板。这种主文件加附属资源的组织方式就是渐进披露的落地。团队共享时把.claude/skills/提交进仓库并在 CI 里加一步校验确保每个SKILL.md的 frontmatter 合法。个人跨项目复用的 Skill 继续放~/.claude/skills/两边通过settings.json的directories合并加载。需要长期跑编码任务或 Agent 流程的话可以了解 TaoToken 的 Coding Plan配合 Skill 把规范固化下来减少每次对话的重复描述。验证模型输出是否符合预期时除了在 Claude Code 里直接问也可以到 TaoToken 的模型对话页面做对照测试确认是 Skill 指令在起作用而不是模型本身的默认行为。接入细节和参数说明可以查接入文档遇到鉴权或路径问题优先核对 API 端点是否写成https://taotoken.net/api。把 Skill 当成可版本回滚的“能力模块”来管理你的 Claude Code 才会越用越顺手。