/sync

sidebar_position: 2

sync

Skill を source からすべての targets にプッシュします。

MCP 接続設定には `skillshare sync mcp` を、skills、agents、extras、MCP、hooks をまとめて含めるには `skillshare sync --all` を使用してください。MCP の同期は skill のシンボリックリンクではなく、 エントリの所有権とコンフリクトチェックを使用します。[mcp](/docs/reference/commands/mcp) を参照してください。

:::info sync はなぜ独立したコマンドなのか？ `install` や `uninstall` のような操作は source のみを変更します — sync は targets に反映します。これにより、変更をバッチ処理し、`--dry-run` でプレビューし、targets が更新されるタイミングを制御できます。[Why Sync is a Separate Step](/docs/understand/source-and-targets#why-sync-is-a-separate-step) を参照してください。 :::

エージェント別スキルバリアント

Tracked repository 内の `skills/<known-agent>/<skill-path>/SKILL.md` は、同じ `skills/` 親ディレクトリ内の二つ以上の異なる正規エージェントに同じ完全なスキルパスがある場合にのみ、エージェント別バリアントと認識されます。一つのエージェントの別名だけでは該当しません。単独の `skills/agents/planner` カテゴリは通常のスキルのままです。

Merge/copy mode では、別名やアカウント target を含め、対応するエージェントにルーティングします。同じ skills フォルダを共有する互換性のある targets は、エージェント ID の和集合を選択します。Codex と `universal` が `~/.agents/skills` を共有する場合、Codex のバリアントが保持されます。各読み取り側にはこの和集合が公開され、互換性のない設定には重複・競合の診断が引き続き表示されます。明示的なソースローカル target 上書きと frontmatter のルーティングが優先され、無視規則と include/exclude フィルタも適用されます。

Source と repository の概要は論理スキルを一度だけ数え、`2 skills, 4 variants` のように物理バリアントを別に表示します。Target ごとの同期操作は物理的な数のままです。ディレクトリ全体の symlink mode はすべてのバリアントを公開します。`status` と `doctor` はこの制限を説明し、自動ルーティングには merge または copy を推奨します。

使うタイミング

• Skill をインストール、uninstall、編集した後 — 変更をすべての targets に反映する
• target の sync mode を変更した後 — 新しい mode を適用する
• 定期的に、すべての targets が sync されていることを確認する

コマンド概要

| タイプ | コマンド | 方向 | |------|---------|-----------| | **Local sync** | `sync` / `collect` | Source ↔ Targets | | **Remote sync** | `push` / `pull` | Source ↔ Git Remote |

• `sync` = Source から Targets へ配布
• `collect` = Targets から Source へ収集
• `push` = git remote へプッシュ
• `pull` = git remote からプルして sync

概要

flowchart TD
    REMOTE["`Remote
(git)`"]
    SOURCE["`SOURCE
~/.config/skillshare/skills/`"]
    CLAUDE["Claude"]
    CURSOR["Cursor"]
    CODEX["Codex"]

    SOURCE -- push --> REMOTE
    REMOTE -- pull --> SOURCE
    SOURCE -- sync --> CLAUDE
    SOURCE -- sync --> CURSOR
    SOURCE -- sync --> CODEX
    CLAUDE -- collect --> SOURCE
    CURSOR -- collect --> SOURCE
    CODEX -- collect --> SOURCE

| コマンド | 方向 | 説明 | |---------|-----------|-------------| | `sync` | Source → Targets | Skill をすべての targets にプッシュ | | `collect <target>` | Target → Source | target から source へ skill を収集 | | `push` | Source → Remote | git にコミットしてプッシュ | | `pull` | Remote → Source → Targets | git からプルし、その後 sync |

---

Project Mode

カレントディレクトリに `.skillshare/config.yaml` が存在する場合、sync は project mode を自動検出します。

cd my-project/
skillshare sync          # 自動検出された project mode
skillshare sync -p       # 明示的な project mode

**Project sync** はデフォルトで merge mode（skill ごとのシンボリックリンク）になりますが、`skillshare target <name> --mode copy -p` によって各 target を copy または symlink mode に設定できます。バックアップは作成されません（project の targets は source から再現可能なため）。

sync が手動で移動した宣言済み skill を引き継ぐときは、その skill の project 設定、ignore rule、既存の lock pin だけを更新します。古いインストール記録があるだけで移動がない場合、`config.yaml`、`.gitignore`、`skills.lock.json` は変更されません。source 内の他の remote installs も project の `skills:` リストには追加されません。

.skillshare/skills/                 .claude/skills/
├── my-skill/          ────────►    ├── my-skill/ → (symlink)
├── pdf/               ────────►    ├── pdf/      → (symlink)
└── ...                             └── local/    (preserved)

デフォルトパスが移動した後のクリーンアップ {#project-path-cleanup}

Project の設定はパスではなく target 名を保存するため、target は組み込みのデフォルトパスに従います。ツールがそのデフォルトを変更すると — goose と openhands が `.agents/skills` を採用したときのように — skillshare が以前のディレクトリに書き込んだ Skill が残り、ツールは両方の場所を読み込んですべての Skill を二重に一覧表示してしまいます。

Project sync はそれらを削除します。明示的な `path:` を持たない各 target について、その target のランタイムがあわせてスキャンするディレクトリを調べ、そのうち設定済みのどの target も書き込まないディレクトリから、skillshare が作成したエントリを削除します。自分で作成したフォルダや、project の外を指すシンボリックリンクが変更されることはありません。

  Cleaned 1 leftover skill from .goose/skills: the default path for 'goose' moved to .agents/skills

target に明示的な `path:` を設定すると、その target はクリーンアップの対象外になります。また `--dry-run` は、何も変更せずに削除される対象をプレビューします。

---

Sync

Skill を source からすべての targets にプッシュします。

skillshare sync              # skill をすべての targets に sync
skillshare sync agents       # agents のみを sync
skillshare sync --all        # skills + agents + extras + MCP + hooks を sync
skillshare sync --dry-run    # 変更をプレビュー
skillshare sync -n           # 短縮形
skillshare sync --force      # 管理対象のすべての skill を上書き
skillshare sync -f           # 短縮形

| フラグ | 短縮形 | 説明 | |------|-------|-------------| | `--all` | | skills の後に agents、extras、MCP + hooks も sync（plugins は除く） | | `--dry-run` | `-n` | 書き込まずに変更をプレビュー | | `--force` | `-f` | チェックサムに関わらず管理対象のすべてのエントリを上書き（copy mode）、または既存のディレクトリをシンボリックリンクに置き換え（merge mode） | | `--json` | | JSON として出力 | | `--quiet` | `-q` | トークンサマリーと budget 警告を抑制 |

JSON 出力

skillshare sync --json

{
  "targets": 3,
  "linked": 12,
  "local": 2,
  "updated": 0,
  "pruned": 1,
  "ignored_count": 2,
  "ignored_skills": ["_team/vendor/lib", "test-draft"],
  "dry_run": false,
  "duration": "0.234s",
  "warnings": ["source link _dev-skills not followed: target is missing; kept existing target entries, nothing pruned this run"],
  "details": [
    {
      "name": "claude",
      "mode": "merge",
      "linked": 8,
      "local": 2,
      "updated": 0,
      "pruned": 1
    },
    {
      "name": "cursor",
      "mode": "merge",
      "linked": 4,
      "local": 0,
      "updated": 0,
      "pruned": 0
    }
  ],
  "context_cost": {
    "groups": [
      {
        "targets": ["claude", "cursor"],
        "always_loaded_tokens": 12400,
        "on_demand_tokens": 58200
      }
    ]
  }
}

`ignored_count` と `ignored_skills` フィールドは、`.skillignore`（および存在する場合は `.skillignore.local`）によって除外された skill を示します。これらは discovery 時にフィルタリングされ、どの target にも到達しません。`.skillignore.local` が有効な場合、テキスト出力には `.local` の source ヒントが含まれます。パターンの構文については [.skillignore](/docs/reference/appendix/fi