在 ~/.claude/skills/ 里放好 SKILL.md 后很多人以为 Claude Code 的 Skills 会自动按需加载结果第一次用 skill 名触发时卡在“Claude Code 到底该走哪个 Base URL、API Key 从哪来”。TaoToken 在这里只做一件事给出一条兼容通道和一把统一 Key。你打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_content 注册并创建 YOUR_API_KEY再把 Claude Code 的 ANTHROPIC_BASE_URL 填成 https://taotoken.net/apiSkills 的三层渐进式披露不会被改变name 和 description 先形成技能目录匹配到之后才读 SKILL.md 主体需要脚本或参考资料时才去碰 scripts/ 和 references/。下面按原文的 3 分钟核心原理节奏把通道配置插到真正会卡住的那一步。1. SKILL.md 在 Claude Code 里为什么不是一上来就全读1.1 元数据层启动时只加载 name 和 descriptionClaude Code 扫描技能目录时不会把每个 SKILL.md 从头读到尾。它先看顶部的 YAML front matter也就是name和description。每个技能的这两项大概百级 Tokens 量级最后拼成一份“技能目录”。这份目录像会议室门口的名牌只告诉模型“这里有哪些能力、什么时候该找它”而不是把整份操作手册都塞进上下文。所以 description 写得含糊模型很难在正确场景里想起这个技能反过来description 写得像触发条件技能目录命中率就会高很多。这里和 Base URL 无关无论你走官方通道还是走兼容通道元数据层的读取方式都由 Claude Code 自己决定。1.2 核心指令层命中后才读 SKILL.md 主体当用户请求和某个 description 对得上Claude Code 才会把对应的 SKILL.md 主体读进上下文。主体里通常放步骤、约束、输出格式、边界条件。比如一个“SQL 解释”技能主体可以写先让用户贴 SQL 和表结构再解释 JOIN、WHERE、GROUP BY 的顺序最后给候选改写和索引建议同时明确不连接数据库、不执行 SQL。这个阶段才是技能真正开始干活的地方。模型通道是否通畅会影响这一步能不能把请求发出去但不会改变“先目录、后主体”的加载顺序。核心指令层读的是 SKILL.md 正文不是 scripts/ 里的脚本。1.3 扩展资源层scripts/ 与 references/ 更晚加载如果 SKILL.md 主体里提到要看 scripts/ 下的脚本或者读 references/ 里的参考文件Claude Code 才会进一步加载这些扩展资源。它们比主体更重按需读取才省上下文。你可以把它理解成技能目录是名片SKILL.md 主体是操作卡scripts/ 和 references/ 是抽屉里的工具和资料。只有操作卡上写了“去抽屉拿某样东西”才会打开抽屉。这个设计决定了 Skills 能放很多知识但不会一上来就占满上下文。也正因如此把 Base URL 改到 TaoToken 不会破坏渐进式披露通道只负责模型请求往哪里走。扩展资源层仍然由 Claude Code 按需决定。2. 个人 ~/.claude/skills/、项目 .claude/skills/ 和插件三种存放位置2.1 个人 ~/.claude/skills/跨项目复用个人技能目录适合你自己反复用的能力比如解释 SQL、生成正则、整理提交信息。路径通常长这样~/.claude/skills/sql-explain/SKILL.md。放在这里的技能只在本机生效换电脑要同步或者把目录纳入自己的 dotfiles。它的好处是打开任何项目都能用不会因为换仓库就消失。注意不要把 API Key 写进 SKILL.mdKey 应该放在 Claude Code 的 env 或系统环境变量里来源是你在 TaoToken 官网创建的那把 YOUR_API_KEY。个人技能适合放“通用但轻量”的规则别把公司生产库连接串塞进去。2.2 项目 .claude/skills/跟仓库一起版本化项目级技能放在仓库的 .claude/skills/ 下例如 .claude/skills/sql-explain/SKILL.md。它适合和代码一起 review、一起版本化。团队里有人改了技能说明Git diff 能看见。项目技能的优先级通常更贴近当前代码库适合放“本项目特有的规范”比如某张表不能直接查、某个模块的 SQL 必须带租户条件。提交前检查一遍SKILL.md 里不要出现真实 Key、内网地址、生产库连接串。技能只写“生成什么、解释什么、让读者本地执行什么”不要写“自动连上生产库执行”。模型通道只认 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_MODEL技能文件不负责这些。2.3 插件技能适合团队分发插件是第三种来源。它把技能打包分发安装后出现在 Claude Code 可发现的技能集合里。适合团队统一安装、统一升级但要注意同名技能冲突。如果个人目录和项目目录都有同名技能Claude Code 会按自己的优先级选择排障时先确认当前命中的是哪一个 SKILL.md再看 description 和主体。三种位置不是互斥的你可以把通用能力放个人目录把项目约定放项目目录把团队标准流程放插件。无论放哪里落到执行层时Claude Code 仍然只生成、解释、对照代码或 SQL诊断 SQL、编译运行由读者在本地或 SQL*Plus 执行再把结果贴回对话。存放位置路径示例适合场景注意个人~/.claude/skills/sql-explain/SKILL.md跨项目复用换机器要同步不要提交密钥项目.claude/skills/sql-explain/SKILL.md跟仓库版本化提交前检查敏感信息插件由插件管理团队分发同名冲突时确认优先级3. description 决定技能目录能不能命中SKILL.md 主体只负责执行细节3.1 description 写触发场景不写口号description 是技能目录里最重要的检索字段。不要写“很强大的 SQL 技能”“提升效率”而要写清楚“当用户需要……时使用”。模型在元数据层只能看到这句话它不知道你后面写了多少步骤。描述里最好包含动作、对象和边界。比如“当用户需要解释一段 SQL 的查询逻辑、索引使用或改写建议时使用只生成解释和候选 SQL不连接数据库不直接执行。”这样既告诉模型什么时候想起它也告诉它不要越界。通道换了、模型换了这条规则仍然成立。description 是触发入口SKILL.md 主体是执行细节两件事不要混着写。3.2 一个可复用的 YAML front matter 模板下面这个模板可以直接放进 ~/.claude/skills/sql-explain/SKILL.md 或项目 .claude/skills/sql-explain/SKILL.md。注意 name 用短横线description 用一句完整触发句。--- name: sql-explain description: 当用户需要解释一段 SQL 的查询逻辑、索引使用或改写建议时使用。只生成解释和候选 SQL不连接数据库不直接执行。 --- # SQL 解释技能 1. 让用户贴出 SQL、表结构和必要索引信息。 2. 解释 FROM、JOIN、WHERE、GROUP BY 的逻辑顺序。 3. 给出候选改写和索引建议并标注假设。 4. 提醒用户诊断 SQL 请在本地或 SQL*Plus 执行把执行计划和报错贴回对话。这个技能被触发后Claude Code 才会读主体。读主体后它也只是生成解释和候选 SQL不会去连生产库更不会执行 impdp、FETCH 这类操作。需要真实执行时由读者在本地或 SQL*Plus 里做再把结果贴回来继续分析。技能主体可以写“怎么解释”但不要写“帮我直接跑”。3.3 别把长流程塞进 descriptiondescription 太长会拖累技能目录的可读性也容易和其他技能混淆。把长流程放到 SKILL.md 主体把“什么时候用”留在 description。一个实用判断如果一句话不能让你在 3 秒内判断“这个请求该不该触发它”那就还没写清楚。技能目录形成之后Claude Code 先匹配描述再决定读不读主体你把描述写准后面 scripts/ 和 references/ 的按需加载才有机会发挥作用。名字也要稳定name 频繁改调用习惯和文档都会乱。4. ANTHROPIC_BASE_URL 接到统一 APIsettings.json 与环境变量两种写法4.1 先创建 YOUR_API_KEY 并确认模型 ID打开 TaoToken 官网 注册并创建 API Key。Key 一律用占位符 YOUR_API_KEY 写在配置里不要硬编码进 SKILL.md。模型 ID 不要自己拼日期后缀也不要把道听途说的名字写进配置以官网模型广场当时列表为准。你可以在同一个控制台里复制模型 ID再回到 Claude Code 配置。这里要分清两件事给人点的官网链接用于注册、创建 Key、看模型广场、看用量填进工具的 Base URL 是 https://taotoken.net/api末尾不要加 /v1也不要带任何 UTM 参数。配置之前先把 Key 复制到安全的地方别贴进聊天记录。4.2 ~/.claude/settings.json 的 env 写法Claude Code 支持在 ~/.claude/settings.json 的 env 里写环境变量。把下面三个值填进去保存后重新打开 Claude Code让它重新读取配置。{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY, ANTHROPIC_MODEL: YOUR_MODEL_ID } }注意ANTHROPIC_BASE_URL只写到 https://taotoken.net/api。有人习惯性补 /v1结果请求路径变成双份或者落到不存在的端点表现就是 404。ANTHROPIC_AUTH_TOKEN 填 YOUR_API_KEY不要填官网地址也不要填登录密码。ANTHROPIC_MODEL 填从模型广场复制的 ID不要自己编。JSON 里不要留多余逗号保存后最好用编辑器校验一次。4.3 临时环境变量写法如果你只想在当前终端会话里试一次可以在 macOS 或 Linux 的 shell 里临时 exportexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENYOUR_API_KEY export ANTHROPIC_MODELYOUR_MODEL_IDWindows PowerShell 里对应写法是$env:ANTHROPIC_BASE_URLhttps://taotoken.net/api $env:ANTHROPIC_AUTH_TOKENYOUR_API_KEY $env:ANTHROPIC_MODELYOUR_MODEL_ID临时变量的好处是改完即可生效关掉终端就消失缺点是每次新开窗口都要重来。长期使用还是写进 ~/.claude/settings.json或者写进你的系统环境变量。无论用哪种方式Base URL 后面都不要拼 /v1也不要带 UTM。环境变量名不要写成 ANTHROPIC_API_KEY 之外的自造名字Claude Code 认的是它自己的键。4.4 统一通道不参与 Skills 分层加载这里要划清边界TaoToken 只提供 Key 和 Base URL 这条模型调用通道不参与 Skills 的元数据层、核心指令层、扩展资源层。Claude Code 仍然先读 name 和 description 形成技能目录命中后才读 SKILL.md 主体再按需读 scripts/ 和 references/。所以“Base URL 改到 TaoToken 行不行”这个问题答案是行但前提是别把通道配置和技能加载混为一谈。你把 Base URL 填对技能加载逻辑照旧你把 description 写好技能命中率也不会因为换了通道而改变。5. 用 skill 名跑一次验证 description 命中和通道都正常5.1 准备一个最小 SKILL.md在项目根目录创建 .claude/skills/sql-explain/SKILL.md内容用上面那个最小示例。保存后Claude Code 下次扫描技能目录时只会先看到 name 和 description。它不会因为 Base URL 指向了统一 API 就提前读主体也不会因为标题里有 Skills 就跳过元数据层。这个最小技能故意写得很克制只解释、只给候选 SQL、不连接数据库、不执行。这样你验证通道时不会误触生产操作。技能目录里出现的是 name 和 description主体只有匹配后才加载。5.2 先问无关问题再问触发场景打开 Claude Code先输入一个和 SQL 无关的请求比如“帮我把这个 CSS 变量改名”。如果技能目录工作正常它不应该把 sql-explain 的 SKILL.md 主体读进来。然后再输入“帮我解释这段 SQL 为什么慢”并贴上表和索引信息。这时 description 命中Claude Code 才会读 SKILL.md 主体。不同版本的上下文面板或调试入口不一样不用死记某个命令你关注的是行为差异无关请求不展开主体相关请求才展开主体。如果两次都触发了主体先检查 description 是不是写得太宽如果两次都不触发先检查 front matter 格式和目录层级而不是先怀疑 Base URL。5.3 同一把 Key 去模型对话发一条配置保存并重启 Claude Code 后可以到 模型对话 用同一把 YOUR_API_KEY 发一条测试消息。模型对话能通说明 Key 和模型 ID 没填错Claude Code 里再触发一次 skill说明技能目录和主体加载路径也走通了。注意模型对话里不要贴真实生产数据先用示例 SQL 或脱敏语句验证。通道验证和技能验证分开做排障时就不会把“Key 错”和“description 写宽”混成一个问题。模型对话里也可以顺便确认当前模型 ID 和官网列表一致。6. 401、404、多写 /v1 和 skill 不触发怎么分6.1 401/403Key 没带上或没重启如果 Claude Code 报 401 或 403先看 ANTHROPIC_AUTH_TOKEN 是不是 YOUR_API_KEY而不是占位符本身。检查 ~/.claude/settings.json 的 JSON 有没有多余逗号环境变量有没有被旧值覆盖。改完配置后要重新打开 Claude Code或者新开终端否则它可能还在用旧环境。还有一种情况Key 创建后没有复制完整尾部少了几位。回官网重新复制一次即可。不要把 Key 写进 SKILL.md也不要把 Key 贴到团队共享的技能仓库。6.2 404Base URL 多写了 /v1404 最常见的原因是 ANTHROPIC_BASE_URL 写成了 https://taotoken.net/api/v1。这里只填 https://taotoken.net/api末尾不要 /v1也不要带问号和 UTM。工具内部会按自己的协议拼请求路径你手动补 /v1 反而会拼错。另一个原因是把官网落地页链接误填进了 Base URL官网链接是给人打开注册和看控制台的不是接口地址。看到 404 时先把 Base URL 恢复成 https://taotoken.net/api再重启工具。路径里也不要留空格或换行。6.3 模型 ID 不匹配回到模型广场核对如果请求返回模型不存在、模型无权限或类似错误先不要改 Base URL去模型广场核对 ANTHROPIC_MODEL。模型 ID 以当时列表为准不要用记忆里的名字也不要自己加日期后缀。把复制的 ID 原样填进 settings.json 的 ANTHROPIC_MODEL保存后重启。模型对话能通、Claude Code 也报同一个模型错误时基本就是模型 ID 写错而不是 Skills 的问题。模型列表会更新配置里的 ID 也要跟着核对。6.4 skill 不触发先改 description不要怀疑通道通道通了但 skill 名输入后没反应更可能是 description 没命中。检查三件事第一SKILL.md 顶部是否有 YAML front mattername 和 description 是否在分隔符内第二description 是否写清了触发场景第三文件是否放在 ~/.claude/skills/ /SKILL.md 或 .claude/skills/ /SKILL.md。个人技能、项目技能、插件技能同名时确认当前生效的是哪一个。把 description 改到模型一眼能懂再重新触发不要在 Base URL 上反复折腾。现象更可能的原因处理401/403Key 没写对、配置没重启检查 ANTHROPIC_AUTH_TOKEN重开 Claude Code404Base URL 多了 /v1 或填成官网链接恢复为 https://taotoken.net/api模型不存在ANTHROPIC_MODEL 拼错以模型广场当时列表为准skill 不触发description 不清晰、front matter 或目录错检查 name/description 和技能路径7. 跑通之后对一下用量再决定模型对话还是 Coding Plan7.1 回控制台看这次 Claude Code 调用是否记上账技能触发成功之后打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_content 回到控制台看这次 Claude Code 调用是否出现在用量里。对照时间点和模型 ID确认请求确实走了统一通道而不是被旧环境变量截走。这个动作能帮你区分两种问题如果控制台有记录说明通道通了Skills 不触发就回到 description 和目录结构如果控制台没记录说明 Claude Code 还在用旧配置重新检查 settings.json 和环境变量。看用量时也顺便确认模型 ID避免明天换了模型却忘了改配置。7.2 下一步页面模型对话、Coding Plan、API Keys、接入文档如果你想把这条链路固定下来先到 模型对话 用同一把 Key 发一条消息确认模型 ID 和 Base URL 没填错准备长期写代码再到 Coding Plan 看套餐是否够用Key 在 控制台 API Keys 创建和管理Claude Code 环境变量对照见 接入文档。把 description 改到能被模型一眼看懂把 ANTHROPIC_BASE_URL 保持为不带 /v1 的 https://taotoken.net/apiSkills 的按需加载仍由 Claude Code 自己判断而你只是把模型调用统一到了一把 Key 上。下一次再遇到 skill 不触发先动 description不要先动通道。