最近在给 Claude Code（下文统一叫 CC）做技能包管理，盯上了社区里那个很火的 skill-creator。本来以为只是把技能目录放进去、重启会话就能跑，结果折腾了一下午：技能包本身两分钟就放好了，真正卡住我的是装完之后 CC 每次请求都栽在/responses这一环，401、404、502、503 换着花样来。
后来才搞明白，问题基本不在 skill-creator，而在它上层的模型路由——我为了在 DeepSeek、Qwen、GLM 这几个模型之间无缝切换，一直用 cc switch 做本地代理转发，技能包能不能正常干活，反而取决于代理那一侧的配置。这篇把完整安装链路和排障过程写出来，给还在观望的人做个参考。
1. 为什么要在 CC 里装一个 skill-creator：技能包生态的现状
1.1 CC 的技能机制到底是什么
CC 现在的技能机制其实不复杂：它会在固定的目录里扫技能包，每个技能包就是一个文件夹，文件夹里必须有一个SKILL.md，这个文件决定了 CC 什么时候触发这个技能、触发后按什么流程干活。默认目录是~/.claude/skills/，你放的每个子目录对应一个技能。
一个最小的SKILL.md长这样：
--- name: code-review description: 在代码提交前执行，针对变更内容做逐文件审查，输出问题清单和修改建议。 --- # Code Review 技能 1. 分析用户提供的 diff 或变更文件列表。 2. 按严重程度输出：阻塞性问题、建议性问题、风格优化点。 3. 每一项必须给出具体文件路径和可执行的修改方案。 4. 最后汇总修复耗时预估。头部那段 YAML 里的name是技能唯一标识，description是给 CC 看的触发描述。模型读到这个文件后，会在合适场景下把正文里的指令当作任务约束来执行。如果你只丢一个 markdown 说明文档进去，没有 YAML 头，CC 根本不会把它当成技能，这就是很多人"装了却没生效"的第一大原因。
技能的价值在于把反复要做的事沉淀下来。比如我团队里有固定的数据库迁移规范、代码提交信息规范、接口评审清单，每次靠嘴说太累，做成技能包之后，一句话就能让 CC 按整个流程走，省掉的不是几秒钟，是来回纠正提示词的半小时。
1.2 skill-creator 的定位：给你生成技能的技能
skill-creator 这个名字很容易被误解成"一个创建技能的程序员工具"，实际上它是一个技能包本身，只不过它的职责是帮你生成其他技能包。
它的典型用法是：你在 CC 会话里告诉它"我要一个技能，用途是审查 Python 代码中的数据库连接泄漏，输出报告要包含连接池使用情况、可疑代码位置、修复建议"，skill-creator 会根据你的描述自动生成目录结构和SKILL.md模板，甚至帮你把触发条件、工作流程、输出格式全部排好。
我见过不少开发者是自己手写SKILL.md的，短时间没问题，但技能一多就乱。有人把 description 写得含糊，导致 CC 老在不该触发的时候触发；有人把技能指令写在高层的 CLAUDE.md 里，根本没被结构化加载。skill-creator 解决的就是这种混沌状态——它强制你按模板来，每次生成的产物格式统一，后续维护成本低很多。
1.3 为什么我决定自己装，而不是让 CC 现场写
有人可能会说，你直接让 CC 帮你生成一份 SKILL.md 不就行了？何必再装一个技能包。
实话说，让 CC 临时生成确实能应急，但我踩过几次坑之后发现，Freeform 生成有两个非常明显的问题。
一是容易丢 frontmatter。你让 CC "写个技能文件"，它可能给你一份纯 markdown，没有 YAML 头，结果 CC 启动时扫不到，等于白做。二是格式不统一。同一个技能在不同时间让 CC 生成，得到的内容结构可能完全不一样，今天生成的带使用示例，明天生成的就没有，后续想批量维护非常痛苦。
skill-creator 这类工具最大的优势是确定性强。它是社区维护的、被反复测试过的模板流程，生成出来的技能包结构一致，frontmatter 字段稳定，触发描述有机会被仔细打磨过。安装一次，后续所有技能都走同一套生产线。
2. 安装前的准备工作：三个最容易漏掉的检查项
2.1 确认 CC 版本和 skills 目录位置
动手之前先确认环境。我见过不少人装完技能包没反应，最后发现是 CC 版本太老，根本不支持 skills 机制。
claude --version如果版本过旧，先升级再继续。然后确认技能目录存在没有：
mkdir -p ~/.claude/skills这一步很多人会跳过，以为系统默认建好了。实际上新装的环境里这个目录可能根本不存在，直接 git clone 时会提示路径找不到，或者更隐蔽——工具自动建了目录但结构不对，导致加进去的技能没被扫描到。
另外注意一点，如果你用的是团队共享配置，或者通过环境变量CLAUDE_CONFIG_DIR改了配置文件目录，那 skills 路径就不会是默认的~/.claude/skills，而是跟着配置目录走。确认不放心的话，在 CC 会话里直接问"你的技能目录在哪"，模型会从配置里读出实际路径。
2.2 检查 cc switch 的本地代理是否已经占住端口
这一步是我这次经历里最后悔没做的。因为我一直用 cc switch 做模型切换，它的工作方式是在本地起一个代理服务，然后把 CC 的 API 请求转发到不同供应商去。既然要装完技能立刻测试，那就必须在动手前知道代理当前的状态。
lsof -i :<cc-switch端口>如果你不确定端口号是多少，先看 cc switch 的默认配置。最常见的异常是端口被其他进程占住、代理服务没起来、或者配置文件里写了一个 cc switch 当前版本不再监听的端口。这三个情况表现完全一样——CC 请求/responses报错，但原因各不相同。
我自己的建议是：装技能包前先确认代理是健康的。可以临时把 cc switch 切到官方账号或者直连模式，跑一个最简单的 CC 会话，确认模型能正常回复之后再回来装技能。这样排障的时候，至少能确定问题不在基站。
2.3 备份现有 skills 目录
这步操作成本极低，但很多人不做。skill-creator 安装时可能会去读取或者改写 skills 目录下的内容（具体取决于你拿到的是哪种形态的 release 包），一旦冲突，轻则技能不可用，重则目录结构被改得乱七八糟。
cp -r ~/.claude/skills ~/.claude/skills.bak.$(date +%Y%m%d)一行命令，备份整个技能目录。装完新技能、验证没问题之后再删备份，完全不亏。我之前也是懒得备份，结果社区新版 skill-creator 要求技能目录里多一个manifest.json字段，旧技能没跟上，全部失效，那个下午就花在恢复上了。
2.4 安装版与便携版怎么选
cc switch 在社区里一直有安装版和便携版两个形态。安装版会写入本机配置目录，跟着系统环境走，适合主力开发机；便携版不写全局配置，目录放哪用哪，适合公司锁权限的机器或者放 U 盘里随身带着。
换成技能包的场景同理：skill-creator 我建议也用便携的思路管理，整个技能包文件夹放~/.claude/skills/skill-creator/，需要升级时直接换掉这个文件夹就行，不要让它依赖全局安装的 CLI 脚本。这样换机器、同步配置都简单，git 仓库一拉就是完整技能环境。
3. 动手安装 skill-creator：完整步骤和目录结构
3.1 从社区仓库获取技能包
一般是从 GitHub 社区仓库拿。注意看是否带 release 包，有的仓库源码和 release 内容有差别，源码包含测试目录和文档，release 包才是真正可以直接放进 skills 目录的交付形态。
cd ~/Downloads git clone <skill-creator 仓库地址> cd skill-creator git tag -l先看 tags，找最新的稳定版。不要直接拉 main 分支，我遇到过 main 分支上的模板格式和文档对不上，跑起来报 frontmatter 解析错误，切到v0.x.x的 release tag 就好了。
如果下载的是 zip 压缩包，解压后看一眼里面的目录结构。正常情况应该包含SKILL.md、scripts/（或assets/）之类的辅助文件。如果只有一个容器说明文档，说明你下错包了——那是项目文档，不是技能包本体。
3.2 放进 skills 目录的正确姿势
拿到技能包后，目标是把整个文件夹放到~/.claude/skills/下。我一开始犯了个错误，直接在~/.claude/skills里执行了 git clone，结果整个仓库变成一个文件夹，还带着.git目录。短时间没事，但后续升级时git pull容易出冲突。
推荐做法：
mkdir -p ~/.claude/skills cp -r ~/Downloads/skill-creator ~/.claude/skills/skill-creator rm -rf ~/.claude/skills/skill-creator/.git去掉.git目录很重要。CC 在扫描技能目录时会遍历文件，如果你留着.git，里面的对象文件会被某些版本误判为技能模板的一部分，轻则拖慢启动速度，重则触发奇怪的解析行为。不要问我是怎么知道的。
如果你有多个技能包，目录结构看起来应该是这样：
~/.claude/skills/ ├── code-review/ │ └── SKILL.md ├── db-migration/ │ ├── SKILL.md │ └── templates/ └── skill-creator/ ├── SKILL.md ├── assets/ └── scripts/3.3 检查 SKILL.md 头部元数据和依赖脚本
放进目录只是第一步，关键在SKILL.md的 frontmatter。至少检查三个字段：name、description、version（如果有的话）。
name不能有空格，它是技能的唯一标识。description要写得足够具体，尤其是触发场景。比如：
description: 当用户要求创建新技能、生成 SKILL.md、编写技能模板时使用。如果你发现 release 包里 description 写得比较宽泛，比如"help create skills"，建议在安装时就自己改成更精确的触发条件，不然之后 CC 可能会在一些无关场景里误触发这个技能。这是安装阶段就能避免的高频坑。
另外看SKILL.md是否引用了同目录下的脚本或资源文件。比如模板文件路径写成scripts/generate.py，那么scripts目录必须和SKILL.md同级，不能放到上层去。装完之后我习惯快速检查一遍文件引用：
find ~/.claude/skills/skill-creator -type f | sort确认所有被引用的模板、脚本、样例文件都在。
3.4 验证安装：在 CC 会话里触发一次
目录结构和 frontmatter 都确认完，重启 CC 会话，先输入/skills看看技能列表是否出现了 skill-creator。如果列表里有，执行一次最简单的触发测试，直接打：
"列出当前可用的技能，并说明 skill-creator 能帮我做什么。"
如果 CC 答复里能看到技能机制在正常工作，说明加载成功。如果这里就报错，先别急着往下排查，回到第 2 步检查SKILL.md格式和目录权限。注意如果~/.claude/skills是root或者其他用户创建的，CC 进程可能没有读取权限，chmod -R u+rwx ~/.claude/skills能解决。
4. 装完先别贪多：用它生成第一个真实技能的全流程
4.1 准备一份技能需求描述
安装只是起点，真正判断 skill-creator 值不值得留，要看生成流程是否顺滑。我的建议是不要一上来就生成复杂技能，先用一个无关紧要的小技能试水。
准备描述时，尽量包含四个信息：技能名称、触发场景、执行步骤、输出格式。例如我想生成一个"依赖升级检查"技能：
"创建一个技能，名为 dependency-updater，在用户提到依赖升级、版本更新时触发。执行时先解析项目依赖清单，然后逐个检查最新版本，对每个依赖给出升级建议，输出格式为表格，包含当前版本、最新版本、升级风险等级。"
不用太长，但场景和输出格式必须明确。这里强调一点：输出格式是很多人的盲区。你没有规定格式，skill-creator 生成的技能可能每次给的答案都不一样，后面维护就没法自动化。
4.2 让 skill-creator 按模板生成
在 CC 会话里，输入：
"使用 skill-creator，帮我根据上面的需求描述生成一个新技能包。"
正常情况下，skill-creator 会在技能目录下新建一个dependency-updater文件夹，写入SKILL.md，可能还会放一个references.md之类的辅助文件。生成完成后，它应该告诉你下一步做什么——比如"重启会话后即可使用"或者"将触发描述补充为英文以提高识别率"。
这里有个细节：skill-creator 生成的description默认继承你输入的需求描述，但它是中文的。CC 的技能触发机制对语言的敏感度我不太好一概而论，但实测下来，多语言描述识别更稳定，所以我习惯让 skill-creator 把 description 改成中英双语。如果你用的 generator 不支持，自己手动改一下 frontmatter 也是可以的。
4.3 生成的技能目录如何被 CC 识别
新技能生成后，CC 正常是要重启会话或者重新加载配置才能扫到新目录。我在实践中发现，同一个会话内直接说"现在加载我新生成的 dependency-updater"，它不一定能识别。
保险做法是退出当前会话、重新打开一个 CC 会话，然后/skills确认出现了dependency-updater，再手动测试一次触发。如果你用的是 cc switch 这样的代理切换工具，建议在刚启动会话时直接让请求走一次链路，确认代理转发的第一个请求就能成功命中模型，如果这里就报 404，后面所有技能交互都会带病运行。
4.4 单测技能：在无关紧要的任务里试调
新技能第一次运行，不要压太重的任务。我实测的流程是让技能干一件没有副作用的小事，比如"分析根目录下 README.md 的内容，按 dependency-updater 的格式输出建议"。
这一步能暴露很多问题：技能指令里引用的路径是否存在、模板里调用的辅助脚本是否有执行权限、输出格式是否符合预期。技能包本质上是"提示词+脚本+模板"的组合，任何一个环节断了，CC 的表现都会很拧巴。
单测通过后再扩到真实任务，一次一个技能，别贪多。同时装五个新技能，哪个没生效，排查成本直接乘以五。
5. 踩坑实录：cc switch 本地代理在 /responses 上的那些状态码
5.1 日志先行：一段典型的异常输出长什么样
安装 skill-creator 之后我踩的真正的坑，其实和技能包本身没关系，而是技能触发后 CC 调模型时走的链路。我当时的场景是：cc switch 接管了 CC 的 API 路由，把请求转发到 DeepSeek 的模型端点。首次触发技能时，直接收到一条类似这样的报错：
unexpected status 404 not found: cc switch local proxy failed while handling codex endpoint /responses.看到404，第一反应是技能文件路径不对，但我去翻了半天 skills 目录，根本没发现异常。后面冷静下来才想明白：这个报错里的关键词是/responses——这不是技能加载的请求，是 CC 调用模型的请求。cc switch 作为本地代理，接管了 CC 和模型供应商之间的转发，/responses是它暴露出来的本地端点。换句话说，问题不出在技能包，而出在代理转发规则上。
这是排障里最容易走弯路的地方：报错文本里出现了你正在折腾的对象（skills、skill-creator、CC），就下意识以为是它的问题，其实是下一层代理的问题。所以我后来强制自己记住一个原则——先看完整日志，再下结论。
5.2 401 Unauthorized：token 过期与 key 映射不一致
装完 skill-creator 过程中最先遇到的是 401。日志长这样：
unexpected status 401 unauthorized: cc switch local proxy failed while handling401 是认证失败，最常见的原因是 API key 没有传对。我遇到的具体场景是：cc switch 里配置了 DeepSeek 的 key，但config文件中模型映射的名字写的是deepseek-chat，而实际上该供应商的 API 端点期望的是deepseek-v4.x这种型号标识。key 本身没问题，但 proxy 在转发时把它当成一个不存在的模型配置来加载，结果认证上下文对不上，直接 401。
还有一次是官方账号的 token 过期了。cc switch 支持官方账号和第三方 key 两种模式混用，如果你在官方账号模式下，token 过期后没有重新登录，CC 请求会带着过期凭证发到代理，代理转而给模型供应商，自然 401。
5.3 404 Not Found：model mapping 没过审，端点路径被改写
404 是我遇到最频繁的。这个报错出现在试图触发技能之后，完整文本指向/responses，说明代理已经把请求转发到某个上游地址，但上游不存在这个路径。
规律基本是：cc switch 的模型映射表里配的模型名称和供应商 API 实际提供的模型名不一致。比如供应商平台上叫glm-4-long，配置里写的却是glm-4，那个 base URL 加上模型名拼出来的请求路径不存在，于是 404。
处理方式分两步。第一步，去供应商控制台确认当前可用模型名，特别注意版本后缀；第二步，打开 cc switch 的配置界面，把模型映射 name 改成和供应商完全一致的字符串，一个字符都不能差。改完保存，然后重启 cc switch 进程，光保存配置有时不会热更新代理的加载状态。
5.4 502/503：上游波动和限流，别急着改配置
和 401、404 不同，502、503 大多不是配置错误，是上游或者代理本身的问题。
502 Bad Gateway 通常是模型供应商服务端异常，或者本地代理到上游之间的连接超时。我会先做一个直连测试：绕过 cc switch，直接用 curl 带同样的 API key 打到供应商的 endpoint，如果能通，说明问题出在代理这边的超时配置太短或者连接池设置太小；如果 curl 也不通，那基本是供应商服务端的问题，等一会儿再试。
503 Service Unavailable 大概率是两个原因：一是 API 配额用完了，供应商端限流；二是 cc switch 本地代理没起来或者崩溃了，请求被一个不健康的服务拒绝。第二种情况很好排查，看端口还在不在：
lsof -i :<cc-switch端口>端口没了，就是代理进程掉了，重启即可。你甚至会在日志里看到类似cc switch local proxy failed while handling codex endpoint的完整信息，英文虽然长，但核心就是本地代理在处理/responses请求时失败了。
5.5 排查的推荐顺序：从日志到配置再到网络
被 401、404、502、503 轮番折磨之后，我总结了一套顺序，现在每次遇到状态码报错都按这个走：
- 先看 cc switch 的完整日志，找到报错状态码前一段请求的上下文，确定是"请求没发出"还是"上游拒绝了"。
- 对照配置，重点查 key、模型映射、base URL 三个字段。
- 直连测试，绕过代理直接向供应商发请求，定位是代理问题还是供应商问题。
- 确认本地端口和进程状态，排除代理本身挂掉的情况。
- 最后才考虑网络波动和限流，因为这两项不需要改配置，等一等或者换时间再试就行。
这五步走完，基本能覆盖 90% 的异常场景。最忌讳的是上来就改配置，你连错误在哪一层都不知道，改了也是瞎猜。
另外提一个容易被误判的现象：切换模型后原对话不停跳闪。这个通常不是状态码问题，而是你在一个长期会话里切换了模型，CC 端对话记录的上下文和新模型的流式响应格式不兼容，界面像抽风一样刷新。解决方法是退出当前会话，重新开一个，别指望在原会话里无缝换模型。
6. 把 skill-creator 和 cc switch 一起用：模型切换后的稳定性话题
6.1 cc switch 与官方账号会不会冲突
这个问题在社区里被问了无数次，我也实测过。cc switch 和官方账号不冲突，前提是你理解它们的分工：官方账号登录的是 CC 官方的认证体系，cc switch 做的只是给本地代理配置不同的上游供应商，它并没有修改官方账号的登录态。
你在 cc switch 里切到 DeepSeek，说明本地请求要发往 DeepSeek 的 API，这和你 CC 官方账号本身没冲突。反过来，你还想用官方模型，就把映射切回官方，重新走官方认证。每次切换后我建议做一件事：重启 CC 会话，让本地代理和 CC 客户端完全重新建立连接，避免残留旧模型的上下文。
但如果你的配置是"官方账号登录 + 第三方 key 同时存在"，注意看 cc switch 当前激活的是哪套配置，别在这上面搞混。最保险的办法是给不同供应商起不同配置名，比如official、deepseek、qwen、glm，切换时一眼就能看出当前走的是谁。
6.2 更新模型配置的正确姿势
模型供应商的模型名不是固定的，隔一两个月就会推新版本、下旧版本。skill-creator 生成技能时不涉及模型名，但你实际使用技能时，CC 发的请求会经过 cc switch，模型名对不对直接决定技能能不能跑起来。
每次模型供应商更新模型列表，记住三步：第一，在供应商控制台确认新模型名；第二，在 cc switch 配置里更新模型映射和 base URL；第三，重启 cc switch 进程，然后新建 CC 会话测试一次简单请求。
不要在旧会话里测。我踩过的坑是：更新完配置后在旧会话里直接继续，结果 CC 还是拿着缓存下来的旧路由信息发请求，又是 404。新建会话一切正常，浪费半小时。
6.3 我的最终配置建议
现在我的工作流是这样：skill-creator 固定装在当前机器，不跟模型绑定；CC 侧的模型路由完全交给 cc switch，每个供应商一套独立配置；每次安装新技能包之后，先在一个不重要的模型上触发一次，确认技能包本身没问题；再切到生产用的模型，验证一次真实任务。
这套流程看起来多跑一次验证，实际上省掉了大量返工。如果你也打算装 skill-creator，我建议照这个顺序走，尤其是"装完技能先跑一次模型链路健康测试"这步，能帮你把技能包的锅和模型路由的锅分开，不至于像我一样混在一起扯半天。
6.4 几个沉淀下来的使用习惯
最后说几个我在实际使用中沉淀下来的习惯。第一，技能包目录里永远不放.git，只放交付文件。第二，每次升级 skill-creator 之前备份skills目录。第三，遇到/responses报错，先想到 cc switch，别先想到技能包。第四，切换模型后如果对话跳闪，杀掉会话重开，不要恋战。
这些并不高深，但每一条都是被实际故障教育出来的。希望这篇对正在折腾 CC 和 skill-creator 的人有帮助，少走一段我走过的弯路。
