SKILL.md 不触发时很多人第一反应是改 description把关键词塞满但我想先提一个前提TaoToken 这类统一 API 通道如果没配通SKILL.md 根本连被读到的机会都没有。排查时我会先做一个分流动作——在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 创建一把 Key把 Claude Code 的 Base URL 填成 https://taotoken.net/api替换掉原来的模型地址然后跑 claude --debug。请求 200 而 skill 没加载才轮到 description 的事如果连 401 都过不去SKILL.md 写得多完美都没用。1. 先分清SKILL.md 不触发是模型通道还是 description 的锅1.1 两种“不触发”症状完全不同先说结论模型通道本身没配通时SKILL.md 连被读到的机会都不会有。Claude Code 每次对话要做两件事先向模型服务发一个 HTTP 请求再把本地可用的技能列表送进模型上下文。技能列表能否被模型看到前提是第一个 HTTP 请求能成功返回。遇到过官方额度不够、手动换过好几把 Key、或者在配置文件里改过 Base URL 的读者最容易撞见一种假象对话能继续但所有 skill 统统失效。这时候你以为是 DESCRIPTION 写坏了其实是模型根本没收到那份携带技能列表的请求。两种“不触发”是两种病通道型不触发问什么模型都答得吞吞吐吐甚至直接报 API 错误。debug 日志里看不到技能加载记录。特征是所有 skill 一起失灵。触发型不触发模型对话正常其他 skill 也能用只有你精心设计的那个不启动。特征是只有特定 skill 无响应。可以这样类比模型是来上班的新同事SKILL.md 是员工手册而模型通道是工牌门禁。门禁刷不过去手册写得再细人根本进不了办公室。1.2 用 claude --debug 先分流别急着改 YAML原文里提过一句很关键的话调试时可运行 claude --debug 查看详细加载日志。这一句包含完整排障思路——先看模型请求通没通再看技能加载到哪一步。终端里进入你的工作目录claude --debug启动后随便发一句“介绍一下你当前加载了哪些 skill”。日志会给出三样信息第一请求 URL 是否指向你期望的模型地址第二HTTP 状态码是 200、401 还是 404第三Claude Code 扫描到几个 skill 目录。我自己用这个命令排查过几次 skill 不触发它会把真实请求路径和技能加载情况原样打出来比反复猜 description 可靠得多。日志里如果直接出现“Failed to load”或一连串异常先看状态码那一行基本就能判断该不该继续查模型通道。2. 从 TaoToken 拿一把干净 Key把链路先跑通2.1 准备材料Key、Base URL、模型 ID排查通道问题最忌讳混着旧环境变量一起查。建议把 Claude Code 的模型通道单独指向一个统一 API 入口也就是用一个干净的账号、一把新 Key 来做对照实验。打开 TaoToken 注册并登录在控制台创建一把 API Key。创建时可以顺便看一眼模型广场确认当前可用的模型 ID 列表——这一步能省掉后面很多猜测。材料用途获取方式YOUR_API_KEY填入 ANTHROPIC_AUTH_TOKENhttps://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 控制台创建Base URL填入 ANTHROPIC_BASE_URLhttps://taotoken.net/api模型 ID填入 ANTHROPIC_MODEL以 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 模型广场当时列表为准注意区分两个地址凡是去网页注册、看模型、查用量走 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 凡是填进 Claude Code、Codex、CC Switch 这类工具里的接口地址一律用 https://taotoken.net/api末尾不要加 /v1。2.2 settings.json 里把 Claude Code 指到 TaoTokenClaude Code 支持在配置文件里统一设置环境变量。路径是~/.claude/settings.json用编辑器打开后在 env 块里写入{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY, ANTHROPIC_MODEL: your-model-id } }三个变量说明ANTHROPIC_BASE_URL 是请求真正发出的地址。TaoToken 做的是兼容通道协议格式保持 Anthropic 原生不变所以 SDK 会自动在 Base URL 后面拼上 /v1。这里手动写 /v1 反而会把地址变成 /api/v1/v1接下来只会收到 404。ANTHROPIC_AUTH_TOKEN 填的是你在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 创建出来的 API Key不是登录密码。注意别把 Key 提交到 Git 仓库。ANTHROPIC_MODEL 先不要凭记忆填打开模型广场看看当前列表里有哪些 ID复制粘贴最稳。保存 settings.json 后完全退出 Claude Code重新启动。提示第一次排障时如果拿不准模型 ID可以先不设 ANTHROPIC_MODEL让 Claude Code 用默认模型把链路测通。链路稳定后再回到模型广场挑一个合适的 ID 换上去。这样能避免“通道没通”和“模型 ID 写错”两个变量搅在一起。3. 从 debug 日志确认请求真的发出去了3.1 日志里三处关键信息重新运行claude --debug这次再看日志重点找三行第一行是 Request URL。正常情况下应该出现类似https://taotoken.net/api/v1/messages的地址。注意这里的/v1出现在客户端日志里但它在你的配置文件中并不存在——是 Anthropic 原生 SDK 自动拼接的。如果看到https://taotoken.net/api/v1/v1/messages说明 settings.json 里写错了。第二行是 HTTP Status。200 代表请求成功401 代表 Key 有问题404 大概率是 Base URL 路径出了问题。第三行是 Loaded skills。Claude Code 启动时会扫描~/.claude/skills/目录把发现的技能列出来。如果这里显示加载了 0 个技能路径检查优先于 description 检查。模拟一段日志长这样[debug] Request URL: https://taotoken.net/api/v1/messages [debug] HTTP Status: 200 [debug] Loaded skills: code-reviewer, pdf-processor出现这样的输出模型通道这一层就通了。接下来才轮到 SKILL.md 自己的问题。3.2 401、404、请求没发出分别对应什么动作对照下面的表格做判断现象可能原因处理方式一直 401 UnauthorizedKey 复制不完整或 Key 被刷新后旧 Key 失效回到 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 重新创建 Key替换 settings.json 里的 YOUR_API_KEY404 且 URL 出现 /v1/v1Base URL 多写了 /v1把 ANTHROPIC_BASE_URL 改回 https://taotoken.net/api请求没发出日志里没有 HTTP 记录settings.json 没有被读取确认文件位置是 ~/.claude/settings.json并且 Claude Code 完全重启200 但 skill 没加载SKILL.md 或 description 问题跳到下一节顺带解释一下“官网 vs 接口”的边界TaoToken 网页端负责注册、创建 Key、看用量、看模型广场也就是人操作的地方Claude Code 里填的 Base URL 是机器访问的接口。两者不能混着填。尤其不要把官网的 UTM 长链接填进 ANTHROPIC_BASE_URL那不是给 SDK 用的。4. 通道通了再回来打磨 SKILL.md 的触发机制4.1 目录、YAML、description 三层检查模型通道通畅后skill 依然不触发此时回到原文反复强调的那个点SKILL.md 靠 YAML frontmatter 里的 name 和 description 被路由。但 description 只是最后一层前两层要先踩稳。第一层是目录与命名。SKILL.md 必须放在~/.claude/skills/skill-name/SKILL.md。文件夹名字要和 YAML 里的 name 字段完全一致而且 name 只用小写字母、数字、连字符不要出现空格或中文。第二层是 YAML 格式。文件必须用两个---包裹元数据前后各一行。少一个---整个文件会被当成普通 Markdown永远无法触发。第三层才是 description。官方建议写成“一句功能说明 具体动作 触发关键词”的组合。还要注意写 description 时用祈使句直接描述动作不要出现“你帮我把”这类对话式措辞这是 Skill 设计区别于 Prompt 的地方。一个简单的 SKILL.md 开头示例--- name: code-reviewer description: 对代码做安全审查和 bug 检查。当用户说 review code、check for bugs、analyze security或提到 SQL 注入、XSS、性能瓶颈时使用。 --- # 代码审查 Skill 按以下步骤执行 1. 读取用户指定的代码文件。 2. 检查常见安全漏洞。 3. 输出风险等级与修复建议。4.2 用“黄金结构”重写 description避开空泛表达原文有一个很好的判断标准description 的首要任务不是给人看而是给 AI 的路由机制看。它需要明确回答两个问题这个 skill 是做什么的用户在什么场景下说话时应该触发它。把“处理 PDF”升级成可触发版本是这么改的低质量写法description: 处理 PDF 文件。高质量写法description: 从 PDF 文档中提取文本、表格和元数据合并或拆分文档。当用户提到 PDF、pdf 文件、表单填写、文档提取或要求“把 PDF 转成文字”时使用。低质量写法的问题在于用户很少直接说“处理 PDF”。他们会说“帮我把这个 PDF 里的表格提出来”或者“这份发票能转成 Excel 吗”。description 里没写这些触发场景模型自然想不起来调用它。模拟用户真实的提问方式把对应关键词写进去触发率会明显提升。如果你照着原文做过“HTML 信息图生成器”这个 skill应该能感受到这个差别description 里写清楚“Magazine Layout、深色主题、信息图”比写“生成 HTML 网页”更容易在“做个海报”的请求下被命中。5. 一次完整的触发验证流程5.1 用自然语言测别用 /skill 命令很多人验证 skill 是否生效时习惯在 Claude Code 里手动敲一条“调用某某 skill”的指令。这个动作测的是“手动调用”不是“自动触发”。而 Agent Skills 的核心机制是自动路由用户用自然语言提出需求模型自行判断是否加载技能。正确的验证方式是关掉所有手动调用入口直接说一句贴近用户原话的请求。假设你写的是 PDF 处理 skill就问“我上传了一份扫描版合同能帮我把里面的表格抽出来吗”。如果模型真的开始调用 pdf-processor skilldebug 日志里会出现对应的加载记录同时它的回答风格会明显按照 SKILL.md 里的步骤来。如果在日志里看到“Loaded skills”里有你的 skill 名称却始终没有出现在当前会话的调用列表里接下来检查 description 中的触发词和用户这句话的语义匹配度。5.2 对照测试清单逐项打勾把原文最后的“测试、调试与迭代”四阶段落实到一张清单上检查项操作方法通过标准路径检查打开~/.claude/skills/skill-name/SKILL.md文件确实存在文件夹名与 name 一致YAML 校验查看文件开头结尾两个---成对出现name、description 都有值触发测试用自然语言提问不用 /skill 命令debug 日志出现该 skill 的加载记录执行验证对比模型回答与 SKILL.md 中的指令回答步骤遵循了 instructions 里规定的顺序边界测试输入一个相似但不该触发的请求skill 没有被误调用如果前四行都通过说明 skill 已经进入正常生命周期如果第五行挂了比如用户只说“帮我把这段文字排版”你的信息图 skill 也被触发说明 description 里的触发范围写宽了需要收回关键词。6. 跑通后回到控制台对一下这次 SKILL 排查的账6.1 在 TaoToken 控制台核对这次调用模型通道切换完成后建议立刻回到 TaoToken 控制台 API Keys 页面 查看这把 Key 的调用记录。你应该能看到刚才 claude --debug 期间产生的请求条目状态码、模型、耗时都在里面。这一步的意义是确认“通道配置真的生效了”而不是靠感觉。日志里写着 200控制台里也记着一笔消耗两者能对上才算闭环。顺便也能检查一下刚才测试时用的模型是不是模型广场里那个预期 ID有没有偷偷路由到其他模型上。6.2 下一步按使用强度选套餐再看文档排查完之后如果打算把 TaoToken 作为日常 Claude Code 的固定通道建议先在 模型对话 里用同一把 Key 发几条消息确认模型行为和代码场景下的表现。长期写代码的话打开 Coding Plan 看看有没有适合你的计费档位。环境变量和 settings.json 的更多参数写法可以参考 Claude Code 接入文档接口地址、模型列表、常见报错都有对照说明。最后说一句掏心窝的话SKILL.md 的 description 写得好是锦上添花模型通道通才是雪中送炭。以后再遇到 skill 不触发别急着把 YAML 改来改去先跑一遍 claude --debug确认请求真的到了模型面前再回头读自己的技能文件。很多问题其实在门禁那一层就解开了。