最近在给 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 urwx ~/.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 Unauthorizedtoken 过期与 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 Foundmodel 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 的人有帮助少走一段我走过的弯路。