1. 为什么你的 Claude Code 里 SKILL 技能总是不触发很多人第一次接触 Claude Code 的 SKILL 技能都会经历同一个困惑明明把 SKILL.md 放进了目录对话里也提了需求Claude 却像没看见一样该干嘛干嘛。我试过把一份写好的技能文档丢进~/.claude/skills/然后问它帮我按规范生成提交信息结果它直接手写了一段完全没走我的技能。问题几乎都不在模型而在 SKILL.md 本身。SKILL 技能是一套按需加载的能力封装机制Claude 平时并不会把所有技能的正文都读进上下文它只先看每个技能的 name 和 description判断当前请求要不要命中命中之后才把 SKILL.md 的正文加载进来按里面的步骤执行。所以决定触不触发的是 frontmatter决定执行对不对的才是正文。绝大多数不触发都是 description 写得太虚或者干脆漏了 frontmatter。SKILL 技能能做什么把一类有固定套路的重复工作沉淀成可复用单元比如统一 commit 规范、固定代码审查清单、按模板生成接口文档、按项目约定做目录初始化。适合谁适合每天都在 Claude Code 里重复交代同一套要求的人——你交代三遍的东西就该封装成一个 SKILL。这篇会从 SKILL.md 的写法讲到目录结构再讲到 Plugin 挂载最后给你一套可复制的模板和验证动作。全程围绕 Claude Code、SKILL、Skill、Plugin、SKILL.md 这几个关键词展开跟着做就能把技能从文档变成真正会被调用的能力。2. TaoToken 前置准备给 Claude Code 配好可用的模型入口在折腾 SKILL 之前得先保证 Claude Code 本身能稳定跑起来。SKILL 是能力层模型入口是底座底座不通技能写得再好也验证不了。这里用 TaoToken 作为模型接入入口它提供兼容 Anthropic 的 API 形式Claude Code 可以直接对接。先拿 Key。打开 https://taotoken.net/api-keys 登录后创建一个 API Key复制保存好。这个 Key 就是后面配置里的ANTHROPIC_AUTH_TOKEN只显示一次丢了只能重建。然后确认你要用的模型 ID。在 https://taotoken.net/models 可以看到当前可用的模型列表把你要接的模型 ID 记下来比如某个 Claude 系列模型 ID。SKILL 技能对模型的指令遵循能力有要求建议选指令遵循较强的模型否则正文里的步骤它可能执行得七零八落。如果你更想先感受一下模型对话效果可以打开 https://taotoken.net/chat 直接试几句确认 Key 和模型都正常再进 Claude Code 配置。这一步能帮你排除到底是 Key 问题还是 SKILL 问题。配置的核心是三件套Base URL、Key、Model ID。Claude Code 通过环境变量读取Base URL 指向https://taotoken.net/apiKey 用刚创建的Model ID 用你选定的。三者缺一Claude Code 要么连不上要么连上了但模型不对。需要提醒的是SKILL 技能的调试会反复触发模型请求建议在正式项目之外先建一个测试目录专门用来验证技能避免误操作污染真实仓库。等技能稳定了再放进正式项目或全局目录。如果你打算长期用 Claude Code 做编码和 Agent 类任务可以了解一下 Coding Plan https://taotoken.net/coding-plan 它更适合高频、长时间的编码场景比零散调用更省心。SKILL 技能本身就是为长期重复任务设计的和这类计划搭配起来比较顺。3. 可复制配置SKILL.md 模板与 Plugin 挂载方式这一节是全文的核心给你能直接抄的配置。先讲目录结构再给 SKILL.md 完整模板最后讲 Plugin 怎么挂载。3.1 Skill 目录结构与两种存放位置一个自建 Skill 的典型结构是这样my-skill/ ├── SKILL.md # 必需技能说明文档 ├── scripts/ # 可选辅助脚本 ├── references/ # 可选参考文档、模板 └── assets/ # 可选示例、素材最小可用的 Skill 只要一个 SKILL.md 就够了其余目录按需扩展别为了凑结构建空目录。存放位置决定作用范围这是最容易搞错的地方位置类型典型路径作用范围适用场景个人级全局~/.claude/skills/skill-name/当前用户所有项目通用技能如 commit 规范项目级本地项目根/.claude/skills/skill-name/仅当前项目项目特有约定、模板记忆口诀全局放家目录项目放项目里。想让团队每个人都用到就放项目级并提交到仓库只想自己用放个人级。3.2 SKILL.md 完整模板可直接复制下面这份模板以生成符合 Conventional Commits 规范的提交信息为例你可以整体替换成自己的场景。注意 frontmatter 必须用---包裹这是触发匹配的门牌号。--- name: git-commit-helper description: 根据 git diff 自动生成符合 Conventional Commits 规范的提交信息。当用户要求写 commit message / 提交信息 / commit 信息 / 生成提交说明时使用。 allowed-tools: - Bash - Read --- # Git Commit Helper ## 用途 读取当前仓库的改动git diff / git status按 Conventional Commits 规范生成一条清晰的提交信息。 ## 适用场景 - 用户完成一个功能或修复需要写提交信息 - 用户明确说帮我写 commit / 写个提交信息 / 生成 commit message ## 不适用场景 - 用户只是想看 diff不需要提交信息 - 用户已有现成 commit 文案只需帮忙执行 git commit ## 执行步骤 1. 运行 git status 和 git diff --staged无暂存时退回 git diff。 2. 归类本次改动类型feat / fix / docs / refactor / test / chore / perf。 3. 用一句话总结改动核心控制在 50 字以内。 4. 如有必要补充正文说明为什么改 / 影响范围。 5. 输出标准格式后停止等待用户确认是否提交。 ## 输出规范 格式必须为 type(scope): subject body 示例feat(login): 新增手机号验证码登录 ## 注意事项 - type 必须取自约定集合禁止自创 - subject 使用祈使句、现在时末尾不加句号 - 中文项目用中文 subject英文项目用英文 ## 示例 输入git diff 显示新增了 src/login/sms.js注册了发送短信验证码的逻辑 输出feat(login): 新增手机号验证码登录frontmatter 里三个字段的分工要清楚name是小写连字符、全局唯一的技能名description是触发匹配的核心依据必须写准allowed-tools可选用来限制这个技能能调用哪些工具比如只允许 Read 和 Bash防止它乱写文件。3.3 Plugin 挂载方式Skill 和 Plugin 是两个层级Skill 是最小能力单元Plugin 是承载和分发 Skill 的容器。一个 Plugin 可以包含多个 Skill。安装一个 Plugin往往就获得一整套配合的能力。如果 Skill 是随 Plugin 分发的按 Plugin 的安装方式整体安装即可不用手动往 skills 目录里塞。如果是单独分发的就放进上面说的个人级或项目级目录。判断标准很简单拿到的是单个 SKILL.md 文件夹就手动放拿到的是一个带配置的 Plugin 包就整体装。3.4 Claude Code 环境变量配置Claude Code 通过环境变量读取模型入口三件套对应关系如下export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKEN你的_API_Key export ANTHROPIC_MODEL你的_Model_ID把这三行写进你的 shell 配置文件如~/.zshrc或~/.bashrc然后source一下或者新开终端。Base URL 指向https://taotoken.net/apiKey 用第 2 节创建的Model ID 用你选定的。三件套齐全Claude Code 才能正常发起请求SKILL 技能才有验证的基础。4. 验证请求确认 SKILL 真的被触发并执行配置写完不算完得验证。验证分两层先确认模型入口通再确认 SKILL 被命中。4.1 先验证模型入口在终端里跑一句最简单的请求确认 Base URL、Key、Model ID 三件套生效。如果 Claude Code 有内置的连通性检查命令用它没有的话直接在项目里发起一次普通对话看是否正常返回。返回正常说明底座通了可以进 SKILL 验证。4.2 验证 SKILL 是否被识别把第 3 节的git-commit-helper放进~/.claude/skills/git-commit-helper/SKILL.md然后查看技能列表确认git-commit-helper已经出现在可用技能里。列表里没有说明路径错了或 frontmatter 格式有问题先解决这个再往下。4.3 正例测试应该触发在一个有改动的 git 仓库里对 Claude Code 说帮我写个 commit 信息预期结果它自动命中git-commit-helper先跑git status和git diff然后按type(scope): subject格式输出一条提交信息比如feat(login): 新增手机号验证码登录输出后停下等你确认。4.4 反例测试不应该触发同一个仓库里对 Claude Code 说看一下我改了哪些文件预期结果它只总结改动不生成 commit 信息也就是不触发这个 Skill。如果反例也触发了说明 description 太宽或者正文里不适用场景没写清楚回到 SKILL.md 补边界。4.5 稳定性测试用同一段测试 prompt 连续跑 3 到 5 次看输出是否稳定。稳定就说明技能成型了不稳定比如有时触发有时不触发、有时格式对有时格式乱就按第 5 节的排查表定位。验证通过后这个技能就从文档变成了可复用能力。核心闭环是建目录 → 写 frontmatter 正文 → 测正例反例 → 按症状迭代。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth调试 SKILL 时遇到的报错一半是模型入口问题一半是技能本身问题。分开看。5.1 401 报错现象Claude Code 发起请求直接返回 401或提示认证失败。原因基本是 Key 不对或没生效。检查ANTHROPIC_AUTH_TOKEN是否和 https://taotoken.net/api-keys 里创建的一致有没有多余空格有没有把 Key 写进了错误的变量名。改完记得重新source配置文件或新开终端环境变量不会自动刷新。5.2 local proxy failed现象提示本地代理失败或连接被拒。这类报错通常指向 Base URL 配置问题。确认ANTHROPIC_BASE_URL写的是https://taotoken.net/api没有多余路径、没有拼写错误、没有混入其他地址。如果你本地有其他网络层配置先排除它们对请求的干扰保证请求直达配置的入口。5.3 reading choices 相关报错现象返回结构解析失败提示读取 choices 出错之类。这通常是模型 ID 不对或者返回格式和客户端预期不匹配。回到 https://taotoken.net/models 核对ANTHROPIC_MODEL是否是你实际可用的模型 ID别用猜测的字符串。模型 ID 错请求可能返回非预期结构客户端解析就报错。5.4 OAuth 相关报错现象提示 OAuth 认证流程失败或 token 过期。如果你用的是基于 token 的接入方式确认没有混用两套认证逻辑。用ANTHROPIC_AUTH_TOKEN这套就不要再触发 OAuth 流程两者混用容易互相覆盖。清掉冲突的认证配置只保留一套。5.5 SKILL 不触发 / 乱触发 / 执行错模型入口没问题后剩下的就是技能本身。对照下表定位症状可能原因处理方法根本不触发description 太模糊没覆盖用户真实问法用用户真实会问的话术重写 description加入关键词乱触发缺少不适用场景边界不清在正文明确列出不适用场景触发但执行错步骤太抽象缺示例补输入 → 输出具体示例强化步骤输出格式不稳输出规范太宽松用固定标题、固定字段钉死输出形式执行到一半跑偏步骤间缺中间校验在关键步骤后加自检环节排查顺序建议先确认三件套Base URL Key Model ID都对再看技能列表里有没有这个 Skill最后才调 description 和正文。顺序反了会在错误的地方浪费时间。6. 把 SKILL 用起来从单个技能到 Plugin 化复用技能跑通之后下一步是让它真正融入日常。单个 SKILL 解决一类任务多个 SKILL 组合起来就可以考虑用 Plugin 打包分发。6.1 触发行为的控制Skill 不是装上就全开。自动触发是默认行为Claude 根据请求语义自行判断手动触发则是你在对话里显式点名某个技能。对那些重要但容易漏触发的技能可以养成手动点名的习惯别完全依赖自动匹配的命中率。影响触发的关键因素有三个description 质量、是否显式启用或禁用、作用范围。description 越贴合用户真实问法自动触发越准作用范围设得越合理越不会在无关项目里误触发。6.2 技能的查看、停用与删除技能多了要管理。定期查看技能列表确认哪些还在用对来源不明的第三方 Skill 保持审慎安装前读一遍它的 SKILL.md尤其是带脚本的技能别直接运行来历不明的逻辑。停用是让某个 Skill 暂时不参与自动触发文件还在删除是彻底移除。删除前确认没有团队其他成员依赖它尤其是放在项目级目录、已经提交到仓库的技能。6.3 从 Skill 到 Plugin当你攒了一组相互配合的技能比如 commit 规范、代码审查清单、接口文档模板就可以把它们打包成一个 Plugin。Plugin 是筐Skill 是筐里的工具。打包后团队里其他人装一个 Plugin 就能拿到整套能力不用一个个手动放 SKILL.md。这也是 SKILL 技能设计的初衷把重复且有套路的工作从对话里沉淀下来变成随取随用的能力模块。精准的描述、清晰的步骤、典型的示例三者缺一不可再加上不断迭代你就能让 Claude Code 在你最常见的那几类任务上稳定输出。如果你还在选模型入口阶段可以先去 https://taotoken.net/chat 试几句感受效果准备长期在 Claude Code 里跑编码和 Agent 任务可以看 https://taotoken.net/coding-plan 接入细节和参数说明在 https://taotoken.net/doc 有完整文档。把底座配好再把 SKILL 一个个沉淀下来这套组合会越用越顺。