Skip to content
CC Switch WikiUnofficial Community Wiki

The Skill source directory has no SKILL.md; refusing to sync to avoid overwriting the target directory - CC Switch

Quick fix

CC Switch fails to install when the skill repository layout does not match the skillId or is nested — install by hand with npx skills add.

Symptom

Section titled “Symptom”
Error output
Skill 源目录缺少 SKILL.md，拒绝同步以避免覆盖目标目录: /home/fengyu/.cc-switch/skills/ast-grep
English translation

The Skill source directory has no SKILL.md; refusing to sync to avoid overwriting the target directory: /home/fengyu/.cc-switch/skills/ast-grep

Cause

Section titled “Cause”

When installing a skill, the CC Switch `resolve_skill_source_dir` logic only tries the direct relative path, a recursive match on directory basename, and a `SKILL.md` in the repository root. When the real GitHub repository layout is deeply nested (the `ast-grep` skill living under `ast-grep/skills/ast-grep/`, for example), or the `skillId` differs from the actual directory name (`weread-skills` living in a `skills/` directory) with `SKILL.md` not at the root, none of the three branches finds the real skill directory, so it reports the missing `SKILL.md` and refuses to sync. CC Switch has fixed some nested scanning problems before, but the blind spot in source directory resolution at install time persists from 3.13.0 through 3.19.2.

Fix

Section titled “Fix”

  1. Bypass the CC Switch GUI and install the skill with the official CLI command in a terminal (run `npx skills add ast-grep/agent-skill`, for example).

  2. Confirm the skill produced the right symlink or files locally (a `SKILL.md` under `~/.agents/skills/`, for instance), after which CC Switch recognises and manages it normally.

  3. Try upgrading CC Switch to the latest version for fixes to some known nested directory layouts.

Affected Versions

Section titled “Affected Versions”
ToolClaude Code
Version3.13.0 - 3.19.2 (受影响版本范围)
PlatformsLinuxWindowsmacOS

Source Issues

Section titled “Source Issues”

This page is distilled from 3 real issues

FAQ

Section titled “FAQ”
Why does `npx skills add` from the official documentation install successfully while clicking install in CC Switch fails?
Because the CC Switch `resolve_skill_source_dir` logic has a blind spot when the `skillId` differs from the directory name or the layout is deeply nested, so it cannot find `SKILL.md`. The official CLI resolution handles those complex repository layouts correctly.
After installing by hand from the command line, can CC Switch still manage the skill?
Yes. As long as `npx skills add` produced the correct directory or symlink containing `SKILL.md` locally, CC Switch recognises it normally.
Section titled “Related problems”
skills installed to the wrong path - cc-switchOlder cc-switch installs skills into ~/.claude/skills/skills, which Claude Code ignores. Upgrade, or move the contents up to ~/.claude/skills/.4 issues mergedcc-switch crashes immediately after openingNo confirmed fix. Reinstalling does not help. Collect debug logs and wait for an official fix.1 issues mergedcc-switch Skills import / sync problems (broken, not detected, directory out of sync)Usually a changed Skills directory layout, or the DB drifting from the file system. Manage through the cc-switch UI and check nested directory support.18 issues merged

This is an unofficial community wiki with no affiliation to the cc-switch authors or the project itself. Its content is compiled from the project's public GitHub issues. This site distributes no software.