Sync Modes

skillshare が source と target をどのようにリンクするか。

これが重要になる場面

Skill ごとの symlink を使い、target 内のローカル Skill を保持したい場合は merge mode(デフォルト)を選びます。symlink ではなく実ファイルが必要な場合(可搬性、CI、個人の好みなど)は copy mode を選びます。ディレクトリ全体をリンクしたく、target 側のローカル Skill が不要な場合は symlink mode を選びます。

概要

モード	動作	ユースケース
`merge`	各 Skill が個別に symlink される	デフォルト。ローカル Skill を保持する。
`copy`	各 Skill が実ファイルとしてコピーされる	可搬性、CI/サンドボックス環境、または symlink より実ファイルを好む場合。
`symlink`	ディレクトリ全体が 1 つの symlink になる	どこでも完全に同一のコピーにする。

判断マトリクス(中立)

target のブランド名ではなく、自分の制約条件をもとに選ぶための表です。

判断軸	`merge`	`copy`	`symlink`
異なる AI CLI 間の互換性	中	高	低〜中
1 回の編集の即時反映	高	低(`sync` が必要)	高
ディスク使用量	低	高	低
target 側での誤削除への安全性	高	高	低
運用のシンプルさ	中	中	高
target ごとのフィルタリング(`include`/`exclude`)	あり	あり	なし

迷ったら merge から始め、必要に応じて特定の target だけ copy に切り替えてください。

Merge Mode(デフォルト)

各 Skill が個別に symlink されます。target 内のローカル Skill は保持されます。

Source                          Target (claude)
─────────────────────────────────────────────────────────────
skills/                         ~/.claude/skills/
├── my-skill/        ────────►  ├── my-skill/ → (symlink)
├── another/         ────────►  ├── another/  → (symlink)
└── ...                         ├── local-only/  (preserved)
                                └── .skillshare-manifest.json

利点:

target 固有の Skill(同期されないもの)を残せる
インストールされた Skill とローカル Skill を混在できる
細かい制御ができる
target ごとの include/exclude フィルタリング
マニフェストベースの孤立ファイル削除(uninstall 後、symlink 以外の残骸を安全に削除)

Project mode における相対 symlink

project mode(-p)では、symlink は絶対パスではなく 相対パス(例: ../../.skillshare/skills/my-skill)として作成されます。これにより、ディレクトリを移動・リネームしても symlink が機能し続けるため、プロジェクトの可搬性が高まります。global mode では、source と target が異なる場所にあるため絶対パスが使われます。

使うべき場面:

一部の Skill を特定の AI CLI にだけ入れたい場合
同期する前にローカル Skill を試したい場合
1 つの source から、target ごとに異なる Skill の組み合わせにしたい場合

Merge Mode でのフィルタ戦略

include と exclude は target ごとに次の順序で評価されます。

include がマッチする名前を残す
exclude がその残った集合から取り除く

簡単な選び方:

target に少数のサブセットだけを渡したいときは include を使う
target にほぼすべてを渡したいときは exclude を使う
広いサブセットに明示的な除外を加えたいときは include + exclude を使う

ルールを変更したときの挙動:

これまで同期されていた source 由来のエントリがフィルタで除外されると、次回の sync で削除される
target 内の既存のローカルな非 symlink フォルダは保持される

完全な例については Target Configuration を参照してください。

Copy Mode

各 Skill は実ファイルとして target ディレクトリにコピーされます。.skillshare-manifest.json ファイルが管理対象の Skill とそのチェックサムを追跡するため、ローカル Skill は保持されます。

Source                          Target (cursor)
─────────────────────────────────────────────────────────────
skills/                         ~/.cursor/skills/
├── my-skill/        ────copy►  ├── my-skill/    (real files)
├── another/         ────copy►  ├── another/     (real files)
└── ...                         ├── local-only/  (preserved)
                                └── .skillshare-manifest.json

なぜ Copy Mode なのか

使用している AI CLI が symlink を正しく扱える場合でも、copy mode には価値があります。

防御的な設計 — すべての AI CLI が symlink サポートを保証しているわけではなく、特に Windows では symlink の挙動がプラットフォームや権限レベルによって異なる
サンドボックス環境 — 厳格な CI パイプライン、コンテナ、エアギャップ環境ではファイルシステム境界をまたぐ symlink をたどれないことがある
ユーザーの好み — 一部のユーザーやチームは、透明性や可搬性のために symlink よりも実ファイルを単純に好む

利点:

どこでも動作する — AI CLI や OS 側に symlink サポートは不要
ローカル Skill を保持する(merge mode と同様)
target ごとの include/exclude フィルタリング
チェックサムによるスキップ: 変更のない Skill は再コピーされない

使うべき場面:

使用している AI CLI が「Skill が見つからない」と報告する、または symlink された Skill を読み込めない場合
プロジェクトリポジトリに Skill をベンダリングしたい場合 — project mode の copy mode を使うと、チームは実際の Skill ファイルを git にコミットできるため、チームメイトは skillshare をインストールする必要がなくなる
中央の source なしで動作する自己完結型の Skill ディレクトリが必要な場合(可搬な構成、CI パイプライン、エアギャップ環境)
merge mode と同じフィルタリングの挙動を実ファイルで実現したい場合
copy の最初の候補としてよく挙がるもの: cursor、antigravity、copilot、opencode

更新の仕組み

skillshare sync を実行するたびに、各 source Skill のチェックサムがマニフェストに保存された値と比較されます。

チェックサムが同じ → Skill はスキップされる(高速)
チェックサムが異なる → Skill は新しいバージョンで上書きされる
--force → チェックサムに関係なく、管理対象のすべての Skill が上書きされる

マニフェストのライフサイクル

merge mode と copy mode の両方が、管理対象の Skill を追跡するために .skillshare-manifest.json を書き込みます。

Merge mode: Skill 名を値 "symlink" として記録 — uninstall 後に孤立した実ディレクトリ(例: copy mode の残骸)を安全に削除するために使われる
Copy mode: Skill 名を SHA-256 チェックサムとともに記録 — 差分同期と孤立検出に使われる
symlink mode に切り替えると自動的に削除される
手動で削除された場合、次の sync で再構築される

Symlink Mode

target ディレクトリ全体が source への単一の symlink になります。

Source                          Target (claude)
─────────────────────────────────────────────────────────────
skills/              ────────►  ~/.claude/skills → (symlink to source)
├── my-skill/
├── another/
└── ...

利点:

すべての target が完全に同一になる
管理がシンプル
孤立した symlink が発生しない

使うべき場面:

すべての AI CLI にまったく同じ Skill を持たせたい場合
target 固有の Skill が不要な場合

警告: symlink mode では、target 経由で削除すると source も削除されます!

rm -rf ~/.claude/skills/my-skill  # ❌ SOURCE から削除されてしまう
skillshare target remove claude   # ✅ 安全にリンクを解除する方法

モードの変更

target ごと

# copy mode に切り替える(symlink を読めない AI CLI 向け)
skillshare target cursor --mode copy
skillshare sync

# symlink mode に切り替える
skillshare target claude --mode symlink
skillshare sync

# merge mode に戻す
skillshare target claude --mode merge
skillshare sync

target ごとの上書き(推奨)

すべての target に対して 1 つのグローバルモードを使う必要はありません。よくあるパターンは次の通りです。

mode: merge
targets:
  claude:
    path: ~/.claude/skills
    # inherits merge
  cursor:
    path: ~/.cursor/skills
    mode: copy
  codex:
    path: ~/.codex/skills
    mode: symlink

ある target には互換性優先の挙動(copy)が必要で、他の target は即時反映(merge/symlink)を維持したい場合に、target ごとの上書きを使います。

デフォルトモード

新しい target 向けに設定で指定します。

# ~/.config/skillshare/config.yaml
mode: merge  # or symlink or copy

targets:
  claude:
    path: ~/.claude/skills
    # inherits default mode

  cursor:
    path: ~/.cursor/skills
    mode: copy  # real files for Cursor

  codex:
    path: ~/.codex/skills
    mode: symlink  # override default

Target の命名規則

merge mode または copy mode を使うとき、target 内で Skill ディレクトリがどう命名されるかを制御します。

命名方式	動作
`flat`(デフォルト)	ネストした Skill は `__` 区切りでフラット化される: `frontend/dev` → `frontend__dev`
`standard`	SKILL.md の `name` フィールドを使う: `frontend/dev` → `dev`

グローバルまたは target ごとに設定します。

target_naming: standard    # global default
targets:
  claude:
    skills:
      target_naming: flat  # per-target override

または CLI 経由で設定します。

skillshare target claude --target-naming standard
skillshare sync

Standard mode は Agent Skills specification に従い、SKILL.md の name フィールドが親ディレクトリ名と一致することを要求します。有効な名前は最大 64 文字の小文字（どの文字体系でも可）、数字、単独のハイフンで構成され、- で始まったり終わったりしません。アンダースコアは使えません。名前が無効な Skill や名前の衝突は警告され、スキップされます。

移行: flat から standard に切り替えると、既存の管理対象エントリはその場で自動的にリネームされます。ローカル Skill が既にそのベア名を占有している場合、レガシーの flat エントリは保持されます。

Symlink mode: target_naming は無視されます — ディレクトリ全体がそのままリンクされます。

モードの比較

観点	Merge	Copy	Symlink
ローカル Skill の保持	✅ あり	✅ あり	❌ なし
symlink 互換性	✅ あり	❌ 実ファイル	✅ あり
すべての target が同一	❌ 異なる場合がある	❌ 異なる場合がある	✅ 同一
target ごとの include/exclude	✅ あり	✅ あり	❌ 無視される
孤立ファイル削除の必要性	✅ あり	✅ あり	❌ なし
削除の安全性	✅ 安全	✅ 安全	⚠️ 注意が必要
ディスク使用量	低(symlink)	高め(コピー)	低(symlink)

孤立ファイルの削除

merge mode と copy mode の両方で、sync は自動的に孤立ファイルを削除します。

削除された source Skill を指す symlink は常に削除される
.skillshare-manifest.json に記録されている(以前 skillshare が管理していた)実ディレクトリ は削除される
マニフェストにない 未知のディレクトリ はユーザーが作成したものとみなされ、警告とともに保持される

つまり uninstall + sync の後は、symlink 以外の残骸(例: 以前の copy mode から残ったディレクトリ)も安全にクリーンアップされます。

$ skillshare sync
✓ claude    5 linked · 2 local · 1 pruned
✓ cursor    3 copied · 2 up to date · 1 pruned

エージェントも同じモードに従う

merge、copy、symlink の 3 つのモードすべてが、エージェントの同期にも適用されます。エージェントの孤立ファイル削除、target ごとの include/exclude フィルタリング、モード変換の挙動は Skill とまったく同じです。唯一の違いは、エージェントがディレクトリではなく単一の .md ファイルであることです。エージェント対応の target(Claude、Cursor、Augment、OpenCode)は、agents: サブキーに対しても同じ mode 設定に従います。詳細は Agents を参照してください。

Extras の Sync Modes

Extras(rules、commands、prompts のような Skill 以外のリソース)も merge mode と copy mode を使用します。各 extras の target は独自のモードを指定できます。

extras:
  - name: rules
    targets:
      - path: ~/.claude/rules          # merge (default): per-file symlinks
      - path: ~/.cursor/rules
        mode: copy                     # copy: real file copies

挙動は Skill の sync modes と同じです。merge はファイルごとの symlink を作成し、copy は実ファイルのコピーを作成します。

Developer Mode がオフの Windows

merge mode は単一のファイルをリンクしますが、Windows では Developer Mode がオンの場合にしか許可されません。Developer Mode がない場合、merge mode の agents と extras は代わりにコピーされ、それらのコピーはリンクと同じように更新・削除されます。Skills はフォルダーなので、どちらの場合も（ジャンクションで）リンクされます。Windows のトラブルシューティングを参照してください。

skillshare が所有していない、内容が同じローカルファイルは保持されます。copy fallback では agent の件数に local preserved として別に表示されます（例：0/1 linked, 1 local preserved）。

概要​

判断マトリクス(中立)​

Merge Mode(デフォルト)​

Merge Mode でのフィルタ戦略​

Copy Mode​

なぜ Copy Mode なのか​

更新の仕組み​

マニフェストのライフサイクル​

Symlink Mode​

モードの変更​

target ごと​

target ごとの上書き(推奨)​

デフォルトモード​

Target の命名規則​

モードの比較​

孤立ファイルの削除​

Extras の Sync Modes​

関連ページ​

概要

判断マトリクス(中立)

Merge Mode(デフォルト)

Merge Mode でのフィルタ戦略

Copy Mode

なぜ Copy Mode なのか

更新の仕組み

マニフェストのライフサイクル

Symlink Mode

モードの変更

target ごと

target ごとの上書き(推奨)

デフォルトモード

Target の命名規則

モードの比較

孤立ファイルの削除

Extras の Sync Modes

関連ページ