AIツールのスキル管理を1か所にまとめる——/skill-sync の仕組みと実践

公開時点: 記事本文に明記なし
検証日: 記事本文に明記なし
対象: Claude Code / Codex CLI / Gemini CLI / /skill-sync

• 結論: 複数の AI CLI で同じスキルを使うなら、~/.claude/skills/ を正本にして同期する運用はかなり現実的です。
• 何が効くか: 手動コピーの更新漏れを減らし、スキル管理の分散を止められます。
• 何を判断すべきか:
  • Claude Code / Codex CLI / Gemini CLI を横断して使うなら導入候補
  • 1つのツールしか使わないなら、無理に入れる必要は薄い
  • Docker や権限が絡む環境では、先にパスと所有権を確認する
• 注意: 同期ツールは便利ですが、ツール仕様の差や権限問題まで自動で消してくれるわけではありません。

• まず何が楽になるのか
• Single Source of Truth にする意味は、単なる整理ではない
  • 1. 更新漏れが減る
  • 2. スキルの内容が比較しやすくなる
  • 3. 追加コストを増やさずにツールを増やせる
• 仕組みはどうなっているのか
  • 基本の流れ
  • 重要なのは、形式の差を吸収すること
  • ただし万能ではない
• 使い方は「正本を置く → 同期する」が基本
  • 1. まず正本を ~/.claude/skills/ に集める
  • 2. プロジェクト側の反映先を決める
  • 3. /skill-sync を走らせる
  • 4. 更新時は正本だけ触る
• Claude Code の権限設定は先に確認する
  • ありがちな失敗
• Docker 環境では、ホームディレクトリの見え方が落とし穴になる
  • 問題になりやすい点
  • 実務での考え方
    • パターンA: ホスト側を正本にする
    • パターンB: コンテナ側を正本にする
  • まず確認すること
• どんな場面で効くか
  • 効く場面
  • あまり効かない場面
• 実際に使ってみて感じたこと
• ワンショットプロンプトで /skill-sync を自作する
  • カスタマイズするなら
• 今日からやるなら、この順番です
• まとめ
• この記事を書いた人
• 関連記事

一番の効果は、スキルの保管場所を1か所に戻せることです。

たとえば、こんな運用をしているとします。

• Claude Code: ~/.claude/skills/
• Codex CLI: それ用の配置先
• Gemini CLI: また別の配置先
• プロジェクト内: .claude/skills/ 的な配置

この状態だと、新しいスキルを1つ追加するたびに、複数箇所へコピーして、内容が一致しているか確認して、どれが最新版か迷うことになります。

/skill-sync はここを割り切ります。

• 正本は ~/.claude/skills/ に置く
• そこから各ツール向けの所定場所へ同期する
• 手動コピーをやめる

つまり、「作る場所」と「配る場所」を分ける発想です。

この分離は単純ですが、実務ではかなり強いです。更新のたびに脳のメモリを削られないので、スキル整備を続けやすくなります。

見た目は「ファイルをまとめるだけ」に見えます。ですが、実際はもっと重要です。

1. 更新漏れが減る

人間は、同じ内容を複数箇所へコピペすると、どこかで忘れます。これは根性の問題ではなく、作業の性質です。

Single Source of Truth にすると、更新対象が1つになるので、**「直したつもり問題」**が起きにくくなります。

2. スキルの内容が比較しやすくなる

Claude Code 用、Codex 用、Gemini 用で別々に編集していると、何が違うのかを追うだけで疲れます。

正本が1つなら、差分管理は同期ロジック側に寄せられます。人間は中身の改善だけに集中できます。

3. 追加コストを増やさずにツールを増やせる

AI ツールを増やすのは簡単です。維持するのが面倒です。

/skill-sync の価値は、ツールを増やしてもスキル管理の運用コストを増やしにくいことにあります。

実際のところ、/skill-sync がやっていることはシンプルです。魔法のように各ツールを理解してくれるわけではなく、かなり地に足がついた仕組みです。

~/.claude/skills/ を Single Source of Truth として、Claude Code・Codex CLI・Gemini CLI へ自動展開する。

基本の流れ

1. ~/.claude/skills/ を正本として読む
2. プロジェクト内に必要ならそこへ反映する
3. Claude Code / Codex CLI / Gemini CLI の期待する配置へコピーまたは展開する
4. 必要に応じて同期を繰り返す

要するに、同期の責務を人間から外す仕組みです。

重要なのは、形式の差を吸収すること

ツールごとに、期待するディレクトリ構成や読み方が少しずつ違います。ここを毎回手で合わせるのがつらい。

/skill-sync は、その差を吸収して「正本 → 各ツール向け出力」に変換する役割を持ちます。

これは、ビルド成果物を直接編集しないのと同じ発想です。編集対象と配布対象を分けたほうが、壊れにくい。

ただし万能ではない

ここは大事です。

• ツールの仕様変更に追従が必要なことがある
• どのツールでも完全に同じ挙動になるとは限らない
• スキルの書き方自体がツール依存だと、同期しても差は残る

つまり、同期ツールは整流器であって、差異を完全に消す装置ではないです。

細かな導入手順は環境差が出るので断定しませんが、考え方はシンプルです。

1. まず正本を ~/.claude/skills/ に集める

このディレクトリに、自作スキルを寄せます。

~/.claude/skills/
  code-review/
  commit-message/
  incident-note/

ここを唯一の編集対象にします。

2. プロジェクト側の反映先を決める

プロジェクトで共有したいスキルがあるなら、その同期先を決めます。

• リポジトリ内の所定ディレクトリ
• チームで共有する設定場所
• 各ツールが参照する位置

ポイントは、**「置く場所を増やす」のではなく、「同期先を定義する」**ことです。

3. /skill-sync を走らせる

ここで正本から各所へ展開します。

実際のコマンド名やオプションは環境により変わる可能性があるので、ここでは断定しませんが、運用としては次の感覚です。

skill-sync

これを定期実行または更新時に走らせることで、各ツールのスキルを揃えます。

4. 更新時は正本だけ触る

これが最重要です。

Claude Code 側のコピーを直さない。Codex 側のコピーも直さない。Gemini 側も同じ。

直すのは ~/.claude/skills/ だけです。

この運用が徹底できると、スキル管理のだるさがかなり減ります。

ここは地味にハマります。

Claude Code は、環境によって権限やアクセス許可の扱いが絡みます。同期そのものはできても、読み書き先の権限が足りずに失敗することがあります。

実務上は、少なくとも次を先に見ます。

• ~/.claude/skills/ に書き込めるか
• プロジェクト配下へ展開する権限があるか
• 実行ユーザーが固定されているか
• CI や Docker 内から走らせる場合、ホームディレクトリの扱いがどうなるか

ありがちな失敗

• root で作ったファイルを通常ユーザーが更新できない
• Docker コンテナ内の ~/.claude とホスト側が別物
• 権限はあるが、パスの解決先が想定と違う

ここで「同期ツールが壊れている」と思いがちですが、実際は権限と実行環境の問題であることが多いです。

Docker で開発している人は、ここを甘く見ないほうがいいです。

問題になりやすい点

• コンテナ内の ~/.claude はホストと別管理
• ボリュームマウントしないと、同期結果がコンテナ内で消える
• ホストに同期したつもりでも、別ユーザーのコンテナでは見えない
• パーミッションの差でコピーが失敗する

実務での考え方

Docker で /skill-sync を使うなら、まずどちらを正本にするか決めるべきです。

パターンA: ホスト側を正本にする

• ~/.claude/skills/ はホストに置く
• コンテナには必要なものだけマウントする
• 同期はホストで実行する

これは分かりやすいです。個人開発ならこちらのほうが事故が少ないです。

パターンB: コンテナ側を正本にする

• 再現性は出しやすい
• ただしホストとの往復が増える
• デバッグ時に「今どっちのファイルを見ているか」が分かりづらい

チームで統一するならありですが、個人用途では少し重いです。

まず確認すること

Docker を使うなら、同期前に次を確認します。

whoami
pwd
ls -la ~/.claude/skills/

この3つだけでも、見え方がかなり変わります。

/skill-sync は、何でもかんでも便利にするタイプではありません。ハマる場面はかなり明確です。

効く場面

• Claude Code / Codex CLI / Gemini CLI を併用している
• 自作スキルを複数ツールで揃えたい
• プロジェクト内とグローバルの両方でスキルを管理している
• 手動コピーの更新漏れにうんざりしている
• チームでスキルの標準化を進めたい

あまり効かない場面

• 使う AI CLI が1つだけ
• スキルの数が少なく、手動管理でも苦痛がない
• CLI やファイル同期の仕組みを触りたくない
• ツールごとの差異を吸収するより、個別最適で済ませたい

ここははっきり分けていいです。CLI に慣れている人には効く。慣れていない人には、そもそも不要なツールです。

大きな変化に見えにくいところですが、毎日触るものほどじわじわ効いてきます。

一番良かったのは、スキル更新の心理的コストが下がったことです。

「複数箇所を直すのが面倒だな」が消えるだけで、スキルを追加・改善する頻度が上がります。すると、結果として AI ツールの使い勝手も上がります。ここは地味ですが、かなり実務的です。

一方で、微妙な点もあります。

• 初回導入時は、同期先の整理に少し時間がかかる
• 権限や Docker の構成次第で、最初の一回はつまずく
• ルールを守らないと、結局またコピー地獄に戻る

つまり、入れた瞬間に全部解決する道具ではないです。ですが、運用ルールまで含めて整えると、かなり現実的に効きます。

「そのまま使いたい」という人のために、Claude Code に一発で依頼できるプロンプトテンプレートを置いておきます。

自分の環境に合わせて [YOUR_HOME] などを書き換えて使ってください。初めて試すなら、まず dry-run で確認してから本番実行するのが安全です。

以下の要件でスキルファイルを ~/.claude/skills/skill-sync/SKILL.md として作成してください。


## 目的
~/.claude/skills/ を Single Source of Truth として、
Claude Code / Codex CLI / Gemini CLI の3ツールにスキルを自動同期するスキル。


## 同期先
- Codex CLI  : ~/.codex/skills/{name}/ にシンボリックリンク（ln -sfn）
- Gemini CLI : ~/.gemini/commands/{name}.toml に TOML ファイルを自動生成


## Gemini TOML の生成ルール
- SKILL.md の YAML frontmatter から description フィールドを読む
- テンプレート:
  description = "{description}"
  prompt = """
  以下のスキル手順を実行してください：
  !{cat ~/.claude/skills/{name}/SKILL.md}
  """
- frontmatter がなければスキップしてログに出力する


## 動作要件
1. dry-run フラグ対応（変更内容を表示するが実行しない）
2. 冪等性（再実行で変更が0になること）
3. 同期前に ~/.codex/skills/ と ~/.gemini/commands/ の存在確認
4. 除外リスト（スキップするスキル名を配列で指定できること）


## 注意点（必ずコメントとして SKILL.md に含めること）
- ~/.codex/ や ~/.gemini/ への書き込みは Claude Code の
  settings.json > allowedDirectories に追加が必要
- Codex は YAML frontmatter 必須（なければスキップ）
- Gemini の trustedFolders.json でリンク先が信頼外だと
  ブロックされる場合がある
- Docker 環境ではホスト側で実行し、コンテナへは別途マウントすること

このプロンプトをそのまま Claude Code に渡すと、SKILL.md が生成されます。あとは /skill-sync --dry-run で確認 → /skill-sync で本番実行の流れです。

カスタマイズするなら

いきなり大規模に入れ替える必要はありません。まずは小さく始めるのがいいです。

1. ~/.claude/skills/ にあるスキルを棚卸しする
2. 上のプロンプトを Claude Code に渡して /skill-sync を生成する
3. dry-run で同期先を確認する
4. settings.json の allowedDirectories に ~/.codex と ~/.gemini を追加する
5. 本番実行 → 以降は正本（~/.claude/skills/）だけ編集する

この順番なら、導入の失敗コストは低いです。

/skill-sync の価値は、派手な機能ではなく、スキル管理の分散を止められることにあります。

Claude Code、Codex CLI、Gemini CLI を横断している人ほど、手動コピーのだるさは見逃せません。

• 正本を ~/.claude/skills/ に置く
• 上のプロンプトで /skill-sync を自作する
• dry-run で確認してから本番実行
• 更新は正本だけに集約する

CLI に慣れている人なら、今日中に整えられる作業量です。

ハードウェア系エンジニア20年超。業務では単独でソリューション2,000件超を回してきた。Claude Code・Codex・Gemini CLI を同時に使い始めてから、スキル管理の破綻に一度ハマり、/skill-sync を作った。このサイト（META-MARK）も全部自作。

• Blog失敗から学ぶClaude Code Sonnet 4.6 1M context：$15と$5の分岐点Claude Code MAXプランで1M contextが突然使えなくなった原因を実機で調査。extra usageの正体と、最小コストで戻す判断材料を整理します。→
• BlogClaude Code の新effortモード徹底解説｜max・ultracode・autoと『呪文ultrathink』の正体Claude Code の /effort に増えた max・ultracode・auto と、プロンプトに紛れ込ませる呪文 ultrathink を、公式が明言した『ultracode は API の effort レベルではない』を起点に解剖。overthinking・自律ワークフロー・永続性と優先順位の罠まで、誤解されやすい論点を一次情報で正します。→
• BlogClaude Code の /effort 完全ガイド｜low〜maxの使い分けと『コストが増える本当の理由』Claude Code の /effort（low〜max・ultracode・auto）は「賢さ」ではなく「トークンの気前よさ」のレバー。モデル別の推奨スタートと、Opus 4.8 でコストが増えた気がする原因を『トークナイザ』と『effort』の2軸に切り分ける考え方を、公式一次情報と v2.1.156 の実機確認で解説します。→