結局SKILL.mdってどこに置けばいいの？

Agent Skillsのお話

以前は、AIエージェントに向けたリポジトリ固有のルールや説明は

• README.md
• AGENTS.md
• CLAUDE.md
• GEMINI.md

などの一つのmdファイルにまとめて書いていた。

一方で、近年はエージェントが必要なときだけ使えるものとしてAgent Skillsというものが提唱され、これはSKILL.mdというファイルに記述される。

しかし、こういった設定ファイルの置き場所や使い方はサービスによっても異なり、自分もいまだに混乱することがある。
この記事では

「結局SKILL.mdはどこに置けばいいの？」

という話をしよう。
あわせて、設定ファイルの種類やサービスごとのベストプラクティスも紹介する。

そもそもSkillは何のためにあるのか

先ほども触れたが、以前はAIエージェントに守ってほしいことを README.md や AGENTS.md、CLAUDE.md にまとめて書く、みたいな使い方が多かった。

例えば、

• デプロイ時はこのコマンドを実行する
• PRレビュー時はこの観点を確認する
• このライブラリを使うときはこの手順に従う

みたいな情報を一か所に入れる。
しかし、実際にはこれらの情報全部が常に必要なわけではない。

例えば「デプロイ手順」はデプロイするときしかいらないし、「PRレビューの観点」はレビューするときしかいらない。
これらを毎回エージェントが読み込むと、トークンを大量に消費してしまうし、必要な情報の取捨選択も難しくなる。

そこで使えるのがAgent Skill。
例えばこんな構成にする。

hello-world/
└── SKILL.md

SKILL.md

---
name: hello-world
description: Responds with "Hello, world!" when the user asks for a greeting, including "挨拶して".
---

# Hello World

When the user asks for a greeting, respond with exactly:

Hello, world!

これは、エージェントに「挨拶して」というとHello, world!を返してくれるスキルだ。
実務においてはデプロイやレビューなど、特定の作業に特化したスキルをあらかじめ定義しておくことで、必要に応じてエージェントがそのスキルを使ってくれる。

ポイントは、エージェントは最初からスキルの中身を全部読むわけではないということだ。
基本的にはまず name と description を見て、タスクに関係すると判断したときに SKILL.md 本文を読む。

このサンプルのdescriptionを読むと、「挨拶をして」と依頼された場合だけ使うスキルということがわかるので、必要な時のみスキルを読む。
これにより、大量のスキルすべてをエージェントが読む必要がないということだ。

逆に言えば、エージェントが適切なタイミングでスキルを呼び出せるようにするためには、このdescriptionが重要になる。

ここではhello-world/以下はSKILL.mdだけだが、必要に応じてスクリプトなども配置可能だ。
Skillsの細かい使い方は調べればいくらでも記事が出てくるので、これくらいにしておく。

SKILL.mdはどこに置くのか

SKILL.mdの置き場所について、最初にまとめておこう。
2026年8月時点では、おおまかにこうなっている。

製品	プロジェクト内のSkill配置場所
GitHub Copilot	.github/skills/, .agents/skills/, .claude/skills/
OpenAI Codex	.agents/skills/
Claude Code	.claude/skills/
Gemini CLI	.gemini/skills/, .agents/skills/

少しややこしいのだが、SKILL.mdのフォーマット自体は共通でも、置き場所は製品ごとに違ったりする。

GitHub Copilotの場合

GitHub Copilotの設定ファイルは基本的に.github/に置かれる。
skillsも.github/skills/におけばいい。
さっきのhello-worldのSkillsなら.github/skills/hello-world/SKILL.mdといった具合だ。

GitHub CopilotはCodexやClaudeの書き方にも準拠しているため、.agents/skills/, .claude/skills/に配置したSKILL.mdも読み込んでくれる。
いろいろサポートしてくれてていいね。

Codexの場合

Codex関連の設定ファイルは基本的に.codex/に置かれるのだが、skillsは業界標準を意識してか、
.agents/skills/に配置している。
個人的に全サービスがこのように特定のサービス名に依存しない名前に標準化されるといいなと思ってる。
CodexやCopilotの場合は迷ったらとりあえずここに置いておけば良い。

Claudeの場合

Claudeのは基本的に設定ファイルを.claude/にまとめて置く方針で、Skillsの場合も.claude/skills/である。
.agents/には対応していないが、実はAgent Skillsを提唱したのはClaudeの開発元であるAnthropicだったりする。

Gemini CLIの場合

Gemini CLIは、.gemini/skills/だが、.agents/skills/にも対応している。

複数プラットフォームを併用する場合は？

SKILL.mdの置き場所は前述のように、使っている製品に合わせれば良い。
ただ、「CodexとClaude Codeを両方使う」ようなケースだとどうすればいいか迷うかもしれない。
また、GitHub Copilotの設定ファイルをすでに.githubに固めてしまってるケースもあるだろう。

このような場合、たとえば .agents/skills/ にSkillをまとめ、.claude/などからはsymlink（シンボリックリンク）を張るなどの方法がある。
以下のようなイメージだ。

    repository/
    ├── .agents/
    │   └── skills/
    │       └── hello-world/
    │           └── SKILL.md
    └── .claude/
        └── skills/
            └── test-workflow -> ../../.agents/skills/hello-world

これならSkillの中身を複数箇所にコピーしなくていい。
正直このへんはどうするのがベストプラクティスなのかわかってない。

少なくともファイルをコピーするよりはsymlinkを張る方が良いように思える。
（ファイルの二重管理は面倒なので）

正直他にもGeminiやCursorなどサービスごとに扱いを考えるのは面倒なので、ファイルの配置方法についても標準化されてほしいなーと思うところ。
「こうするのが良い！」があったら教えてほしい。

Custom Agentの場合

Skill以外のCustom Agent (Sub Agent)についても製品依存は結構ある。
これまではSkillsについて話してきたが、固有のスキルではなくエージェントの振る舞いまでを定義したい場合は

製品	プロジェクト内のCustom Agent配置場所
GitHub Copilot	.github/agents/reviewer.agent.md
Claude Code	.claude/agents/reviewer.md
Codex	.codex/agents/reviewer.toml
Gemini CLI	.gemini/agents/reviewer.md

という感じにファイルを定義する。

リポジトリ全体の設定は？

README.mdのようにリポジトリ共通の設定をAIエージェント用に書きたい場合は以下：

製品	ファイル
GitHub Copilot	AGENTS.md, .github/copilot-instructions.md
Claude Code	CLAUDE.md
Codex	AGENTS.md
Gemini CLI	GEMINI.md

とりあえずAGENTS.mdを使うような方向性にはあるようだ。

AGENTS.mdに寄せる方法もある。
たとえばCLAUDE.md内に@AGENTS.mdと書いておけば、CLAUDE.mdを前提としたエージェントでもAGENTS.mdの方を読みにいってくれる。

まとめ

• SKILL.mdの置き場所は製品によって違うものの、.agents/skills/が多い
• 基本的には使っているプラットフォームにあわせたベストプラクティスを使っていくのが良さそう