作者注：AI Agent開発における.agentsと.claude設定フォルダの役割の違い、Skillsの格納規則、ディレクトリ構造の比較、およびAGENTS.mdとCLAUDE.mdの適用シーンについての詳細解説
AI Agentの開発がますます注目を集める中、プロジェクトのルートディレクトリには.agents、.claude、.cursorといった様々な設定フォルダが出現しています。中でも.agentsと.claudeはどちらもSkillsを配置できますが、その役割、設計思想、適用範囲は全く異なります。不適切な場所にSkillsを配置すると、軽微な場合はSkillsが機能しない、深刻な場合はチーム開発時に設定が競合するといった問題が発生する可能性があります。本稿では、根本的な設計から掘り下げ、両者の核心的な違いとベストプラクティスを明確に解説します。
コアバリュー: 本稿を読むことで、Skillsを.agentsに配置すべきか、.claudeに配置すべきかが明確になり、マルチツールチームにおけるAgent設定の効率的な管理方法を理解できます。
.agents と .claude フォルダの核心ポイント
まず最も核心的な質問に答えます。これらの2つのフォルダは競合関係にあるのではなく、異なる階層の設定体系です。
| 比較項目 | .claude/ フォルダ |
.agents/ フォルダ |
|---|---|---|
| 帰属 | Anthropic（Claude Code 専用） | Agentic AI 財団 / Linux 財団 |
| 位置づけ | Claude Code のプロジェクト設定ディレクトリ | ツールに依存しない Agent 設定標準 |
| Skills 形式 | SKILL.md（Markdown + YAML フロントマター） |
SKILL.yaml（純粋な YAML） |
| 成熟度 | 本番稼働準備完了、Claude Code が正式サポート | 規格策定中（Work In Progress） |
| クロスツールサポート | Claude Code のみ | すべての AI Agent ツールを対象とした設計目標 |
.agents と .claude フォルダのデザイン思想の違い
これら2つのフォルダの根本的な違いは、デザイン哲学にあります。
.claude/ は「専用の深い統合」という考え方です。Claude Code 専用にカスタマイズされており、Skills、Subagents、Hooks、Permissions などの完全な機能を提供し、Claude Code のツールチェーンと深く結びついています。利点は機能が充実しており、すぐに使えることです。代償として、Claude Code エコシステムにロックインされます。
.agents/ は「クロスツール汎用標準」という考え方です。これは、.editorconfig がエディタにとってそうであるように、すべての AI Agent ツールが読み取れる設定仕様を定義しようとするものです。利点は、1つの設定で複数のツールに汎用的に使えることです。代償として、仕様はまだ進化中であり、各ツールのサポートレベルは異なります。
これら2つは、同じプロジェクト内で共存させることが可能です。Claude Code 専用の深い設定は .claude/ に、クロスツールで再利用可能な汎用設定は .agents/ に配置します。
.claude フォルダの完全なディレクトリ構造
まず、Claude Code ネイティブの .claude/ フォルダを見てみましょう。これが現在最も成熟した実装です。
.claude フォルダのディレクトリ構造詳細
.claude/
├── CLAUDE.md # プロジェクトの指示（ルートディレクトリの CLAUDE.md を代替）
├── settings.json # プロジェクト設定（git にコミット、チームで共有）
├── settings.local.json # ローカル設定（gitignore、個人設定）
├── skills/ # Skills のディレクトリ
│ └── <skill-name>/
│ ├── SKILL.md # Skill 定義ファイル（必須）
│ ├── scripts/ # 補助スクリプト
│ ├── references/ # 参考資料
│ └── templates/ # テンプレートファイル
├── agents/ # サブエージェントの定義
│ └── <agent-name>.md # サブエージェント定義ファイル
├── commands/ # 旧バージョンのスラッシュコマンド（skills に統合済み）
│ └── <command-name>.md
└── agent-memory/ # サブエージェントの永続化メモリ
└── <agent-name>/
└── MEMORY.md
また、ユーザーレベルの ~/.claude/ ディレクトリもあり、個人の Skills をここに配置すると、すべてのプロジェクトで有効になります。
~/.claude/
├── CLAUDE.md # ユーザーレベルの指示（プロジェクト横断）
├── settings.json # ユーザーレベルの設定
├── skills/ # 個人 Skills（全プロジェクトで利用可能）
├── agents/ # 個人サブエージェント
└── projects/ # 会話履歴とデータ
.claude フォルダの Skills における SKILL.md 形式
Claude Code の Skills は、Markdown ファイル + YAML フロントマターで定義されます。
---
name: my-skill
description: Skill の説明。Claude がいつトリガーするかを判断するのに役立ちます。
user-invocable: true # ユーザーは /my-skill で呼び出し可能
allowed-tools: Read, Grep # 使用可能なツールを制限
context: fork # 独立したサブエージェントで実行
model: sonnet # モデルのオーバーライド
---
あなたはプロフェッショナルなコードレビューアシスタントです...
（Markdown 形式の Skill 指示）
主要フィールドの説明：
user-invocable: trueの Skill は/slash-commandとして登録されます。context: forkは、メインの会話を汚染せず、独立したコンテキストで実行されることを意味します。allowed-toolsは、Skill が使用できるツールのセットを制限できます。$ARGUMENTS、$0、$1はパラメータ置換をサポートします。
🎯 開発のヒント: Claude Code の Skills システムは、Agent Skills Open Standard (agentskills.io) に準拠しており、Claude Code、Claude API、VS Code Copilot で構文が共通です。
Claude Code で AI アプリケーションを開発する場合は、APIYI apiyi.com から API キーを取得し、複数のモデル呼び出しを一元管理することをお勧めします。
.agents フォルダの完全なディレクトリ構造
.agents/ フォルダの仕様（AGENTS-1 Spec）は Agentic AI Foundation によって管理され、Linux Foundation の下でホストされており、すべての AI コーディングツールが理解できる一般的な設定標準を定義することを目的としています。
.agents フォルダのディレクトリ構造の詳細
.agents/
├── manifest.yaml # 必須：設定レジストリ。利用可能なすべての設定を宣言します。
├── prompts/ # 必須：指示プロンプト
│ ├── base.md # 一般的な Agent の指示
│ ├── project.md # プロジェクト固有の指示
│ └── snippets/ # モジュール化された指示フラグメント
├── modes/ # 必須：動作モード（.claude/agents/ に類似）
│ ├── plan.md # 計画モード
│ ├── code.md # コーディングモード
│ └── review.md # レビューモード
├── policies/ # 必須：セキュリティポリシーと機能制限
├── skills/ # 必須：スキル定義（Agent Skills Spec に準拠）
│ └── <name>/
│ └── SKILL.yaml # YAML 形式のスキル定義
├── scopes/ # 必須：パスレベルのオーバーライド（Monorepo サポート）
├── profiles/ # 必須：名前付き設定のオーバーレイ（dev/ci/staging）
├── schemas/ # 必須：JSON Schema 検証
└── state/ # ローカル状態（git にコミットしない）
├── .gitignore
└── state.yaml
.claude/ の Skills が SKILL.md（Markdown）を使用するのに対し、.agents/ の Skills は SKILL.yaml（プレーン YAML）形式を使用します。
.agents フォルダのユニークな設計
.agents/ 仕様には、.claude/ には存在しないいくつかの概念があります。
- Scopes（スコープ）: Monorepo 内の異なるサブディレクトリに対して異なる設定を定義します。最も具体的なパスが優先的に一致します。
- Profiles（プロファイル）:
dev、ci、prodなどの名前付き設定のオーバーレイをサポートします。環境変数に似ています。 - Policies（ポリシー）: 独立したセキュリティ制限ディレクトリ。
denyルールは常にallowルールをオーバーライドします。 - Determinism（決定性）: 同じ入力は同じ出力を生成する必要があります。外部状態に依存しません。
.agents および .claude フォルダの Skills 格納ルールの比較
これは開発者が最も関心を寄せる実践的な問題です。私の Skills はどこに格納すべきでしょうか？
.agents および .claude フォルダの Skills 比較
| 比較項目 | .claude/skills/ |
.agents/skills/ |
|---|---|---|
| 定義ファイル | SKILL.md（Markdown + YAML frontmatter） |
SKILL.yaml（プレーン YAML） |
| Claude Code サポート | ネイティブサポート、自動検出 | 手動設定が必要、または公式サポート待ち |
| スラッシュコマンド | user-invocable: true で /command が自動登録 |
具体的なツール実装に依存 |
| サブエージェント実行 | context: fork で独立したコンテキストで実行 |
modes/ で設定 |
| モデルオーバーライド | model: sonnet で直接指定 |
profiles/ で設定 |
| ツール制限 | allowed-tools: Read, Grep |
policies/ で設定 |
| 補助ファイル | scripts/、references/、templates/ サブディレクトリ |
実装に依存 |
| パラメータ渡し | $ARGUMENTS、$0、$1 変数置換 |
仕様で明確に定義されていない |
.agents および .claude フォルダの共存方法
実際のプロジェクトでは、両方のフォルダを共存させて補完させることができます。このプロジェクトを例に挙げます。
.claude/skills/ に Claude Code 専用の Skills を格納:
apiyi-article-generator— プロジェクトのテンプレートと仕様に深く統合された記事生成apiyi-svg-generator— プロジェクトの SVG テンプレートに依存する SVG イラスト生成apiyi-content-reviewer— プロジェクトの品質基準を使用したコンテンツレビュー
.agents/skills/ に汎用的なポータブル Skills を格納:
markdown-proxy— Python スクリプトを使用した URL から Markdown への変換取得nano-banana-pro-image-gen— 外部 API を呼び出す画像生成
分割の原則は明確です。Claude Code と深く統合されているものは .claude/ に、他の AI ツールで再利用可能なものは .agents/ に配置します。
🎯 選択の推奨: チームが Claude Code のみを使用している場合は、すべてを
.claude/skills/に配置すれば、機能が最も充実します。
チームメンバーが異なる AI ツール（Cursor、Windsurf、Codex など）を使用している場合、汎用 Skills を.agents/skills/に配置すると、コラボレーションが容易になります。
AI Agent 開発における API 呼び出しは、APIYI apiyi.com を通じて一元管理することをお勧めします。1 つの API キーで複数のモデルをカバーできます。
.agents と .claude の連携指令ファイル比較
Skills フォルダ以外にも、両システムにはそれぞれのプロジェクト指令ファイルが存在します。
CLAUDE.md と AGENTS.md の違い
| 比較項目 | CLAUDE.md | AGENTS.md |
|---|---|---|
| 対応ツール | Claude Code | Claude Code、OpenAI Codex、Google Jules、Cursor、GitHub Copilot など |
| ファイル階層 | ユーザーレベル (~/.claude/) → プロジェクトレベル (./) → サブディレクトリレベル |
プロジェクトレベル (./) → サブディレクトリレベル |
| ローカル上書き | CLAUDE.local.md (gitignore 対象) |
なし |
| 公式標準 | なし (Anthropic 製品ドキュメント) | あり (Linux Foundation 下の Agentic AI Foundation) |
| エコシステム規模 | 成長中 (Next.js、LangChain、Deno などで採用) | 大規模 (n8n 178K stars、llama.cpp 97K stars、Bun 82K stars) |
| 初期化 | Claude Code 内の /init コマンド |
手動作成 |
実際のアドバイス：両方のファイルを共存させることが可能です。CLAUDE.md には Claude Code 専用の指令（Hooks 設定、権限ルールなど）を配置し、AGENTS.md には全ての AI ツールに共通するプロジェクトコンテキスト（ビルドコマンド、コーディング規約、アーキテクチャ説明など）を配置します。
.agents および .claude 連携ファイルのエコシステム概要
| ファイル/ディレクトリ | 所属システム | 用途 | git へのコミット |
|---|---|---|---|
CLAUDE.md |
.claude | Claude Code プロジェクト指令 | はい |
CLAUDE.local.md |
.claude | 個人ローカル指令 | いいえ |
.claude/settings.json |
.claude | 権限、Hooks、MCP | はい |
.claude/settings.local.json |
.claude | 個人ローカル設定 | いいえ |
AGENTS.md |
.agents | 汎用 Agent プロジェクト指令 | はい |
.agents/manifest.yaml |
.agents | 設定レジストリ | はい |
.agents/state/state.yaml |
.agents | ローカル実行状態 | いいえ |
.cursorrules |
Cursor | Cursor 専用ルール | はい |
ヒント: 2026 年の ETH Zurich の研究によると、AI が生成したコンテキストファイルが Agent のパフォーマンスを低下させる場合があるとのことです。そのため、手動で記述し、コードから推測できない非明示的な情報（カスタムツールチェーン、非定型パターンなど）に限定することが推奨されています。
よくある質問
Q1: Claude Code は .agents/skills/ ディレクトリ内のスキルを読み込めますか？
現在、Claude Code はネイティブでは .claude/skills/ からのみスキルを自動検出・ロードします。.agents/skills/ 内のコンテンツは自動的には認識されません。GitHub では、Claude Code が .agents/ ディレクトリをサポートするように求める Issue（#31005）が提出されています。Claude Code でスキルを有効にするには、現在 .claude/skills/ に配置する必要があります。
Q2: .agents フォルダの仕様は成熟していますか？本番プロジェクトに使用できますか？
.agents/ フォルダの仕様（AGENTS-1 Spec）は現在策定中（Work In Progress）ですが、AGENTS.md ファイルは広く採用されています。n8n（178K stars）、llama.cpp（97K stars）、Bun（82K stars）などの大規模オープンソースプロジェクトで使用されています。汎用的な指示ファイルとして AGENTS.md を採用し、.agents/ の完全なディレクトリ構造などの仕様が安定してから使用することをお勧めします。
Q3: チームメンバーが異なるAIツール（Claude Code + Cursor）を使用する場合、設定はどう管理しますか？
階層的な管理をお勧めします。1）AGENTS.md に共通のプロジェクト情報（ビルドコマンド、コーディング規約）を配置し、すべてのツールで読み込めるようにします。2）CLAUDE.md に Claude Code 専用の指示を配置します。3）.cursorrules に Cursor 専用のルールを配置します。共通のスキルは .agents/skills/ に、ツール固有のスキルはそれぞれのディレクトリに配置します。APIYI apiyi.com を通じてチームのAI API呼び出しを統一管理し、1つのプラットフォームですべてのモデルをカバーします。
Q4: SKILL.md と SKILL.yaml のフォーマットの違いは何ですか？
SKILL.md は Claude Code のフォーマットで、Markdown ファイル + YAML フロントマターを使用します。指示部分は Markdown で記述され、人間にとって読みやすいです。SKILL.yaml は .agents/ 仕様のフォーマットで、すべて YAML の構造化定義を使用し、機械による解析が容易です。両者のコア情報（名前、説明、トリガー条件）は同じで、フォーマットが異なります。
まとめ
.agents と .claude フォルダの主な違い：
- 目的の違い:
.claude/は Claude Code 専用のプロジェクト設定ディレクトリで、すべての Claude Code 機能を深く統合しています。.agents/は Linux Foundation 配下の、ツールに依存しない汎用標準です。 - スキルのフォーマットの違い:
.claude/skills/はSKILL.md（Markdown）を使用し、Claude Code がネイティブでロードします。.agents/skills/はSKILL.yaml（YAML）を使用し、ツールに依存しないように設計されています。 - 共存と補完が可能: Claude Code の高度な機能（Hooks、サブエージェント、権限）は
.claude/に、汎用的で移植可能なスキルは.agents/に配置します。プロジェクトの基本的な指示はAGENTS.mdを使用します。
どちらのフォルダを選択するかは、チームのツールチェーン構成とスキルの移植性に関する要件によって決まります。
AI Agent 開発におけるモデル呼び出しの統一管理には、APIYI apiyi.com の利用をお勧めします。このプラットフォームは、無料枠と統一されたAPIインターフェースを提供し、Claude、GPT、Gemini などの主要モデルへのワンストップアクセスをサポートします。
📚 参考資料
-
Claude Code Skills 公式ドキュメント: Skills の完全な定義、フォーマット、および使用方法
- リンク:
code.claude.com/docs/en/skills - 説明: SKILL.md のフォーマット、トリガーのルール、およびパラメータの渡し方について理解する
- リンク:
-
Claude Code Sub-agents ドキュメント: Sub-agents の定義と設定方法
- リンク:
code.claude.com/docs/en/sub-agents - 説明:
.claude/agents/ディレクトリ内のファイルフォーマットについて理解する
- リンク:
-
AGENTS.md 公式サイト: クロスツール Agent 指令ファイル規格
- リンク:
agents.md - 説明: AGENTS.md の記述規則とサポートツールのリストについて理解する
- リンク:
-
.agents/フォルダ仕様: AGENTS-1 Spec の完全なディレクトリ構造定義- リンク:
github.com/agentsfolder/spec - 説明: manifest.yaml、modes、policies、scopes の設計について理解する
- リンク:
-
APIYI ドキュメントセンター: AI Agent 開発における統一 API 呼び出し管理
- リンク:
docs.apiyi.com - 説明: マルチモデルの統一インターフェースをサポートし、Agent 開発シーンに適している
- リンク:
著者: APIYI 技術チーム
技術交流: コメント欄での議論を歓迎します。より多くの資料は APIYI の docs.apiyi.com ドキュメントセンターでご覧いただけます。
