1. 从一次 Skill 失效说起：为什么你的 SKILL.md 没被触发
很多人第一次写 Skill 都会经历同一个场景：文件放好了，SKILL.md也写了，结果在 Claude Code 里提问，模型压根没调用它。我试过把description写成「这是一个用于处理数据库迁移的 Skill」，看起来没毛病，但模型就是不触发。后来才明白，description不是给人看的摘要，而是给模型看的触发条件描述——它要回答的是「什么请求该用我」，而不是「我是什么」。
Claude Code 里的 Skill 本质是一个文件夹，不是单个 markdown。文件夹里可以有SKILL.md、references/、assets/、scripts/，甚至config.json。模型启动会话时会扫描所有可用 Skill 的description，构建一张「请求 → Skill」的匹配表。所以 Skill 工程化的核心就三件事：让模型知道什么时候用你、让模型知道怎么用你、让模型用完还能记住结果。
这篇聚焦的是可落地的工程链路：SKILL.md结构怎么拆、Agent 调用链路怎么走、hook 在什么时机触发，以及怎么用 TaoToken 的统一 Key 和 API 通道把整条链路串起来。适合已经在用 Claude Code、想把手头零散提示词沉淀成可复用 Skill 的开发者。下面所有配置都可以直接复制，改掉路径和 Key 就能跑。
2. TaoToken 前置：统一 Key 与 API 通道准备
Skill 要真正跑起来，绕不开模型调用。Claude Code 本身支持通过环境变量或settings.json指定 API 通道，这样团队里每个人不用各自维护一套 Key，也不用在多个项目里重复粘贴。TaoToken 在这里扮演的是统一入口的角色：一个 Key 覆盖模型对话、编码计划、控制台管理，接入文档里给了完整的参数说明。
你需要先拿到两样东西：API Key 和接入地址。Key 在控制台的 API Keys 页面创建，地址用https://taotoken.net/api（注意 API 地址不带任何查询参数）。创建 Key 的时候建议按用途分：一个给日常对话调试，一个给 Coding Plan 长期编码任务，避免一个 Key 到处用导致额度混乱。
拿到 Key 之后，先别急着写 Skill，先用最小请求验证通道是通的。这一步很关键，因为后面 Skill 里的 hook 和脚本都会复用这条通道，如果通道本身有问题，排障会非常痛苦。验证方式可以用 curl，也可以直接在 Claude Code 里发一条消息看是否正常返回。
注意：Key 不要写进会提交到 Git 的
SKILL.md或脚本里。推荐放在settings.json的环境变量段，或者用系统环境变量注入。团队共享时，让每个人用自己的 Key，而不是共用一个。
3. 可复制配置：settings.json 与 SKILL.md 骨架
先看settings.json的配置骨架。Claude Code 读取配置的优先级是项目级.claude/settings.json高于用户级，所以团队协作时把通道配置放在项目级，个人偏好放在用户级。下面这段是可直接复制的结构，把YOUR_API_KEY换成你自己的：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "YOUR_API_KEY" }, "skills": { "enabled": true, "directories": [".claude/skills"] } }这里ANTHROPIC_BASE_URL指向 TaoToken 的 API 通道，ANTHROPIC_API_KEY填控制台创建的 Key。skills.directories告诉 Claude Code 去哪里扫描 Skill 文件夹。配好之后重启会话，模型就能看到你放在.claude/skills/下的所有 Skill。
接下来是SKILL.md的骨架。一个能稳定触发的 Skill，结构大致如下：
--- name: db-migration description: 当用户需要创建、审查或回滚数据库迁移文件时使用。适用于 schema 变更、索引调整、字段重命名场景。 --- # 数据库迁移 Skill ## 何时使用 - 新增或修改表结构 - 调整索引 - 回滚上一次迁移 ## 操作步骤 1. 读取 `references/migration-template.md` 获取模板 2. 检查 `config.json` 中的数据库连接配置 3. 生成迁移文件到 `migrations/` 目录 4. 运行 `scripts/validate.sh` 做语法校验 ## Gotchas - 字段重命名必须先加新字段再删旧字段，不能直接 rename - 索引名冲突会导致迁移失败，命名前先查 `references/index-naming.md` - 回滚脚本必须和正向脚本成对出现注意description的写法：它描述的是触发场景，不是功能摘要。「当用户需要创建、审查或回滚数据库迁移文件时使用」比「数据库迁移工具」的触发率高得多。Gotchas 部分是信号最强的内容，把你踩过的坑写进去，模型下次就会避开。
4. 验证请求：Agent 调用链路与 hook 触发时机
配置写完之后，怎么确认 Skill 真的被调用了？最直接的方式是发一条明确匹配description的请求，然后观察 Claude Code 的输出里有没有读取SKILL.md的动作。比如你写了db-migrationSkill，就发「帮我给 users 表加一个 last_login 字段」，正常情况模型会先读 Skill 文件，再按步骤执行。
Agent 调用链路大致是：用户请求 → 模型扫描 Skill 列表 → 匹配description→ 读取SKILL.md→ 按需读取references/或执行scripts/→ 返回结果。渐进式披露就体现在这里：SKILL.md只放主干，详细签名和示例拆到references/api.md，模板放assets/，模型需要时才读，不占用默认上下文。
hook 的触发时机是另一个关键点。Skill 可以注册「按需启用」的 hook，只在调用该 Skill 时激活，持续到会话结束。比如一个/carefulSkill，通过 Bash 的 PreToolUse 匹配器拦截rm -rf、DROP TABLE、force-push这类危险命令。只有你明确知道自己在操作生产环境时才启用它，平时不启用，避免误伤。
{ "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "python3 .claude/skills/careful/check_dangerous.py" } ] } ] } }这个 hook 在每次 Bash 工具调用前执行check_dangerous.py，脚本里判断命令是否命中危险模式，命中就返回非零退出码阻断执行。验证方式是故意发一条rm -rf /tmp/test，看是否被拦截。如果没拦截，检查脚本路径和退出码逻辑。
5. 本篇常见错排查
Skill 不触发：九成是description写成了功能摘要。改成「当用户需要……时使用」的句式，把触发关键词放进去。另外确认settings.json里skills.directories路径正确，以及SKILL.md的 frontmatter 格式没写错。
hook 不生效：先确认 hook 是注册在 Skill 内部还是全局。按需 hook 只在 Skill 被调用后激活，如果你没触发 Skill，hook 自然不会跑。再检查matcher是否匹配到正确的工具名，Bash 工具的大小写要和实际一致。
脚本执行报权限错误：scripts/下的脚本需要可执行权限，chmod +x scripts/validate.sh。另外脚本里的路径建议用相对 Skill 目录的写法，避免换机器后路径失效。
数据存储丢失：Skill 升级时目录内数据可能被清掉。需要持久化的数据放到${CLAUDE_PLUGIN_DATA}这个稳定文件夹里，或者用纯追加的日志文件记录历史，下次运行时模型读自己的历史就能判断增量。
API 通道返回 401：检查ANTHROPIC_API_KEY是否填对，以及ANTHROPIC_BASE_URL是否写成了带查询参数的地址。API 地址就是https://taotoken.net/api，不要加多余后缀。如果 Key 是在控制台刚创建的，确认没有复制到多余空格。
模型读了 Skill 但没按步骤走：多半是SKILL.md写得太死板，把模型限制住了。给必要信息，但保留灵活调整空间。比如不要写「必须用 A 方法」，而是写「优先用 A 方法，如果 A 不适用则参考references/alternatives.md」。
6. 把 Skill 工作流跑成日常
Skill 真正产生价值，是在它被反复调用、持续迭代之后。大多数好用的 Skill 最初只是几行说明加一个 gotcha，后来因为不断有人往里补边缘情况才变得可靠。所以别追求一次写完美，先让链路跑通，再在每次踩坑后往 Gotchas 里加一条。
如果你还在调试单个 Skill 的触发和 hook，建议先把 API Keys 和接入文档过一遍，确认通道和 Key 没问题；想验证模型对 Skill 的响应是否符合预期，可以直接在模型对话里试；如果是要把 Skill 接进长期编码或 Agent 工作流，Coding Plan 更适合承载这种持续调用。三条路径按你的阶段选，不用一次全上。
最后留一个实用习惯：给每个 Skill 建一个standups.log或类似的追加日志，记录每次调用的输入和结果。下次运行时模型读这个日志，就能知道「和上次相比发生了什么变化」。这个模式在站会报告、周报汇总、部署记录这类 Skill 上特别管用，也是把一次性提示词变成可复用工作流的关键一步。
