Claude CodeとCodexのスキル共有をシンボリックリンクからジャンクションに変えた理由【Windows】

以前、Claude CodeとCodexで同じAgent Skillsを使うために、.agent/skills を正本として、.claude/skills と .codex/skills からシンボリックリンクで参照する方法を紹介しました。

構成としては次のような形です。

MyProject/
├── .agent/
│   └── skills/
│       └── your-skill-name/
│           ├── SKILL.md
│           ├── references/
│           └── scripts/
├── .claude/
│   └── skills -> ../.agent/skills
└── .codex/
    └── skills -> ../.agent/skills

スキルの実体を1か所に置いて、Claude CodeとCodexから同じものを参照する。

この考え方自体は今も変わっていません。

一方で、その後Windows環境で運用していく中で、リンクの作り方についてはシンボリックリンクではなくジャンクションの方が今回の用途には合っているのではないかと考えるようになりました。

現在は、.claude/skills と .codex/skills をジャンクションとして作成しています。

この記事では、なぜシンボリックリンクからジャンクションへ変更したのか、そして実際に使ってみて分かった制約について整理します。

結論：Windowsでディレクトリを共有するだけならジャンクションで十分だった

現在の構成は次のようにしています。

MyProject/
├── .agent/
│   └── skills/
│       ├── skill-a/
│       ├── skill-b/
│       └── skill-c/
├── .claude/
│   └── skills => .agent/skills
└── .codex/
    └── skills => .agent/skills

論理的な構成は以前と同じです。

違うのは、.claude/skills と .codex/skills をシンボリックリンクではなくジャンクションとして作っている点です。

Windowsでは次のコマンドで作成できます。

mklink /J ".claude\skills" ".agent\skills"
mklink /J ".codex\skills" ".agent\skills"

Microsoftのドキュメントでも、mklink /D はディレクトリのシンボリックリンク、mklink /J はディレクトリジャンクションを作成するオプションとして定義されています。

今回の用途は、

• ファイル単体をリンクしたいわけではない
• ネットワーク上のディレクトリを参照したいわけでもない
• Windows上のローカルディレクトリ同士をつなぎたい
• .agent/skills というフォルダを別の場所から見せたい

という非常に限定されたものです。

この条件なら、より汎用的なシンボリックリンクを使わなくても、ジャンクションで十分でした。

そもそもジャンクションとは何か

ジャンクションは、Windowsにある「あるディレクトリから別のディレクトリを参照する」仕組みです。

例えば、

.claude/skills

にアクセスしたとき、実際には

.agent/skills

を参照させることができます。

利用する側から見ると、通常のディレクトリとほとんど同じように扱えます。

WindowsのジャンクションはNTFSのReparse Pointという仕組みを使って実装されています。

今回やりたいことは、まさにこの「ディレクトリの別名を作る」という使い方でした。

シンボリックリンクとの違い

シンボリックリンクとジャンクションは似ていますが、できることには違いがあります。

ざっくり整理すると次のようになります。

シンボリックリンクの方が機能としては柔軟です。

例えば、

• ファイル単体もリンクしたい
• 相対パスでリンクしたい
• ネットワーク上のディレクトリを参照したい
• Windows以外でも同じ考え方を使いたい

といった場合は、シンボリックリンクの方が適しています。

そのため、

ジャンクションの方がシンボリックリンクより優れている

という話ではありません。

重要なのは、用途に対してどちらが適しているかです。

なぜ最初はシンボリックリンクを使っていたのか

最初にシンボリックリンクを採用した理由は単純で、

1つのディレクトリを複数箇所から参照する

という仕組みとして、シンボリックリンクがまず思い浮かんだからです。

LinuxやmacOSでも一般的な仕組みなので、概念としても分かりやすいです。

実際、前回紹介した構成でも問題なくClaude CodeとCodexからスキルを認識できました。

そのため、シンボリックリンクを使ったこと自体が間違いだったわけではありません。

ただ、Windowsではシンボリックリンク作成時に少し気を使う場面があります。

Windowsのシンボリックリンクでは権限を意識する場面がある

以前、シンボリックリンクを作ろうとした際に、次のようなエラーに遭遇しました。

You do not have sufficient privilege to perform this operation.

Windowsでは、シンボリックリンクの作成に権限が関係します。

環境によっては管理者権限やDeveloper Modeなどを意識する必要があります。

Agent Skillsを共有したいだけなのに、

スキルを共有したい
↓
シンボリックリンクを作る
↓
権限エラー
↓
管理者権限？
↓
Developer Mode？

と考えることが増えてしまいます。

今回必要なのは単純なディレクトリ参照なので、Windowsネイティブのジャンクションを使った方が、自分の環境では分かりやすいと感じました。

現在の作成方法

現在は .agent/skills を正本として、Claude CodeとCodexのスキルディレクトリをジャンクションにしています。

まず、スキル本体を配置します。

.agent/
└── skills/
    ├── code-review/
    │   └── SKILL.md
    ├── impact-analysis/
    │   └── SKILL.md
    └── technical-blog/
        └── SKILL.md

そしてコマンドプロンプトからジャンクションを作成します。

mklink /J ".claude\skills" ".agent\skills"

Codex側も同じです。

mklink /J ".codex\skills" ".agent\skills"

これで、

.agent/skills

を編集すると、

.claude/skills
.codex/skills

の両方から同じ内容が見えるようになります。

スキルそのものをコピーする必要はありません。

スキルの「正本を1つにする」という設計は変わらない

今回変更したのは、あくまで参照方法です。

スキル管理について一番重要だと考えている部分は前回から変わっていません。

.agent/skills
        │
        ├── Claude Code
        │
        └── Codex

という構造にして、

Agent Skillsそのものと、各AIエージェント固有の設定を分離する

という考え方です。

例えば、

.agent/skills/

にはAgent Skillsとして共有できるものを置く。

一方、

CLAUDE.md

にはClaude Code固有のコンテキストを書く。

AGENTS.md

にはCodex固有のコンテキストを書く。

このように分離しておけば、使用するAIエージェントが増えてもスキルそのものをコピーする必要がありません。

                 ┌─ Claude Code
                 │
.agent/skills ───┼─ Codex
                 │
                 └─ その他のAgent Skills対応ツール

スキルはAgent Skillsという共通部分として扱い、各ツール固有の設定だけを分離する。

最近はこの構成がかなりしっくりきています。

ジャンクションにも制約はある

ここまで見るとジャンクションの方が便利に見えますが、当然制約もあります。

今回使ってみて、特に意識しているのは次の3点です。

Windows環境に依存する

ジャンクションはWindowsのファイルシステム上の仕組みです。

そのため、macOSやLinuxでも同じ構成をそのまま使いたい場合には向いていません。

複数OSをまたいで共通の仕組みにしたいのであれば、シンボリックリンクの方が考えやすいです。

リモート共有には向いていない

ジャンクションはローカルディレクトリを参照する用途に向いています。

一方で、ネットワーク共有上のディレクトリをターゲットとして使う用途には適していません。

今回のように同一PC内の、

.agent/skills

を、

.claude/skills
.codex/skills

から参照するだけであれば問題ありません。

リポジトリをコピー・cloneしたら再設定が必要になる

個人的に、実際の運用ではここがかなり重要なポイントだと感じています。

ジャンクションは、ソースコードそのものではなくWindows上のファイルシステムに作られる参照関係です。

そのため、リポジトリを別の場所へコピーしたからといって、その参照関係まで必ずそのまま引き継がれるとは限りません。

例えば、

C:\work\my-project

で、

.claude/skills
↓
.agent/skills

というジャンクションを作っていたとします。

そのリポジトリを、

C:\work\my-project-copy

へコピーした場合、コピー先でも同じジャンクション構成が自動的に再現されるものとして扱わない方が安全です。

また、別PCでGitHubから、

git clone

した場合も、cloneしただけでジャンクションが自動的に作成されるわけではありません。

そのため、clone後にはもう一度、

mklink /J ".claude\skills" ".agent\skills"
mklink /J ".codex\skills" ".agent\skills"

を実行する必要があります。

この点はジャンクションを使ううえで明確な制約です。

ジャンクションは「ソース」ではなく「環境セットアップ」と考える

この制約を踏まえてからは、ジャンクションをリポジトリの一部というよりも、開発環境のセットアップ処理として考えるようになりました。

例えば、新しいPCで開発を始める場合は次のような流れです。

git clone
    ↓
依存パッケージをインストール
    ↓
環境変数を設定
    ↓
Agent Skills用のジャンクションを作成

npm install や .env の設定と同じように、

このプロジェクトを動かすために最初に行うローカル環境のセットアップ

という位置づけです。

このように考えると、Gitでジャンクションそのものをどう管理するかに悩む必要もなくなります。

Gitでは、

.agent/skills

にあるスキル本体だけを管理する。

そして各開発環境では、

.claude/skills
.codex/skills

のジャンクションだけをローカルで作成する。

この役割分担が分かりやすいと感じています。

セットアップ方法はREADMEに残しておく

ただし、毎回コマンドを覚えておくのは面倒です。

そのため、READMEなどにセットアップ方法を残しておくと便利です。

例えば次のようにします。

## Agent Skillsのセットアップ

Windowsではプロジェクトルートで以下を実行する。

```bat
mklink /J ".claude\skills" ".agent\skills"
mklink /J ".codex\skills" ".agent\skills"

これだけでも、新しいPCにcloneしたときに、

> あれ、Claude Codeからスキルが認識されない

となる可能性を減らせます。

## セットアップスクリプトにしてもよさそう

さらに運用するリポジトリが増えてきた場合は、セットアップ処理そのものをスクリプトにする方法もあります。

例えば、

```text
scripts/
└── setup-skills.bat

を用意します。

中身はシンプルです。

@echo off

mklink /J ".claude\skills" ".agent\skills"
mklink /J ".codex\skills" ".agent\skills"

echo Agent Skills setup completed.

新しい環境では、

scripts\setup-skills.bat

を実行するだけです。

こうしておけば、ジャンクションそのものはGit管理しなくても、

ジャンクションを作成する手順はGit管理できる

ようになります。

個人的にはこの形がかなり相性が良いと思っています。

前回の記事から変わったこと

前回の記事では、

mklink /D ".claude\skills" ".agent\skills"
mklink /D ".codex\skills" ".agent\skills"

としていました。

現在は、

mklink /J ".claude\skills" ".agent\skills"
mklink /J ".codex\skills" ".agent\skills"

としています。

変更点だけ見れば、/D から /J に変えただけです。

しかし、実際に運用してみると考え方も少し変わりました。

以前は、

Agent Skillsを共有する
=
リンクを作る

くらいに考えていました。

現在は、

Agent Skillsの正本を決める
        ↓
各AIエージェントから参照する
        ↓
参照方法は環境に合わせて選ぶ

と考えています。

つまり、

.agent/skillsを正本にする

という設計と、

シンボリックリンクを使う
ジャンクションを使う

という実装方法は別です。

これは少し、プログラミングにおけるインターフェースと実装の分離にも似ています。

Claude Codeから見れば、

.claude/skills

にスキルが存在していればよい。

Codexから見れば、

.codex/skills

にスキルが存在していればよい。

その裏側で、

• コピーしているのか
• シンボリックリンクなのか
• ジャンクションなのか

は、利用する側には関係ありません。

利用側と実現方法を分離して考えることで、環境に応じて実装を変更しやすくなります。

まとめ

以前はClaude CodeとCodexのAgent Skillsを共有するためにシンボリックリンクを使っていました。

現在はWindows環境での用途を考え、ジャンクションへ変更しています。

理由をまとめると、

• .agent/skills をスキルの正本にする考え方は変わらない
• .claude/skills と .codex/skills から同じスキルを参照する
• シンボリックリンクでも実現できる
• 今回必要なのはローカルディレクトリの共有だけ
• Windowsではジャンクションでも十分
• シンボリックリンクより用途が限定されている分、今回の構成には合っている
• 一方でWindows依存という制約がある
• リポジトリをコピーしたり git clone したりした場合には再設定が必要
• そのためジャンクションは「ソースコード」ではなく「開発環境セットアップ」として扱う
• READMEやセットアップスクリプトに作成手順を残しておくと管理しやすい

という形です。

シンボリックリンクの方が高機能だからといって、必ずしもシンボリックリンクを使う必要はありません。

必要な機能が「Windows上でローカルのディレクトリを別の場所から参照する」だけなら、ジャンクションは十分実用的です。

ただし、ジャンクションはリポジトリをcloneすれば自動的に再現される仕組みではありません。

そのため、

.agent/skills

をGitで管理し、

.claude/skills
.codex/skills

は各開発環境のセットアップ時に作成する。

現在は、この運用がAgent Skillsを複数のAIコーディングエージェントで共有する方法として、一番分かりやすいと感じています。