Skip to content
CC Switch WikiUnofficial Community Wiki

cc-switch Skills import / sync problems (broken, not detected, directory out of sync)

Quick fix

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.

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”

This cluster holds several Skills problems: 1) plugins and Skills break after switching API provider, because the config was not carried across via general config; 2) the UI still lists a Skill after you delete files under .cc-switch/skills by hand, because it reads the SQLite database rather than scanning the directory; 3) ZIP/.skill imports fail or are not recognised, involving temp directory names containing a dot, unsupported nesting, and .skill suffix filtering; 4) the newer Claude Code plugin directory ~/.claude/plugins/marketplaces/ is not scanned; 5) the DB marks a sync as enabled but the symlink was never created, and an idempotence check means it never self-heals; 6) the skills.zip cloud sync entry count exceeds the 10000 limit. Some are fixed in v3.12.3 and similar releases; others remain open or were folded into other tracking issues.

Fix

Section titled “Fix”

  1. When Skills/Agents break after switching API provider, use cc-switch 通用配置 (general config) to carry non-provider data across providers.

  2. Do not uninstall a Skill by deleting files under ~/.cc-switch/skills or %USERPROFILE%\.cc-switch\skills by hand. Delete through the cc-switch UI so the SQLite records are cleaned up too.

  3. When a ZIP Skill import is not recognised, upgrade to v3.12.3 or newer. That version fixed .skill suffix support in ZIP import and detection failing on directory names containing a dot.

  4. If the Skill comes from a multi-skill repository or a nested directory (skills/<repo>/skills/*/SKILL.md, for example), some versions only detect a SKILL.md directly inside a first-level directory. The stopgap is to flatten each skill into ~/.cc-switch/skills/.

  5. When Skills under the newer Claude Code plugin directory ~/.claude/plugins/marketplaces/ are not scanned, you have to wait for cc-switch to support that directory; the scan path is still ~/.claude/skills/.

  6. If the DB has enabled_claude=1 or enabled_codex=1 but the matching symlink does not exist, create the symlink by hand or disable and re-enable the Skill. This currently does not repair itself.

  7. When cloud sync reports too many skills.zip entries (over 10000), reduce the number of Skills files you back up, or wait for the 10000-entry limit to be adjusted or removed.

Affected Versions

Section titled “Affected Versions”
ToolClaude Code / Codex
Version3.12.2 - 3.16.2
PlatformsWindowsmacOSLinux

Source Issues

Section titled “Source Issues”

This page is distilled from 18 real issues

FAQ

Section titled “FAQ”
I deleted the files under .cc-switch/skills by hand — why does cc-switch still show the Skill?
The cc-switch UI loads Skills from its SQLite records rather than scanning the .cc-switch/skills directory. Delete the Skill through the cc-switch UI so both the files and the database records are cleaned up.
My plugins/skills disappeared after switching API provider. What now?
Config beyond the provider data itself has to be carried across providers with the cc-switch 通用配置 (general config) feature. Some cases were folded into a known issue — watch the relevant tracking issue.
Why is my local multi-skill repository directory not recognised by import-existing?
Some versions only recognise a SKILL.md directly inside a first-level directory, such as ~/.cc-switch/skills/<skill-name>/SKILL.md. A nested layout like skills/<repo>/skills/*/SKILL.md may not be recognised — flatten it, or wait for a fix.
Why are Skills in the newer Claude Code plugin directory not found?
Claude Code moved its Skills storage from ~/.claude/skills/ to ~/.claude/plugins/marketplaces/, and the cc-switch scan logic has not fully caught up with the new directory.
Cloud sync says skills.zip has too many entries (14359) against a 10000 limit. What now?
Restoring a backup currently caps skills.zip at 10000 files. For now, reduce the number of Skill files, or wait for the limit to be adjusted.
I do not want cc-switch moving my existing Skills. How?
Users suggest not clicking the import Skills feature in cc-switch, though the exact UI options vary by version.
Section titled “Related problems”
Test script: error, no result returnedMiniMax changed the balance query API response shape, breaking the old parser. Upgrade cc-switch to v3.16.2+, or use a custom template for now.5 issues mergedcc-switch crashes immediately after openingNo confirmed fix. Reinstalling does not help. Collect debug logs and wait for an official fix.1 issues mergedThe Skill source directory has no SKILL.md; refusing to sync to avoid overwriting the target directoryCC Switch fails to install when the skill repository layout does not match the skillId or is nested — install by hand with `npx skills add`.3 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.