cc-switch Skills 导入/同步异常（失效、无法识别、目录不同步）
Quick fix
多数问题源于 Skills 目录结构变化或 DB 与文件系统不同步；优先使用 cc-switch UI 管理、升级版本并检查嵌套/插件目录支持。
Symptom
Section titled “Symptom”Skill 源目录缺少 SKILL.md，拒绝同步以避免覆盖目标目录: /home/fengyu/.cc-switch/skills/ast-grep该集群包含多种 Skills 相关问题：1) 切换 API 供应商后插件/Skills 失效，因配置未通过通用配置传递；2) 手动删除 .cc-switch/skills 文件后 UI 仍显示，因界面读取 SQLite 数据库而非直接扫描目录；3) ZIP/.skill 导入失败或无法识别，涉及临时目录名含点、嵌套结构不支持、.skill 后缀过滤等；4) Claude Code 新版插件目录 ~/.claude/plugins/marketplaces/ 未被扫描；5) 同步状态 DB 标记 enabled 但软链未创建，幂等检查导致不会自愈；6) 云同步 skills.zip 条目数超过 10000 限制。这些问题部分已在 v3.12.3 等版本修复，部分仍开放或归并到其他主 issue。
切换 API 供应商后 Skills/Agents 失效时，使用 cc-switch 的“通用配置”功能在供应商之间传递非供应商数据。
不要手动删除 ~/.cc-switch/skills 或 %USERPROFILE%\.cc-switch\skills 下的文件来卸载 Skill；通过 cc-switch UI 删除，以同步清理 SQLite 数据库记录。
ZIP 导入 Skill 无法识别时，升级到 v3.12.3 或更新版本；该版本修复了 ZIP 导入中 .skill 后缀支持和目录名包含 . 导致识别失败的问题。
如果 Skill 来自多 skill 仓库或嵌套目录（例如 skills/<repo>/skills/*/SKILL.md），当前部分版本只能识别一级目录下直接包含 SKILL.md 的结构；临时方案是将每个 skill 平铺到 ~/.cc-switch/skills/ 下。
Claude Code 新版插件目录 ~/.claude/plugins/marketplaces/ 下的 Skills 无法被扫描时，需要等待 cc-switch 适配该目录；当前扫描路径仍为 ~/.claude/skills/。
如果 DB 中 enabled_claude=1 或 enabled_codex=1 但对应软链不存在，手动补建软链或重新禁用/启用该 Skill；该问题目前可能不会自动修复。
云同步报错 skills.zip 条目数过多（超过 10000）时，减少备份的 Skills 文件数量，或等待官方调整/移除 10000 条目限制。
Affected Versions
Section titled “Affected Versions”Source Issues
Section titled “Source Issues”本页汇总自 18 个真实 issue
- #1000[BUG] codex 无法识别从 cc-switch 中通过“从 ZIP 安装”导入的skills
- #1240Skills ZIP 安装支持 .skill 后缀?
- #1702[BUG]Skills 安装后遗漏共享辅助目录，导致 bundle 型 skill 运行时报缺依赖
- #1794CCSwitch 无法完全控制 OpenCode 的 skills
- #1842v3.12.3 回归：导入已有无法发现本地嵌套 skills，而 v3.12.2 可以
- #2139Bug: Skills Import Count Multiplied When Button Clicked Multiple Times
- #2238切换 API 供应商后，在plugins中安装的Skills/Agents 失效，复制导入的skills有效
- #2569「WebDAV 云同步」无法正常使用
- #3070Codex skill 同步时会把普通用户 skill 放到 .codex/skills/.system 下
- #3498本地多 skill 仓库目录无法识别：skills/<repo>/skills/*/SKILL.md
- #3564[Bug] Skill 同步:DB 标记 enabled=1 但软链未创建,幂等跳过导致永不自愈;重命名 skill 残留旧 name
- #3623windows下，个性化设置中的skills同步方式选择软连接的时候，没有生效，还是普通文件
- #4024手动删除 .cc-switch/skills中的skill，cc-switch 上面还显示
- #4141ast-grep skill 无法安装
- #4266fix(skill): 恢复备份时应还原原有的应用启用状态
- #5499I don't want CC Switch to change my existing Skills location
- #5579[Bug] Skills 扫描失败：未适配 Claude Code 新版插件目录结构
- #5690导入已有Skill时，同时安装于Claude Code和Codex的Skill只被记录一个来源，另一个显示未安装
- 手动删除 .cc-switch/skills 里的文件后，为什么 cc-switch 还显示这个 Skill？
- cc-switch 界面根据 SQLite 数据库记录加载 Skill，不是直接扫描 .cc-switch/skills 目录。请通过 cc-switch UI 删除 Skill，这样文件和数据库记录都会清理。
- 切换 API 供应商后 plugins/skills 消失了怎么办？
- 非供应商数据之外的配置项需要通过 cc-switch 的“通用配置”功能在供应商之间传递。部分场景已被归并为已知问题，请关注相关主 issue。
- 为什么本地多 skill 仓库目录无法被“导入已有”识别？
- 部分版本只识别一级目录下直接包含 SKILL.md 的结构，例如 ~/.cc-switch/skills/<skill-name>/SKILL.md。嵌套结构如 skills/<repo>/skills/*/SKILL.md 可能无法识别，需要平铺或等待修复。
- Claude Code 新版插件目录里的 Skills 为什么扫描不到？
- Claude Code 的 Skills 存储目录已从 ~/.claude/skills/ 变更为 ~/.claude/plugins/marketplaces/，但 cc-switch 的扫描逻辑尚未完全适配新目录。
- 云同步提示 skills.zip 条目数过多（14359），上限 10000，怎么处理？
- 当前恢复备份时会限制 skills.zip 文件数不超过 10000。临时只能减少 Skill 文件数量，或等待官方调整限制。
- 我不想让 cc-switch 修改已有 Skills 位置，该怎么做？
- 有用户建议不要点击 cc-switch 中的导入 Skills 功能；但具体 UI 选项可能因版本而异。
这是一个非官方社区 wiki，与 cc-switch 作者及项目本身无隶属关系。内容整理自项目公开的 GitHub issues。本站不分发任何软件。