1. 从一次“技能不触发”的排查说起Claude Code 的 skill 机制刚上手时最容易踩的坑不是写不出 SKILL.md而是写完了它压根不触发。我见过太多人把技能目录建在项目根目录下然后对着 Claude Code 输入/skills发现列表空空如也回头怀疑是不是版本不对、是不是要重启、是不是要装插件。其实问题往往出在路径和元数据这两件事上。先把概念说清楚Claude Code 里的 skill 是一套可复用、可约束、可执行的能力单元入口是一个叫SKILL.md的文件。它最大的价值在于按需加载——平时只有 YAML Frontmatter 里的元数据会被打包进上下文只有当模型判断当前任务匹配某个技能时才会把 Markdown 正文加载进来。这意味着你可以往技能里塞很长的操作手册、参考资料、脚本调用说明而不用担心每次对话都烧掉大量 token。这套机制适合谁适合那些反复让 AI 做同一类结构化任务的人比如每次都要按固定格式梳理文章、每次都要按合规模板审计会议记录、每次都要跑同一套数据清洗脚本。把这些流程固化成 skill比每次手打一长串提示词稳定得多。而要让这套东西在真实项目里跑通除了 skill 本身的写法还需要一个稳定的模型通道——这就是后面要讲的 TaoToken 配置部分它负责把 Key 和 API 地址统一管起来让 Claude Code 的请求走一条可控的链路。下面按“建目录 → 写 SKILL.md → 加 references → 加 script → 配 TaoToken → 验证 → 排障”的顺序走一遍每一步都给可复制的命令和文件内容。2. TaoToken 前置把 Key 和 API 通道准备好在动 skill 之前先把模型通道理顺。Claude Code 这类工具最终是要发请求给模型的如果你用官方直连Key 管理、额度、多项目切换会比较散用 TaoToken 的好处是拿一个统一 Key通过一个 API 地址走配置集中在一个地方换项目时不用到处改。你需要做两件事拿 Key记下 API 地址。拿 Key 的入口在控制台登录后进 API Keys 页面创建一个新 Key复制出来先存好后面要填进配置文件。地址是https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewriteAPI 地址统一用这个注意它不带任何查询参数https://taotoken.net/api如果你还没注册从官网进https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注意Key 只显示一次创建后立刻复制。丢了就重新建一个别去猜。拿到这两样东西后先别急着写 skill我们先把 Claude Code 的 settings.json 配好确保基础请求能通再往上叠 skill 逻辑。这样出问题时能快速定位是通道问题还是 skill 写法问题。3. 可复制配置settings.json 与 SKILL.md 骨架3.1 settings.json 里的统一通道配置Claude Code 的配置一般放在用户目录下的.claude/settings.json。如果你之前没建过直接新建。核心是把 API 地址和 Key 通过环境变量注入让 Claude Code 走 TaoToken 的通道。{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥 } }把sk-你的TaoToken密钥换成你在控制台创建的那串。保存后Claude Code 启动时会读取这个文件所有请求就走https://taotoken.net/api了。提示如果你在多个项目里用不同的 Key可以把 settings.json 放在项目级目录.claude/settings.json它会覆盖用户级配置。日常建议用户级放一个通用 Key项目级按需覆盖。3.2 建技能目录skill 的存放位置在用户目录下的.claude/skills。每个技能一个子目录目录名建议和技能名一致方便管理。我们建一个叫shuli的技能mkdir -p ~/.claude/skills/shuli cd ~/.claude/skills/shuli3.3 写第一个 SKILL.mdSKILL.md 的结构是固定的顶部 YAML Frontmatter 包在---之间下面是 Markdown 正文。Frontmatter 里name和description是必需的description尤其关键模型就是靠它判断要不要加载这个技能。--- name: shuli description: 用于梳理文章或文字内容、段落将长篇内容压缩为简短易懂的一段话。当用户要求“梳理”时触发。 version: 1.0.0 --- # 梳理 ## 角色定义 你是一名文章梳理工程师擅长把长篇大论压缩成一段简单易懂、一目了然的文字。 ## 核心指令 1. 读取用户提供的原文。 2. 提取核心信息去掉修饰和重复。 3. 仅输出梳理后的内容不要额外解释。 ## 输出格式 - 仅输出梳理后的内容 - 语言通俗、简短 ## 示例 **用户输入**小明非常爱吃青菜因为这样能有助于身体发育和健康成长 **用户输出**小明爱吃菜可以长高高且健康保存后打开 Claude Code输入/skills你应该能在列表里看到shuli。如果没看到先检查目录层级是不是~/.claude/skills/shuli/SKILL.md文件名大小写是否一致。3.4 触发验证输入一句带“梳理”的提示请帮我梳理这段文章过去20年最佳的投资对象就是闹钟任何新兴市场投资在长线来看都跑不过闹钟货币和市场地位的上升空间。因为闹钟的上升空间是无限的最多速度慢一点需要用一点美元资产对冲波动。正常情况下Claude Code 会识别到“梳理”这个触发词加载shuli技能的正文然后按你定义的输出格式返回一段压缩后的文字。到这一步基础链路就通了。4. references 与 script 的高级用法基础 skill 能省 token但任务一复杂SKILL.md 正文就会膨胀。比如你希望梳理技能在遇到“总结”时额外输出字数、关键字、标题在遇到“统计”时跑一个脚本算字符数。如果把这些规则全写进正文每次梳理都要加载一堆用不上的内容。references 和 script 就是解决这个问题的。4.1 references条件触发的补充资料references 是放在技能目录下的参考文件只有在 SKILL.md 里明确指示、且条件满足时才会被读取。先建目录和文件mkdir -p ~/.claude/skills/shuli/references新建references/文章总结助手.md# 文章总结助手 ## 总结规则 - 文章字数 - 文章关键字 - 文章标题 注意每项只能分别使用一句话来表示不要分成多条。 ## 触发方式 当用户内容包含“总结、梳理”时自动激活 ## 示例 输入AI叙事现在很复杂不排除一种可能是美国AI完蛋了但中国AI巨幅崛起 输出 文章字数34 文章关键字AI、美国 文章标题美国AI完蛋中国崛起然后修改 SKILL.md在正文里加一条条件规则## 梳理规则 - 文字必须简短、通俗、易懂 - 统计提醒仅在提到“总结”时触发需读取 ./references/文章总结助手.md 进行总结注意这里写的是相对路径./references/文章总结助手.mdClaude Code 会基于技能目录去解析。改完后测试帮我用技能梳理这篇文章2026年“Skills”成为AI圈热词。其中GitHub狂揽30K Stars的“Superpowers”备受瞩目它通过系统化工作流让AI从“美工”进化为“全能架构师”。最后请对这篇文章进行总结你会看到 Claude Code 先触发shuli技能然后因为出现了“总结”它提示要读取文章总结助手.md确认后按字数、关键字、标题三项输出。这就是 references 的价值不触发就不加载触发了才读。4.2 script让模型运行而不是读取script 的思路更进一步。如果技能需要做精确计算或数据处理与其让模型读一大段代码再“心算”不如直接让它运行脚本。运行脚本时模型不需要读取脚本内容哪怕脚本上万行也不占 token。在技能目录下新建count.pyimport sys # 获取所有参数排除脚本自身 args sys.argv[1:] if not args: print(未传入任何参数) else: # 拼接所有参数 all_text .join(args) # 统计总字符数 total len(all_text) print(参数内容, all_text) print(总字符数, total)然后在 SKILL.md 里加统计规则## 统计规则 如果用户提到“统计”时你必须运行 count.py 脚本进行统计脚本使用方法 python count.py 梳理内容测试帮我用技能梳理这篇文章2026年“Skills”成为AI圈热词。其中GitHub狂揽30K Stars的“Superpowers”备受瞩目。最后请对这篇文章进行统计Claude Code 会触发shuli识别到“统计”然后执行python count.py ...把字符数打出来。这里的关键是措辞要明确“运行”而不是“读取”否则模型可能去读脚本内容反而浪费 token。4.3 references 与 script 的定位差异维度referencesscript加载方式条件满足时读取内容进上下文直接执行不读内容适用场景规则文档、模板、示例库计算、格式转换、数据处理token 消耗读取时消耗执行时不消耗典型指令“读取 references/xxx.md”“运行 scripts/xxx.py”一句话references 是给模型看的资料script 是让模型用的工具。分清楚这两者技能包才不会臃肿。5. 验证请求与成功结果配置和技能都写完后做一次端到端验证。先确认通道通再确认技能触发。第一步在 Claude Code 里发一个最简请求确认模型能正常返回你好请回复“通道正常”如果这一步就报错说明 settings.json 里的ANTHROPIC_BASE_URL或 Key 有问题先解决通道别往下走。第二步输入/skills确认shuli在列表里。第三步发一条同时触发 references 和 script 的提示帮我用技能梳理这篇文章AI编程工具正在快速迭代从补全到 Agent 再到 skill 机制开发者的工作流在被重塑。最后请对这篇文章进行总结和统计预期结果Claude Code 触发shuli读取文章总结助手.md输出字数、关键字、标题然后运行count.py输出字符数。整个过程你能在对话里看到它先请求读取文件、再请求执行命令的步骤。如果 references 没触发检查 SKILL.md 里的路径是不是./references/文章总结助手.md文件名有没有写错。如果 script 没执行检查规则里是不是用了“运行”这个词以及count.py是否在技能根目录下。6. 本篇常见错排查技能不显示在/skills列表里九成是路径问题。确认是~/.claude/skills/技能名/SKILL.md不是~/.claude/skill/也不是项目根目录。文件名必须全大写SKILL.md。技能显示了但不触发看description写得够不够具体。只写“用于梳理”太泛模型可能匹配不上。把触发词写进去比如“当用户要求‘梳理’时触发”。触发词要和用户实际输入对得上。references 读取失败路径写错是最常见的。用相对路径./references/文件名.md确保文件真实存在。文件名里有中文没问题但要注意大小写和扩展名。script 不执行或报错先确认规则里写的是“运行”而不是“读取”。再确认脚本路径如果脚本在技能根目录直接写python count.py如果在子目录写全相对路径。另外确认本机有 python 命令Windows 上可能是python或py。请求报 401 或 403Key 错了或没生效。检查 settings.json 里的ANTHROPIC_API_KEY是不是完整复制有没有多余空格。改完配置后重启 Claude Code。请求超时或连不上确认ANTHROPIC_BASE_URL是https://taotoken.net/api不要多加斜杠或路径。网络环境正常的话这个地址是通的。token 消耗还是很高检查是不是把大段内容写进了 SKILL.md 正文而不是 references。正文是每次触发都加载的参考资料应该放 references 里条件加载。7. 把通道和技能串起来下一步怎么走skill 这套机制跑通之后你会发现它和 MCP 是两种定位。MCP 偏向从远程服务拉数据skill 偏向处理这些数据——一个负责取一个负责加工。skill 也能通过脚本调远程接口但那属于“能做”不等于“合适”就像开发服务器程序 Java 是首选用 Node 或 Python 也能写合不合适是另一回事。定位清楚架构才不会乱。如果你打算把 skill 用在长期编码或 Agent 场景里建议把 TaoToken 的 Coding Plan 用起来额度管理更省心https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite想先在对话里验证模型对 skill 的理解和触发判断可以用模型对话页快速试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite接入细节和参数说明看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteKey 管理和新建还是在控制台https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite最后给一个实操建议每加一个 references 或 script都单独测一次触发别一次性堆完再调。skill 的调试成本主要在“模型有没有正确判断该不该加载”一次只改一个变量出问题最容易定位。
