SkillBridge

Sync your CC Switch skills into every AI coding tool — live links, zero copies.

English · 中文

---

SkillBridge mirrors the skills in CC Switch (~/.cc-switch/skills) into 23 AI coding tools — Claude Code, Cursor, Gemini CLI, Cline, Kilo Code, ZCode, WorkBuddy, Comate, Hermes Agent, TRAE, Cherry Studio, CodeBuddy, AutoClaw, Verdent, Qoder, Doubao, MiniMax, Qwen Office, Grok Bot, Codex, OpenCode and more — using directory junctions (Windows) / symlinks (Unix) instead of copies. Skills stay live: edits and removals in CC Switch propagate instantly, and new skills are auto-linked at logon (at boot on Linux).

Why SkillBridge?

Every AI coding tool maintains its own skills/ directory. Copying skills around by hand is slow, drifts out of sync, and breaks the moment a tool is reinstalled. SkillBridge makes CC Switch the single source of truth and every other tool a live consumer of it:

• Edits / removals propagate instantly — a junction is a live reference, not a stale copy.
• New skills are linked automatically at logon — at boot on Linux (Windows scheduled task / launchd / cron).
• Dead links are pruned — when a skill is deleted, the links it left behind are cleaned up instead of accumulating.
• The CC Switch database stays in step — check-db-sync.py registers skills the database never picked up, so they also reach Codex and appear in the CC Switch UI.
• Idempotent & safe — existing entries are never overwritten; a tool's own skills are never touched.
• Portable — every path uses environment variables (%USERPROFILE%, %APPDATA%, %HERMES_HOME%), so it runs on any machine as-is.

Features

• Live sync via junctions / symlinks — no periodic re-copying
• Config-driven targets (config.json) — add or drop a tool in one line
• Auto-detection (detect-tools.ps1 / detect-tools.sh) — adapts to whatever is installed on a machine
• Auto-link at logon / boot (install-autolink.ps1 / .sh) with optional interval
• Cross-platform: PowerShell (Windows) and Bash (macOS / Linux)
• Pure scripts, no daemon; Windows needs nothing extra, macOS / Linux need python3 (for config parsing)

Quick Start (Windows)

Daily use: double-click 同步CCSwitch技能.bat — it links every CC Switch skill into all configured tools immediately.

One-time setup:

# 1. Generate config.json for THIS machine — required on first run (it is not committed)
powershell -NoProfile -ExecutionPolicy Bypass -File .\detect-tools.ps1

# 2. Sync once
powershell -NoProfile -ExecutionPolicy Bypass -File .\sync-skills.ps1

# 3. Optional: auto-link new skills at logon (-IntervalMinutes 30 for periodic)
powershell -NoProfile -ExecutionPolicy Bypass -File .\install-autolink.ps1

macOS / Linux:

chmod +x sync-skills.sh install-autolink.sh detect-tools.sh
./detect-tools.sh         # generate config.json for this machine (or copy config.example.json)
./sync-skills.sh          # sync once
./install-autolink.sh     # register auto-link (macOS: at login / Linux: at boot)

Installation on a New Machine

1. Clone or copy the repository.
2. If you use Hermes Agent, set the HERMES_HOME environment variable to its data directory (containing a skills folder).
3. Auto-detect installed tools and generate a matching config.json:

   powershell -NoProfile -ExecutionPolicy Bypass -File .\detect-tools.ps1

   On macOS / Linux: ./detect-tools.sh. Use -All / --all to include every supported tool regardless of detection.
4. Double-click 同步CCSwitch技能.bat (or run sync-skills.ps1).
5. Optional: install-autolink.ps1 for automatic sync at logon.

Configuration (config.json)

config.json is machine-specific and not committed (gitignored). Generate it with detect-tools.ps1 / detect-tools.sh, or copy config.example.json → config.json and edit. The committed template is config.example.json; the tool list is defined in supported-tools.json.

{
  "link_type": "junction",
  "source": "%USERPROFILE%\\.cc-switch\\skills",
  "targets": {
    "Claude Code": "%USERPROFILE%\\.claude\\skills",
    "Cursor":         { "path": "%USERPROFILE%\\.cursor\\skills", "mode": "copy" },
    "ZCode":          "%USERPROFILE%\\.zcode\\skills",
    "WorkBuddy":      "%USERPROFILE%\\.workbuddy\\skills",
    "Comate":         "%USERPROFILE%\\.comate\\skills",
    "Hermes Agent":   "%HERMES_HOME%\\skills",
    "TRAE Work CN":   "%USERPROFILE%\\.trae-cn\\skills",
    "Cherry Studio":  "%APPDATA%\\CherryStudio\\Data\\Skills"
  },
  "autolink": {
    "enabled": true,
    "at_logon": true,
    "interval_minutes": 0
  }
}

• source — the CC Switch skills library (%USERPROFILE%\.cc-switch\skills on Windows, $HOME/.cc-switch/skills on Unix).
• targets — a name → skills directory map. A value can be a path string (link) or { "path": "...", "mode": "copy" } for tools that cannot follow junctions (Cursor). A leftover "Cursor": "path" string, or any path ending in /.cursor/skills, is promoted to copy mode. %USERPROFILE%, %APPDATA%, %HERMES_HOME% (Windows) and $HOME (Unix) are expanded automatically. Relative paths like .cursor/skills are resolved from the current directory. detect-tools keeps extra targets you added that are not in the catalog.
• link_type — junction (Windows, no admin required) or symlink (Unix). Used only for mode: link targets.

See 支持的软件列表.md for the full list of supported tools and their default paths. The catalog file supported-tools.json is the source of truth used by both detect-tools scripts.

How It Works

┌────────────────────┐        junction/symlink         ┌─────────────────┐
│  CC Switch skills  │  ───────────────────────────▶  │ ZCode skills/   │
│  ~/.cc-switch/skills│  one live reference per tool    ├─────────────────┤
│  (single source)   │                                 │ WorkBuddy skills/│
└────────┬───────────┘                                 ├─────────────────┤
         │ ① edits/removals propagate instantly         │ Comate skills/  │
         │ ② new skills need one new link               └─────────────────┘
         └──▶ sync-skills script + task/launchd (auto-link at logon / boot)

1. Junction / Symlink — <tool>/skills/<name> → ~/.cc-switch/skills/<name>. A reference, not a copy: edit once, every tool reads the new version.
2. Sync script — scans the source, creates a link in every configured target for each skill that is missing; skips anything that already exists. Links left behind by deleted skills are pruned (reported as pruned= in the summary).
3. Database alignment — check-db-sync.py runs at the end of every sync and reconciles CC Switch's own skill database (~/.cc-switch/cc-switch.db) with the skills folder. CC Switch never rescans the filesystem, so a skill copied in by hand or generated locally is never registered on its own. Disable with "check_db": false in config.json.
4. Auto-trigger — Windows Scheduled Task (install-autolink.ps1) or launchd/cron (install-autolink.sh).

Repository Layout

SkillBridge/
├── 同步CCSwitch技能.bat    # double-click to sync (daily driver)
├── detect-tools.ps1        # auto-detect installed tools -> generate config.json (Windows)
├── detect-tools.sh         # same on macOS / Linux
├── sync-skills.ps1         # Windows sync script (junctions)
├── sync-skills.sh          # Unix sync script (symlinks)
├── check-db-sync.py        # reconcile CC Switch's skill DB (called by sync)
├── install-autolink.ps1    # Windows: register scheduled task
├── install-autolink.sh     # Unix: register launchd / crontab
├── supported-tools.json    # catalog of supported tools (source of truth)
├── config.json             # generated per machine (run detect-tools); gitignored
├── config.example.json     # portable env-var based example (all targets)
├── 支持的软件列表.md         # supported tools & paths (中文)
├── tests/                  # smoke tests + catalog / DB-alignment checks
├── .github/workflows/      # CI
├── README.md / README.zh-CN.md
└── LICENSE                 # MIT

FAQ

Why links instead of copies? Links are live: change a skill in CC Switch and every tool reads the new version on next open. Copies require periodic re-runs and drift. The one downside (a new skill needs a new link) is handled automatically by the scheduled task.

A tool doesn't see the new skills? Tools re-scan their skills directory on session/UI restart — restart the tool.

A tool doesn't follow junctions / symlinks? Remove it from targets, or switch to a copy strategy (replace New-Item -ItemType Junction with Copy-Item -Recurse).

Does SkillBridge support Cursor? Yes. The user-level target is ~/.cursor/skills, and it uses copy mode (real directories, not junctions). Cursor does not follow symlinks when discovering skills or when uploading them via Sync Skills for Cloud Agents, so a live link would be invisible in Cloud Agents.

Cloud Agents still run on a separate VM and cannot see your laptop. After SkillBridge copies skills into ~/.cursor/skills:

1. Reliable (recommended for cursor.com / Grok Bot): materialize skills into the project repo Cloud Agents check out, then commit and push:

# Double-click 同步到仓库给云端用.bat and paste the project path, or:
powershell -NoProfile -ExecutionPolicy Bypass -File .\sync-skills.ps1 -CopyInto D:\path\to\your-repo\.cursor\skills

./sync-skills.sh --copy-into /path/to/your-repo/.cursor/skills

Then git add .cursor/skills && git commit && git push, and start a new Cloud Agent on that commit.

2. Optional / flaky: turn on Cursor Settings → Agents → Sync Skills for Cloud Agents. Even when the toggle is on, agents started from the website or Grok Bot often still have an empty ~/.cursor/skills on the VM. Prefer the desktop Agents Window if you rely on this path.

Do not dump personal skills into the SkillBridge tool repo itself unless you are only testing — put them in the repo you actually work on.

Cursor additionally loads ~/.claude/skills, ~/.codex/skills and ~/.agents/skills for compatibility, so if those tools are in targets too, the same skill may show up more than once locally — drop the extras you don't want.

Stale links left behind after deleting a CC Switch skill? They are pruned automatically (reported as pruned= in the summary). Link-mode targets only remove a reparse point / symlink whose recorded target is gone. Copy-mode targets only remove a directory that has a .skillbridge-copy marker (or a leftover link into the CC Switch source). A tool's own skills stay safe even if they were listed in .skillbridge-managed.json.

The script reports pruned=0 but the folder clearly has broken links? Check that the folder is listed in targets. Also note that Test-Path does not resolve a junction's target — it returns True even for a dead one. The script compares the link's recorded Target path instead.

Contributing

Contributions are welcome! See CONTRIBUTING.md.

License

MIT © SkillBridge contributors