Skip to content
Back to search

sync-skill

One-click synchronization tool for **AI Agent Skills** (`SKILL.md`) across coding agents and IDEs.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/william-garden--sync-skill/badge.svg)](/listings/william-garden--sync-skill)

HTML

<a href="/listings/william-garden--sync-skill"><img src="/api/listings/william-garden--sync-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 132 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # sync-skill
  2. [中文](https://github.com/william-garden/sync-skill/blob/main/docs/zh.md)
  3. One-click synchronization tool for **AI Skills** (`SKILL.md`) across coding agents and IDEs.
  4. ## 1. Overview
  5. `sync-skill` copies your Agent Skills from one AI tool into another. Agent Skills use the open **`SKILL.md` format** — a skill is just a folder containing a `SKILL.md` file (YAML frontmatter plus Markdown instructions) and optional scripts/assets. Because every supported platform reads the *same* format, syncing is simply a matter of copying skill folders from one platform's skills directory into another's. No format conversion is needed.
  6. Each platform stores skills in a different directory, so `sync-skill` knows where every tool looks and moves your skills there safely — asking for confirmation before it replaces anything that already exists on the target, and never deleting skills that only exist there.
  7. ## 2. Technical Specifications
  8. - **Runtime:** Node.js >= 18 (pure ESM, no build step).
  9. - **Distribution:** run via `npx sync-skill` (no global install required).
  10. - **Dependency:** [`@inquirer/prompts`](https://www.npmjs.com/package/@inquirer/prompts) for the interactive wizard. Everything else uses Node built-ins.
  11. - **Tests:** `npm test` (Node's built-in `node --test`).
  12. - **OS support:** Linux, macOS, and Windows.
  13. ## 3. Usage
  14. ### Direct mode (copies all skills)
  15. ```bash
  16. npx -y sync-skill <source> <target> [--scope global|project]
  17. ```
  18. Examples:
  19. ```bash
  20. # Sync all global skills from Claude Code into Cursor
  21. npx -y sync-skill claude cursor
  22. # Sync project-level skills from Claude Code into Codex (./.claude/skills -> ./.agents/skills)
  23. npx -y sync-skill claude codex --scope project
  24. ```
  25. ### Interactive mode (pick individual skills)
  26. ```bash
  27. npx -y sync-skill
  28. ```
  29. The wizard walks you through: **scope → source platform → target platform → checkbox selection of skills** to copy.
  30. - `--scope global` (default): personal skills under your home directory.
  31. - `--scope project`: workspace skills under the current directory.
  32. ## 4. Platform Matching Keywords
  33. You can pass any of these keywords as the `<source>` / `<target>`:
  34. | Platform | Keywords |
  35. | :--- | :--- |
  36. | Claude Code | `claude`, `claude-code`, `claude code`, `anthropic` |
  37. | Codex | `codex`, `openai`, `codex cli` |
  38. | Cursor | `cursor`, `cursor ide` |
  39. | Gemini CLI | `gemini`, `gemini cli`, `google`, `gcloud` |
  40. | GitHub Copilot CLI | `copilot`, `copilot cli`, `github`, `gh` |
  41. | Visual Studio Code | `vscode`, `vs code`, `vs-code`, `code` |
  42. | OpenCode | `opencode`, `open code`, `anomaly` |
  43. ## 5. Supported Platforms and Skill Directories
  44. | Platform | Global (Linux / macOS) | Global (Windows) | Project | Documentation |
  45. | :--- | :--- | :--- | :--- | :--- |
  46. | Claude Code | `~/.claude/skills/` | `%USERPROFILE%\.claude\skills\` | `.claude/skills/` | [Claude Code skills](https://code.claude.com/docs/en/skills) |
  47. | Codex | `~/.codex/skills/` | `%USERPROFILE%\.codex\skills\` | `.agents/skills/` | [Codex skills](https://developers.openai.com/codex/skills) |
  48. | Cursor | `~/.cursor/skills/` | `%USERPROFILE%\.cursor\skills\` | `.cursor/skills/` | [Cursor skills](https://cursor.com/docs/skills) |
  49. | Gemini CLI | `~/.gemini/skills/` | `%USERPROFILE%\.gemini\skills\` | `.gemini/skills/` | [Gemini CLI skills](https://geminicli.com/docs/cli/skills/) |
  50. | GitHub Copilot CLI | `~/.copilot/skills/` | `%USERPROFILE%\.copilot\skills\` | `.github/skills/` | [Copilot CLI skills](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills) |
  51. | Visual Studio Code | `~/.copilot/skills/` | `%USERPROFILE%\.copilot\skills\` | `.github/skills/` | [VS Code agent skills](https://code.visualstudio.com/docs/agent-customization/agent-skills) |
  52. | OpenCode | `~/.config/opencode/skills/` | `%LOCALAPPDATA%\opencode\skills\` | `.opencode/skills/` | [OpenCode skills](https://opencode.ai/docs/skills/) |
  53. Notes:
  54. - **VS Code and GitHub Copilot CLI share `~/.copilot/skills/`.** Syncing between them under the global scope is reported as a no-op.
  55. - Many tools additionally read the cross-tool locations `~/.agents/skills/` (personal) and `.agents/skills/` (project), as well as `~/.claude/skills/`. `sync-skill` targets each platform's primary native directory shown above.
  56. ## 6. Core Features
  57. - **Two modes:** direct CLI (copy all) and interactive (select individual skills).
  58. - **Two scopes:** `global` (personal) and `project` (workspace).
  59. - **Non-destructive merge:** skills that exist only on the target are left untouched.
  60. - **Overwrite confirmation:** if a skill of the same name already exists on the target, `sync-skill` shows the source vs. target `version` (when declared) and asks before replacing it.
  61. - **Model-field awareness:** reports skills whose frontmatter is bound to a specific model (see below).
  62. ## 7. Model-Related Fields and Manual Adjustment
  63. A skill's `SKILL.md` frontmatter has **universal fields** (`name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`) that are portable across every platform, and **Claude Code-specific extensions** that other tools ignore.
  64. Among the extensions, two are bound to a specific **model**:
  65. - **`model`** — the model the skill runs on (`sonnet` / `opus` / `haiku`, a full model id, or `inherit`).
  66. - **`effort`** — the reasoning effort level.
  67. These values belong to Anthropic's model family. When a skill is synced to Gemini, Codex, Cursor, etc., spec-compliant tools simply ignore unknown fields (so nothing breaks), but the values are meaningless there.
  68. **`sync-skill` never rewrites these values.** It copies the skill as-is, then prints a report listing which synced skills declare `model`/`effort` and reminds you to **edit them manually** for the target platform:
  69. ```
  70. [sync-skill] Heads up — some synced skills declare model-specific fields:
  71. [sync-skill] - demo (model: opus, effort: high)
  72. [sync-skill] Cursor uses a different model family. These values were copied as-is — please edit them manually.
  73. ```
  74. ## 8. Overwrite Confirmation
  75. When a source skill shares its folder name with a skill already present on the target, `sync-skill` does **not** overwrite it silently. Instead it:
  76. 1. Tells you the skill already exists on the target.
  77. 2. Shows the source and target `version` (read from each `SKILL.md` frontmatter), if either side declares one.
  78. 3. Asks you to confirm the replacement.
  79. ```
  80. [sync-skill] "demo" already exists in Cursor (~/.cursor/skills).
  81. [sync-skill] Source version: 2.0.0 Target version: 1.0.0
  82. ? Replace "demo"? This cannot be undone — no backup will be kept. (y/N)
  83. ```
  84. This applies in both interactive and direct (`npx sync-skill <source> <target>`) mode. Declining leaves the existing target skill untouched (reported as **Skipped**); accepting replaces it permanently — **no backup is kept**, so make sure you no longer need the existing version before confirming.
  85. ## 9. Platform Compatibility
  86. - On Windows, home-based tools resolve under `%USERPROFILE%`; OpenCode resolves under `%LOCALAPPDATA%`. Missing environment variables fall back to the standard `AppData` locations.
  87. - `--scope project` resolves directories relative to the current working directory, so run it from your project root.
  88. - Paths are normalized per-OS, so the same command works on Linux, macOS, and Windows.
  89. ## License
  90. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.