1. 为什么你的 SKILL.md 写了却从不自动触发很多人第一次接触 Claude Code 的 Skills 机制都会经历同一个困惑我明明按文档写了.claude/skills/xxx/SKILL.mdfrontmatter 也填了为什么 Claude 就是不自动加载每次还得我手动说用一下那个 skill。问题几乎都出在description字段上。Claude Code 的 Skills 是 LLM 推理触发的——它不会扫描你的文件目录去找技能而是在每次推理时读取所有 Skill 的 frontmatter拿description和当前对话做语义匹配。匹配上了才加载正文。所以description不是给人看的说明是给模型看的触发条件声明。我见过最典型的错误写法是description: A changelog generator。这句话描述的是这个技能做什么但模型需要知道的是用户说什么话的时候我该用它。前者让模型无从判断时机触发率基本为零后者才能让模型在用户提到更新 changelogrelease notes时自动命中。这篇聚焦三件事SKILL.md 的 frontmatter 四个字段怎么设计、Skills 的触发链路到底怎么走、以及怎么和 SubAgent 协同。面向的是需要把重复工作流沉淀成可复用技能包的工程团队——不是写一个玩玩的 demo而是要建一套能长期维护的技能目录。先明确一个边界Skills 和 SubAgent 是 Claude Code 两种不同的能力扩展机制触发方式完全不同。SubAgent 由主对话显式调起code-reviewer有独立上下文和固定启动成本Skills 由 LLM 自动发现、渐进式加载零调用成本。两者互补不冲突。搞混这两者是第二个高频踩坑点。下面从 frontmatter 字段设计讲起给出可直接复制的模板再演示一次从手动触发到自动命中的完整验证动作。2. TaoToken 前置准备让 Claude Code 稳定跑起来在写 SKILL.md 之前得先保证 Claude Code 本身能正常调用模型。Skills 的触发依赖模型推理如果底层请求不稳定你会分不清是 description 写错了还是请求根本没发出去。TaoToken 在这里的作用是提供一个兼容 Anthropic 接口的调用入口让 Claude Code 的请求能稳定落到模型上。你需要准备三样东西Base URL、API Key、Model ID。这三件套在后面的配置里会反复出现缺一不可。第一步拿到 API Key。访问https://taotoken.net/api-keys带 UTM?utm_sourcetaotoken_aicg_blog_endutm_contentskill_md_guideutm_campaignrewrite在控制台创建一个新的 Key。建议按项目维度建 Key方便后续排查是哪个项目在消耗额度。第二步确认 Base URL。Claude Code 走 Anthropic 协议Base URL 填https://taotoken.net/api。注意这里不加 UTM 参数保持接口地址干净。第三步选 Model ID。Claude Code 场景下建议用 Claude 系列模型具体型号在控制台的模型列表里能看到。把 Model ID 记下来配置时要用。这三样准备好之后Claude Code 的请求链路就通了。你可以先用模型对话页面https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentskill_md_guideutm_campaignrewrite发一条测试消息确认 Key 和模型都正常再去配 Claude Code。为什么要先做这一步因为 Skills 的调试本质是观察模型有没有在正确的时机加载技能。如果请求本身时通时断你观察到的触发失败可能是网络问题不是 description 问题。先把底层链路跑稳后面的调试才有意义。对于需要长期跑编码任务、频繁触发 Skills 的团队可以考虑 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentskill_md_guideutm_campaignrewrite按用量规划比单次调用更可控。3. 可复制配置SKILL.md 模板与 SubAgent 协同这一节给出可以直接落地的配置。先看 SKILL.md 的完整模板再看它和 SubAgent 怎么协同。3.1 frontmatter 四字段设计SKILL.md 顶部是 YAML frontmatter四个核心字段name、description、license、allowed-tools。其中description是灵魂。--- name: sync-changelog description: Update CHANGELOG.md from git commits since the last release. Use when user says 更新 changelog / sync changelog / release notes or before a release tag. license: MIT allowed-tools: Read, Edit, Bash ---name反映能力而非技术用sync-changelog而不是bash-skill-1。description必须包含三要素触发时机、动作、触发词中英文都列。allowed-tools按最小权限原则给这个技能只需要读文件、改文件、跑 git 命令就不要给 Write 和 NotebookEdit。3.2 正文三层结构frontmatter 下面是正文按渐进式披露分三层快速参考、详细步骤、边界 case。# sync-changelog: 从 git commits 同步 CHANGELOG ## 快速参考 1. 读 git log --oneline -50 2. 按 Conventional Commits 分类 3. 追加到 CHANGELOG.md 的 [Unreleased] 段 4. 如果 [Unreleased] 段已发布新建 [版本号] 段 ## 详细步骤 ### 1. 读 git log - git log --oneline -50 --prettyformat:%h %s - 如果是 monorepogit log --oneline -50 -- 子项目路径 - 如果 commit 多于 50加 --since3 months ago ### 2. 分类Conventional Commits - feat: 新功能 - fix: bug 修复 - refactor: 重构无功能变化 - perf: 性能优化 - docs: 仅文档 - chore: 杂项 ### 3. 追加到 CHANGELOG.md - 找到 [Unreleased] 段没有则创建 - 按子标题分类追加### feat / ### fix / ### refactor - 每条带 commit hash用反引号包起来 ## 边界 case - 仓库没 CHANGELOG.md询问用户是否初始化 - commit 不规范归到 ### other 段 - 同一 commit 涉及多类别归到主要类别 - 已发布版本的 changelog 被改拒绝并提示 ## 深层引用 - Conventional Commits 规范见 references/conventional-commits.md - CHANGELOG 模板见 references/changelog-template.md正文控制在 100-200 行。超过 300 行就该拆把边界 case 和详细文档挪到references/子目录SKILL.md 里只留引用。3.3 与 SubAgent 协同Skills 和 SubAgent 可以叠加使用。一个复杂任务主对话先调起 SubAgent 跑隔离上下文SubAgent 内部再用 Skill 加载专项能力渐进式披露。这是分层能力调用。SubAgent 的配置放在.claude/agents/下同样需要三件套对齐{ name: code-reviewer, description: Review code changes for quality and security issues, model: 你的 Model ID, base_url: https://taotoken.net/api, api_key: 你的 API Key, tools: [Read, Bash], skills: [audit-security, sync-changelog] }注意base_url、api_key、model三件套要和 Claude Code 主配置一致否则 SubAgent 启动时会因为鉴权失败直接报错。skills字段声明这个 SubAgent 可以加载哪些 Skill形成能力组合。3.4 目录结构.claude/ ├── skills/ │ └── sync-changelog/ │ ├── SKILL.md │ └── references/ │ ├── conventional-commits.md │ └── changelog-template.md ├── agents/ │ └── code-reviewer.json └── settings.jsonsettings.json里配置 Claude Code 的全局 Base URL 和 Key{ api: { base_url: https://taotoken.net/api, api_key: 你的 API Key, model: 你的 Model ID } }这套配置落地后Skill 的自动触发链路就具备了运行条件。4. 验证请求从手动触发到自动命中配置写完必须验证。分两步先手动确认 Skill 能被加载再验证自动命中。4.1 手动触发验证在 Claude Code 里直接说用 sync-changelog 更新 changelog。如果 Skill 配置正确Claude 会加载 SKILL.md 正文并按步骤执行。这一步验证的是Skill 本身能不能跑通和触发机制无关。观察点Claude 是否读到了快速参考、是否按详细步骤执行、遇到边界 case 是否按规则处理。如果这一步就失败说明 SKILL.md 内容有问题先修内容。4.2 自动命中验证手动跑通后换一种说法不提技能名只说需求帮我更新一下 changelog。这时候 Claude 应该自动匹配description里的触发词加载 sync-changelog。如果没命中检查三件事description里有没有更新 changelog这个触发词触发词是不是写成了何时触发而非做什么有没有其他 Skill 的 description 关键词重叠导致模型选错。4.3 用日志确认加载Claude Code 在加载 Skill 时会有日志输出。你可以观察请求里是否包含了 SKILL.md 的正文内容。如果description匹配上了但正文没加载说明 frontmatter 格式有问题比如 YAML 缩进错误。4.4 触发率优化自动命中不是 100% 的取决于 description 写得准不准。优化方法把用户可能说的各种说法都列进触发词中英文都覆盖。比如更新 changelogsync changelogrelease notes生成发布说明都写上。触发词越具体命中率越高。实测下来一个 description 写得到位的 Skill在相关对话里的自动命中率能到 80% 以上。剩下的 20% 靠用户手动点名兜底。5. 本篇常见错排查401、local proxy failed、reading choices调试 Skills 时遇到的报错很多其实和 Skill 本身无关是底层请求链路的问题。逐个排查。5.1 401 Unauthorized最常见。说明 API Key 无效或没传对。检查settings.json里的api_key是否和 TaoToken 控制台创建的一致有没有多余空格。如果 Key 是对的还报 401检查 Base URL 是不是https://taotoken.net/api路径写错也会导致鉴权失败。5.2 local proxy failed这个报错通常出现在 Claude Code 启动阶段说明请求没能发出去。检查网络是否能访问 Base URL以及settings.json的 JSON 格式是否合法少个逗号就会解析失败。用curl直接测一下 Base URL 通不通能快速定位是配置问题还是网络问题。5.3 reading choices 相关报错这类报错说明请求发出去了但响应格式不符合预期。常见原因是 Model ID 填错了或者用了不兼容的模型。回到控制台确认 Model ID确保用的是 Claude 系列。如果换了模型还报错检查请求体里有没有多余的参数。5.4 OAuth 相关报错Claude Code 某些版本会走 OAuth 流程。如果你用的是 API Key 模式确保没有同时启用 OAuth 配置两者冲突会导致鉴权混乱。清理掉 OAuth 相关配置只保留 API Key 三件套。5.5 Skill 不触发但无报错这是最隐蔽的。请求正常、模型正常但 Skill 就是不加载。99% 是description问题。把 description 拿给同事看问你在什么情况下会用这个技能答不上来就是写错了。改成何时触发的写法重新验证。5.6 多个 Skill 触发混乱项目里 Skill 多了之后description 关键词重叠会导致模型选错。检查方法把所有 Skill 的 description 列出来看有没有两个以上共享同一批关键词。有就改其中一个的触发词保证互斥。排查顺序建议先确认三件套Base URL Key Model ID正确再确认请求能通最后才怀疑 Skill 配置。底层不通的时候调 Skill 是白费功夫。6. 把技能目录当成代码来维护Skills 用起来之后真正的挑战不是写第一个而是维护第十个。几个实践建议。技能目录要有命名规范。name反映能力用动词对象比如sync-changelog、generate-api-docs、audit-security。不要用skill1、myskill这种也不要带技术栈名。description 要定期审查。随着技能增多关键词重叠的概率上升。建议每个月过一遍所有 Skill 的 description确保互斥。发现重叠就调整触发词。SKILL.md 超过 300 行就拆。把边界 case 和详细文档挪到references/主文件只留快速参考和核心步骤。这是渐进式披露的工程价值——大多数情况只读前两层边缘情况才读第三层。Skills 和 SubAgent 的边界要清晰。需要独立上下文、工具白名单、可并行的任务用 SubAgentLLM 推理该用就用的能力用 Skill。判断心法用户会主动调吗是就用 Command需要隔离上下文吗是就用 SubAgent都不是就用 Skill。最后把技能目录纳入版本控制。.claude/skills/和.claude/agents/都提交到 git团队共享。新人拉下代码就能用同一套技能包不用重新配。需要长期跑 Agent 任务、频繁触发 Skills 的团队Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentskill_md_guideutm_campaignrewrite比按次调用更划算。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentskill_md_guideutm_campaignrewrite里面有完整的接口说明和示例。API Key 管理在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentskill_md_guideutm_campaignrewrite。