Skip to content
CC Switch WikiUnofficial Community Wiki

cc-switch Skills Import/Sync Issues (Invalid, Unrecognized, Out of Sync)

Quick fix

Most issues stem from Skills directory changes or a DB/filesystem mismatch. Manage Skills through the cc-switch UI, upgrade, and check nested and plugin…

Symptom

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

The Skill source directory is missing SKILL.md; sync was refused to avoid overwriting the target directory: /home/fengyu/.cc-switch/skills/ast-grep

Cause

Section titled “Cause”

This cluster includes several Skills-related issues: (1) plugins/Skills stop working after switching API providers because the configuration is not passed through general configuration; (2) after manually deleting files from .cc-switch/skills, the UI still shows them because it reads the SQLite database rather than scanning the directory; (3) ZIP/.skill imports fail or are not recognized due to periods in temporary directory names, unsupported nested structures, or .skill suffix filtering; (4) the newer Claude Code plugin directory ~/.claude/plugins/marketplaces/ is not scanned; (5) the DB marks sync status as enabled but the symlink is not created, and an idempotency check prevents self-repair; (6) cloud sync skills.zip entries exceed the 10000 limit. Some of these issues were fixed in versions such as v3.12.3, while others remain open or have been merged into other main issues.

Fix

Section titled “Fix”

  1. If Skills/Agents stop working after switching API providers, use cc-switch's “General Configuration” feature to pass non-provider data between providers.

  2. Do not manually delete files under ~/.cc-switch/skills or %USERPROFILE%\.cc-switch\skills to uninstall a Skill; delete it through the cc-switch UI so its SQLite database record is also removed.

  3. If a ZIP import does not recognize a Skill, upgrade to v3.12.3 or later; this version fixed support for the .skill suffix and failures to recognize directory names containing . during ZIP import.

  4. If a Skill comes from a multi-skill repository or nested directory (for example, skills/<repo>/skills/*/SKILL.md), some versions can recognize only structures with SKILL.md directly inside a first-level directory. As a workaround, place each skill directly under ~/.cc-switch/skills/.

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

  6. If enabled_claude=1 or enabled_codex=1 in the DB but the corresponding symlink is missing, create the symlink manually or disable and re-enable the Skill; this issue may not currently self-repair.

  7. If cloud sync reports too many skills.zip entries (more than 10000), reduce the number of Skills files in the backup or wait for the official 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 11 real issues

FAQ

Section titled “FAQ”
Why does cc-switch still show a Skill after I manually delete its files from .cc-switch/skills?
The cc-switch UI loads Skills from SQLite database records; it does not scan the .cc-switch/skills directory directly. Delete the Skill through the cc-switch UI to remove both the files and the database record.
What should I do if plugins/skills disappear after switching API providers?
Configuration items that are not provider-specific need to be passed between providers using cc-switch's “General Configuration” feature. Some cases have been merged into known issues; follow the related main issue.
Why can't “Import Existing” recognize a local multi-skill repository directory?
Some versions recognize only structures with SKILL.md directly inside a first-level directory, such as ~/.cc-switch/skills/<skill-name>/SKILL.md. Nested structures such as skills/<repo>/skills/*/SKILL.md may not be recognized; flatten the directory structure or wait for a fix.
Why aren't Skills in the newer Claude Code plugin directory being scanned?
Claude Code's Skills storage directory changed from ~/.claude/skills/ to ~/.claude/plugins/marketplaces/, but cc-switch's scanning logic does not yet fully support the new directory.
Cloud sync says there are too many skills.zip entries (14359), with a limit of 10000. What should I do?
Restoring a backup currently limits skills.zip to no more than 10000 files. For now, reduce the number of Skill files or wait for the official limit to be adjusted.
How can I prevent cc-switch from modifying the location of existing Skills?
A user suggested not clicking the Import Skills feature in cc-switch, but the specific UI options may vary by version.
Section titled “Related problems”
No MCP servers configured. Claude CodeEnable MCP servers one at a time to find the unusable configuration, then disable or remove it and reload Claude Code.20 issues mergedCrash on Launch: CC Switch Windows Startup CrashReproduce on the latest version and provide the CC Switch, Windows, and WebView2 versions, along with the latest logs and Event Viewer error details.1 issues merged[DISCUSS] Support for pi coding agentThis is a feature request merged into tracking issue #1855; the original post provides no verifiable solution.1 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.