Skill 源目录缺少 SKILL.md，拒绝同步以避免覆盖目标目录 - CC Switch

Quick fix

当技能仓库目录结构与 skillId 不匹配或存在嵌套时 CC Switch 会安装失败，可改用 npx skills add 命令行手动安装。

Symptom

报错原文复制

Skill 源目录缺少 SKILL.md，拒绝同步以避免覆盖目标目录: /home/fengyu/.cc-switch/skills/ast-grep

Cause

CC Switch 在安装技能时，其 `resolve_skill_source_dir` 逻辑仅尝试直接相对路径、递归匹配目录 basename 以及仓库根目录的 `SKILL.md`。当 GitHub 仓库的实际目录结构存在深层嵌套（例如 `ast-grep` 技能位于 `ast-grep/skills/ast-grep/` 下），或者 `skillId` 与实际目录名不同（如 `weread-skills` 位于 `skills/` 目录）且 `SKILL.md` 不在根目录时，CC Switch 的三个分支均无法命中真实技能目录，从而触发缺少 `SKILL.md` 的报错并拒绝同步。虽然 CC Switch 曾修复过部分嵌套扫描问题，但安装阶段的源目录解析盲区在 3.13.0 至 3.19.2 版本中依然存在。

Fix

1. 1

   绕过 CC Switch 的图形界面，直接在终端中使用官方 CLI 命令安装技能（例如执行 `npx skills add ast-grep/agent-skill`）。

2. 2

   确认技能已在本地正确生成软链接或文件（如 `~/.agents/skills/` 目录下存在 `SKILL.md`），此后 CC Switch 即可正常识别并管理该技能。

3. 3

   尝试升级 CC Switch 至最新版本，以获取对部分已知嵌套目录结构解析的修复。

Affected Versions

ToolClaude Code

Version3.13.0 - 3.19.2 (受影响版本范围)

PlatformsLinuxWindowsmacOS

Source Issues

本页汇总自 3 个真实 issue

• #2078无法安装技能
• #4141ast-grep skill 无法安装
• #6365[Bug] skills.sh 的 skillId 与仓库目录名不同时无法安装（weread-skills）

FAQ

为什么按照官方文档使用 `npx skills add` 可以成功安装，但在 CC Switch 中点击安装却失败？

因为 CC Switch 的 `resolve_skill_source_dir` 逻辑在处理 `skillId` 与目录名不一致或深层嵌套时存在盲区，导致找不到 `SKILL.md`。而官方 CLI 工具的解析逻辑可以正确处理这些复杂的仓库结构。

使用命令行手动安装后，CC Switch 还能正常管理这个技能吗？

可以。只要 `npx skills add` 成功在本地生成了包含 `SKILL.md` 的正确目录或软链接，CC Switch 就能正常识别它。

相关问题

skills 安装路径不对 cc-switch旧版 cc-switch 会把 skills 装到 ~/.claude/skills/skills，Claude Code 不识别；升级到修复版本，或临时把内容上移到 ~/.claude/skills/。4 issues merged打开后就闪退 cc-switch目前没有已确认修复：卸载重装也无效，先收集 debug 日志并保留现场，等待官方修复。1 issues mergedcc-switch Skills 导入/同步异常（失效、无法识别、目录不同步）多数问题源于 Skills 目录结构变化或 DB 与文件系统不同步；优先使用 cc-switch UI 管理、升级版本并检查嵌套/插件目录支持。18 issues merged