Agent Skills：.claude/skillsと.agents/skillsの設定方法

Claude Code、Codex、Cursor、Gemini CLIで同じリポジトリを使うなら、管理するスキルファイルは .agents/skills/<skill-name>/ にまとめてください。Claude Codeからも参照できるように、.claude/skills/ の下にスキルごとの相対シンボリックリンクを作ります。そのうえで、各クライアントがスキルを検出し、呼び出せることを確認してからチーム全体に展開します。

この構成なら、クライアントごとに探索ルールが違っていても、編集する手順書は同じコピーを使えます。Claude Codeしか使わないチームなら、既存の .claude/skills/ のままで構いません。ディレクトリを移す意味があるのは、別のクライアントでも同じスキルを利用したい場合です。

AAIFへの移管でディレクトリ名は統一されたのか

標準の受け入れ先はAAIFになりましたが、スキルを探す場所は引き続き各クライアントが決めます。Anthropicは2026年10月22日に寄贈を発表し、AAIFもAgent Skillsをホストするプロジェクトとして受け入れました。

クライアント実装ガイドは、スキルを置く親ディレクトリを仕様の要件に含めないと明記しています。相互運用のため、クライアント独自のディレクトリに加えて .agents/skills/ の利用を検討するよう勧めています。ただし、この推奨によって既存のすべてのクライアントが自動的にそのパスを探索するようになるわけではありません。

持ち運べる単位は、SKILL.md と、その冒頭に置くYAMLメタデータ、Markdownの指示を含むディレクトリです。フォーマット仕様では name と description が必須で、必要に応じて補助リソースも同梱できます。呼び出し構文、スクリプトの実行環境、権限は利用するクライアントに依存します。特に allowed-tools は実験的な項目で、実装ごとに対応が異なるため、共通の権限ポリシーとして扱うことはできません。

各ツールはどのパスを探索するのか

ローカルファイルシステムでは、次の文書化された探索先を使ってください。このガイドのパスと操作方法は、2026-10-26 時点の公式ドキュメントに基づいています。ここで使う配置にするには、各パスの末尾に <skill-name>/SKILL.md を付けます。

ツール	リポジトリ内の探索先	ユーザー用の探索先	共有リポジトリでの使い方
Claude Code	`.claude/skills/`	`~/.claude/skills/`	`.claude/skills/` から共有ディレクトリへ、スキルごとにリンクを作る。
Codex CLIとIDE拡張	`.agents/skills/`	`~/.agents/skills/`	共有ディレクトリを直接読み込む。
Cursor Agent	`.agents/skills/`、`.cursor/skills/`。互換性のため `.claude/skills/` と `.codex/skills/` も探索	`~/` の下にある同じ4種類のディレクトリ	`.agents/skills/` を使う。Cursor用の追加リンクは不要。
Gemini CLI	`.agents/skills/` と `.gemini/skills/`	`~/.agents/skills/` と `~/.gemini/skills/`	`.agents/skills/` を直接読み込む。同じ適用範囲では `.gemini/skills/` より優先される。

Claude Codeの現行ガイドには、.agents/skills/ を直接探索する機能は記載されておらず、機能追加リクエスト #31005も現在オープンです。一方、上記のCodexとGeminiのガイドでは、.claude/skills/ は探索先に挙げられていません。どちらのディレクトリでもすべてのクライアントで代用できるとは考えず、文書化されたパスを利用してください。

これらはローカルでスキルを検出するためのパスです。ノートPCのホームディレクトリに置いたスキルが、リモートのワーカーや新しく作ったコンテナにも自動で用意されるわけではありません。実行先の環境にも必要なファイルを渡す必要があります。

共有スキルとClaude Code用リンクを作る

スキル一式は .agents/skills/ に保存し、そのディレクトリ全体へのリンクを作ります。こうすれば、後から追加するスクリプトや参考資料も同じリンクから参照できます。スキルごとにリンクを作る方式なら、Claude専用の既存スキルを同じ場所に残す余地もあります。

事前にGitを用意し、クライアントをインストールして認証を済ませ、そのリポジトリで作業できる状態にしてください。このファイル配置の設定に、新しいAPI認証情報は必要ありません。ただし、通常のクライアント利用条件やツール実行権限は引き続き適用されます。

共通フォーマットでスキルを書く

エディターで .agents/skills/review-staged/SKILL.md を作成し、必要であれば親ディレクトリも作ってください。同名のスキルがすでにある場合は別の名前を選び、ディレクトリ名、冒頭のメタデータ、コマンドを一貫して変更します。

次の内容をファイル全体として貼り付けます。

---
name: review-staged
description: "Review staged Git changes for correctness before a commit. Use when the user asks to review the Git index or staged changes."
---

Begin the answer with `Skill loaded: review-staged`.

1. Locate the repository root with `git rev-parse --show-toplevel`.
   Run all following commands from that directory.
2. Run `git diff --cached --name-only`. If it prints no paths,
   report `No staged changes.` and stop.
3. Run `git diff --cached --check` and `git diff --cached --`.
   Treat a nonzero `--check` exit as evidence to report, not a reason
   to skip reading the diff.
4. Read relevant files as needed. Report concrete correctness issues
   with file and line references. Separate confirmed issues from questions.
5. Finish with suggested verification commands. Do not claim they ran.

Do not edit files, stage changes, or create a commit.

この手順がレビューするのはGitのインデックス、つまり次のコミットに向けてステージした変更です。Gitのdiffリファレンスには、その比較を行う --cached と、空白文字のエラーや競合マーカーを検出する --check が説明されています。この例はクライアント固有のプロンプト展開に頼らず、通常のコマンドを実行するようエージェントに指示します。

macOSまたはLinuxでBashからリンクを追加する

このスキルへの相対シンボリックリンクを作ってください。Claude Codeは、シンボリックリンクになっているスキルディレクトリへの対応を明記しています。

対象のGitリポジトリ内であれば、どのディレクトリからでも次のコードを Bash で実行できます。

(
  set -eu
  cd "$(git rev-parse --show-toplevel)"
  test -f .agents/skills/review-staged/SKILL.md
  mkdir -p .claude/skills

  skill_link=.claude/skills/review-staged
  if [ -e "$skill_link" ] || [ -L "$skill_link" ]; then
    printf '%s\n' "Already exists: $skill_link" >&2
    exit 1
  fi

  ln -s ../../.agents/skills/review-staged "$skill_link"
  test -L "$skill_link"
  test -f "$skill_link/SKILL.md"
  readlink "$skill_link"
)

想定する出力は ../../.agents/skills/review-staged、終了ステータスは 0 です。2つの .. はリンクの親ディレクトリである .claude/skills/ を基準に解釈され、リポジトリのルートまで戻ります。

リンクを作るパスにすでに何か存在する場合は、変更する前に内容を確認してください。正しいリンクならそのまま使い、実際のスキルディレクトリがあるなら、管理元のコピーと比較して内容を整理します。このコマンドは、既存のディレクトリも参照先が存在しないリンクも置き換えません。

Windowsで同等のリンクを作る

次の相対ディレクトリリンクを作成するには、PowerShell 7.1以降 を使用してください。MicrosoftのNew-Itemドキュメントに、このバージョン要件が記載されています。Windowsでのシンボリックリンク作成には通常、管理者としての実行、または対応するWindowsで開発者モードが有効になっていることが必要です。

管理元の SKILL.md を保存した状態で、リポジトリのルートから実行します。

New-Item -ItemType Directory -Force -Path '.claude/skills' -ErrorAction Stop | Out-Null
Push-Location '.claude/skills' -ErrorAction Stop
try {
    New-Item -ItemType SymbolicLink -Path 'review-staged' `
        -Target '../../.agents/skills/review-staged' -ErrorAction Stop | Out-Null
    Get-Item 'review-staged' | Select-Object LinkType, Target
    Test-Path 'review-staged/SKILL.md' -PathType Leaf
}
finally {
    Pop-Location
}

LinkType が SymbolicLink になり、ファイルの確認で True が返ることを確認してください。権限不足で作成できない場合は、組織で認められた手順に従って開発者モードを有効にするか、権限を昇格して設定します。

WindowsネイティブのGit BashがLinuxと同じ動作をするとは限りません。Git for Windowsの文書では、デフォルトの ln -s はコピーを作成すると説明されています。PowerShellの手順を使い、作成されたものが本当にリンクかを確認してください。

クローン後には別の問題が起こることもあります。core.symlinks=false の場合、Gitはシンボリックリンクを、リンク先の文字列を含む通常のファイルとしてチェックアウトします。この状態はPowerShellで次のように調べます。

git config --show-origin --get core.symlinks
Get-Item '.claude/skills/review-staged' |
    Select-Object LinkType, Target, PSIsContainer
Test-Path '.claude/skills/review-staged/SKILL.md' -PathType Leaf

リンクのはずのものがテキストファイルなら、その内容を確認してから、そのファイルだけを実際のリンクに置き換えてください。今後クローンする際には、環境が対応するシンボリックリンクのチェックアウトを有効にします。Gitの設定を変更しただけでは、すでにチェックアウトされたテキストファイルがディレクトリへのリンクに変わることはありません。

検出、呼び出し、出力を確認する

まずクライアントのスキル一覧を確認し、次に明示的に呼び出してください。ディスク上にファイルがあるだけでは、クライアントに検出された証拠になりません。また、一覧に項目があっても、その指示本文が読み込まれたとは限りません。

各クライアントでリポジトリのルートを開くか、その場所から起動します。次の操作はBashやPowerShellのプロンプトではなく、クライアントの中で行ってください。

クライアント	検出を確認する方法	この例を呼び出す方法
Claude Code	`/skills` を実行する。必要ならコマンドリファレンスにある `/reload-skills` を使う。	`/review-staged` を送信する。
Codex CLIまたはIDE拡張	`/skills` または `$` のスキル選択画面を開く。	`$review-staged Review my staged changes.` を送信する。
Cursor Agent	Customize → Skills を開き、`/` の選択メニューでスキルを探す。	`review-staged` を選び、ステージ済みの変更のレビューを依頼する。
Gemini CLI	`/skills list` を実行する。ファイル追加後は `/skills reload` を使う。	`Use the review-staged skill to review my staged changes.` と依頼する。

Geminiの文書化された有効化の流れでは、activate_skill と対話形式の同意確認を使います。確認が表示されたら、利用するスキルのディレクトリを承認してください。一覧表示や再読み込みのコマンドは、管理ガイドで説明されています。

想定する回答は Skill loaded: review-staged で始まり、その後に指摘事項と推奨する確認方法が続きます。インデックスが空なら No staged changes. が返ります。この目印の文字列だけで判断せず、有効化やファイル読み取りの記録、実行されたGitコマンドも確認してください。これで手順が読み込まれたことは確かめられますが、レビューの各指摘が正しいことまで保証されるわけではありません。

この構成ではCursorが両方のパスを読み込みます。2026年10月14日のIDE 3.25リリースノートには、同名のスキルがメニューで別々の行に表示される場合があると書かれています。インストール済みのバージョンで重複項目を確認し、すべてのクライアントが同じようにリンクを重複排除するとは考えないでください。

モノレポとCIで配置を揃える

共有スキルはリポジトリのルートに置き、最初の動作確認ではすべてのクライアントをそこから起動してください。特定のパッケージ専用の手順では、スキルの説明と指示に対象パッケージを明記します。各クライアントがネストしたディレクトリを同じように探索することには依存しない構成です。上の例は、意図的にGitインデックス全体をレビューします。

実用的な配置では、それぞれのパスに次の役割を持たせます。

配置先	役割
`.agents/skills/review-staged/SKILL.md`	編集・管理する共有の指示本文。
`.agents/skills/review-staged/references/`	必要に応じてスキルと一緒に配布する参考資料。
`.claude/skills/review-staged`	共有スキルのディレクトリ全体への相対リンク。
`packages/mobile/`	依頼する作業で指定するアプリケーションコード。

適用範囲のルールはクライアントごとに異なります。Claude CodeとCodexは、起動ディレクトリからリポジトリのルートまで親ディレクトリをたどり、それぞれのスキルディレクトリを探します。Cursorには、プロジェクト内のネストしたスキルを、そのディレクトリ配下のファイルに限定して適用する仕組みも文書化されています。Geminiの管理ガイドは、現在のディレクトリを基準としてワークスペースのスキルを説明しています。すべてをルートから起動すれば、これらの違いに頼らず設定を確認できます。

各共有スキルは、スキル探索用ディレクトリの直下にある子ディレクトリに配置してください。Geminiの入門ガイドでは、探索する深さがそこまでに制限されています。Cursorが再帰的に探索できても、カテゴリ分け用の階層を追加した配置がそのまま他のクライアントでも使えるとは限りません。

単一のパッケージだけを開いたワークスペースでは、その場所でも検出を確認し、必要に応じて共有スキルをインストールするかリンクを作ってください。より深い場所でリンクを作るときは、ルートに置いたリンクの ../../ をそのまま使わず、リンク先への相対パスを計算し直します。

チームのチェックアウト環境が対応しているなら、管理元のディレクトリと相対シンボリックリンクをコミットに含めます。リンク先はリポジトリ内に収めてください。そうすれば、新しいクローンでも特定の開発者のホームディレクトリにアクセスせず、リンク先を参照できます。

LinuxのCIでチェックアウトした後は、次の Bash のチェックで必要なファイルとリンクを確認できます。

test -f .agents/skills/review-staged/SKILL.md &&
test -L .claude/skills/review-staged &&
test -f .claude/skills/review-staged/SKILL.md

終了ステータスが 0 なら、これらのファイルシステム上の確認が通ったことを意味します。クライアントによる検出と呼び出しは、実際に実行する環境で、前述の手順を使って別途確認する必要があります。

スキルが読み込まれないときは失敗している段階を調べる

プロンプトを何度も変える前に、どの段階で失敗しているかを切り分けて修正してください。次の項目は症状別の確認先です。全員が上から順にすべての設定を変更する手順ではありません。

スキル一覧に出てこない： ワークスペースのルート、ディレクトリ名の綴り、正確なファイル名 SKILL.md を確認します。クライアントが探索するパスを通してファイルを読んでください。管理元のパスでは読めるのにClaude用のパスでは読めないなら、リンクかチェックアウトの状態を修正します。
ファイルは見つかるがメタデータが受け付けられない： YAMLの区切り、空でなく最大 1024 文字の description、ディレクトリ名と一致する name を確認します。名前は小文字・数字・ハイフンによる 1–64 文字とし、先頭や末尾のハイフン、連続するハイフンを避けてください。
新しいファイルがまだ反映されない： 前述のコマンドでClaudeまたはGeminiのスキルを再読み込みします。Codexは変更の自動検出を文書化していますが、反映されなければ再起動します。Cursorで起動時の探索をやり直す必要がある場合は、開き直してください。
Geminiでワークスペースのスキルが見つからない： /permissions trust でフォルダーの信頼設定を確認します。現行の設定リファレンスでは skills.enabled のデフォルトは true ですが、管理者ポリシーでスキルを禁止できます。無効化された設定や信頼の判断は、それぞれに対応する操作から見直してください。
別のスキルが動く： 個人用とプロジェクト用に同名のコピーがないか調べます。Claudeは個人用をプロジェクト用より優先し、Codexは両方を一覧に表示する場合があります。Geminiはワークスペースのスキルをユーザー用より優先します。異なる作業手順には、区別できる名前を付けてください。
一覧にはあるが自動で選ばれない： まず明示的に呼び出します。それで動くなら、どの作業を担当するスキルなのか分かるように説明を改善してください。明確な説明は選択の助けになりますが、すでに正しく検出されているファイルを移動しても、この問題は解決しません。
指示は読み込まれるがコマンドが失敗する： Gitを使えるか、作業ディレクトリは正しいか、どの権限エラーが報告されているかを確認します。ディレクトリ配置を共通化しても、実行環境のインストールやコマンド実行権限の付与まで行われるわけではありません。