为什么 SKILL.md 写对了Claude Code 还是没触发技能如果你正在按 Agent Skills 规范写SKILL.md大概率已经踩过这个坑YAML 前置数据里的name、description都按规范填了目录结构也是标准的skill-name/SKILL.md但把技能目录丢给 Claude Code 之后它要么完全不加载要么加载了却不按技能里的指令走。问题往往不在技能文件本身而在 Claude Code 的模型通道没配通。Agent Skills 规范解决的是技能怎么描述、怎么被识别但真正读SKILL.md、判断要不要激活技能、执行技能里指令的是 Claude Code 背后的模型。模型通道没接上技能写得再规范也只是一堆静态文本。这篇就按接入配置的视角把两件事串起来一边按规范定义好SKILL.md一边通过 TaoToken 给 Claude Code 配好模型通道让技能里的name/description能被智能体正确触发。前置先把 TaoToken 的 Key 和 Base URL 拿到Claude Code 是真正消耗 Token 的 AI 工具技能文件只是喂给它的指令。所以第一步不是写技能而是让 Claude Code 能调用到模型。打开 TaoToken 官网进入控制台创建 API Key。拿到 Key 之后记下两个东西API Key形如YOUR_API_KEY后面填进 Claude Code 的配置Base URLhttps://taotoken.net/api这是 Claude Code 请求模型的入口如果你还没注册直接在官网完成注册再创建 Key 即可。Key 只在创建时完整显示一次记得先存好。可复制配置Claude Code 的 settings.json 怎么填Claude Code 通过环境变量读取模型通道核心是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这两个。推荐写进settings.json避免每次开终端都要重新 export。配置文件位置按系统选一个macOS / Linux~/.claude/settings.jsonWindows%USERPROFILE%\.claude\settings.json内容如下把YOUR_API_KEY换成你刚创建的 Key{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: YOUR_API_KEY } }如果你更习惯用环境变量也可以直接在 shell 里设置export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYYOUR_API_KEY两种方式选一种即可settings.json的好处是持久化重启终端不用重设。配好之后Claude Code 的所有模型请求都会走 TaoToken 的通道。这一步通了技能才有被读懂的前提。按规范定义 SKILL.md目录结构与 YAML 前置数据模型通道配好后回到技能本身。Agent Skills 规范里一个技能就是一个至少包含SKILL.md的目录skill-name/ └── SKILL.md # 必需可选地加上scripts/、references/、assets/来支撑技能。SKILL.md必须包含 YAML 前置数据后跟 Markdown 正文。前置数据里两个字段是必需的--- name: pdf-processing description: 从 PDF 文件中提取文本和表格填写 PDF 表单以及合并多个 PDF。在处理 PDF 文档或用户提及 PDF、表单或文档提取时使用。 ---name的约束比较严1-64 个字符只能用小写字母、数字和连字符不能以连字符开头或结尾不能有连续连字符而且必须和父目录名一致。所以PDF-Processing、-pdf、pdf--processing都是无效的。description是 1-1024 个字符非空要同时说清这个技能做什么和什么时候用它。规范里给的对比很典型# 好的写法包含触发关键词 description: 从 PDF 文件中提取文本和表格填写 PDF 表单以及合并多个 PDF。在处理 PDF 文档或用户提及 PDF、表单或文档提取时使用。 # 差的写法太笼统智能体判断不出何时激活 description: 帮助处理 PDF。可选字段包括license、compatibility、metadata、allowed-tools。其中compatibility只在技能有特定环境要求时才写比如compatibility: 需要 git、docker、jq 和访问互联网大多数技能不需要这个字段。metadata是字符串键值映射用来存规范未定义的额外属性建议键名足够独特避免冲突。一个带可选字段的完整前置数据长这样--- name: pdf-processing description: 从 PDF 文件中提取文本和表格填写表单合并文档。在处理 PDF 文档或用户提及 PDF、表单或文档提取时使用。 license: Apache-2.0 metadata: author: example-org version: 1.0 ---前置数据之后的 Markdown 正文没有格式限制写任何有助于智能体执行任务的内容。推荐包含分步说明、输入输出示例、常见边缘情况。注意一旦智能体决定激活技能整个文件都会被加载所以主SKILL.md建议控制在 500 行以下把长内容拆到references/里。验证技能被正确加载、模型请求走通配置和技能都就位后分两步验证。第一步验证技能文件本身合规。规范提供了skills-ref参考库skills-ref validate ./my-skill它会检查SKILL.md前置数据是否有效、命名是否符合约定。如果name和目录名不匹配、或者有连续连字符这一步就会报出来。第二步验证 Claude Code 能通过 TaoToken 调用模型并识别技能。启动 Claude Code输入一个会触发技能的任务比如帮我从这个 PDF 里提取表格。如果配置正确Claude Code 会通过ANTHROPIC_BASE_URL指向的 TaoToken 通道发起模型请求模型读取技能的name和description判断当前任务是否匹配匹配成功后加载整个SKILL.md正文按里面的指令执行如果技能没被触发先确认模型请求是否走通——这一步可以用 模型对话 快速测一下 Key 和通道是否正常。通道正常但技能不触发问题就在description的关键词覆盖上。本篇常见错排查报错一Claude Code 提示认证失败或 401多半是ANTHROPIC_API_KEY没填对或者settings.json里的 Key 带了多余空格。检查 Key 是否完整复制以及ANTHROPIC_BASE_URL是否写成了https://taotoken.net/api注意不要漏掉/api。报错二技能目录存在但 Claude Code 完全不加载先跑skills-ref validate ./my-skill。最常见的原因是name和父目录名不一致或者name里出现了大写字母、连续连字符。规范要求name必须与父目录名称匹配这一条最容易忽略。报错三技能加载了但该触发的时候不触发问题在description。规范明确说description应该包含有助于智能体识别相关任务的关键词。如果只写帮助处理 PDF模型判断不出什么时候该用。改成包含具体动作和触发场景的写法比如把用户提及 PDF、表单或文档提取时使用这类关键词补进去。报错四技能激活后行为不符合预期检查SKILL.md正文是否过长。规范建议主文件保持在 500 行以下把详细参考资料移到references/。正文太长会挤占上下文模型可能抓不住重点。另外确认文件引用用的是从技能根目录开始的相对路径且引用深度不超过一级。报错五改了配置但没生效settings.json的改动需要重启 Claude Code 才会重新读取。如果是用环境变量方式确认当前终端会话里export过或者写进了 shell 的启动文件。技能规范与模型通道缺一不可回到开头那个问题SKILL.md写对了但技能不触发本质是把技能描述和模型调用当成了两件事。Agent Skills 规范管的是前者——name、description、目录结构、渐进式披露这些决定了技能能不能被正确识别。但识别技能、执行指令的是 Claude Code 背后的模型模型通道没配通规范执行得再标准也没有意义。所以完整的接入是两条线并行一条是按规范定义好SKILL.md让name/description具备可被触发的语义另一条是通过 TaoToken 给 Claude Code 配好ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY让模型请求真正跑起来。如果你还在逐个配置 Key、反复调试通道可以到 API Keys 页面统一管理接入细节参考 接入文档。如果是要长期跑编码任务、频繁触发各类 Agent SkillsCoding Plan 会比按量调用更省心。技能规范决定智能体懂不懂模型通道决定它跑不跑得动两者都配好SKILL.md里的name和description才会真正被触发。