--- title: 縦串のAGENTS.mdと横串のAgent Skills tags: author: [Masayuki Matsuki](https://docswell.com/user/Songmu) site: [Docswell](https://www.docswell.com/) thumbnail: https://bcdn.docswell.com/page/GJ5MQD4GJ4.jpg?width=480 description: 縦串のAGENTS.mdと横串のAgent Skills by Masayuki Matsuki published: June 06, 26 canonical: https://docswell.com/s/Songmu/KN7VEP-agents-md-and-agent-skills --- # Page. 1 ![Page Image](https://bcdn.docswell.com/page/GJ5MQD4GJ4.jpg) 縦串のAGENTS.md と 横串のAgent Skills Masayuki Matsuki (Songmu) Senior Solutions Engineer GitHub Japan # Page. 2 ![Page Image](https://bcdn.docswell.com/page/LE3WVMGPE5.jpg) Agenda ● Agentへの指示の最適化 ● オープンスタンダード志向 ● AIへの指示ファイル形式多すぎ問題 ● インストラクションファイル (AGENTS.md) ● Agent Skills ● Agent Plugins ● SkillsやPluginsの管理 # Page. 3 ![Page Image](https://bcdn.docswell.com/page/8EDK86137G.jpg) Agentへの指示の最適化 # Page. 4 ![Page Image](https://bcdn.docswell.com/page/V7PK8YQPJ8.jpg) Token Maxxing から Token Optimization へ # Page. 5 ![Page Image](https://bcdn.docswell.com/page/2JVVNG5VJQ.jpg) ハーネスエンジニアリングの重要性向上 Agentへインストラクションやスキルを与える ● 本セッションではハーネスの土台を整える前段階の話をします ● Agentへの指示ファイルの形式やAgent Skillsの話 # Page. 6 ![Page Image](https://bcdn.docswell.com/page/5EGLK861JL.jpg) オープンスタンダード志向 # Page. 7 ![Page Image](https://bcdn.docswell.com/page/4JQYN94N7P.jpg) AI関連情報・アップデート多すぎ問題 ● 各社バラバラの仕様を追いかけるのは大変 ○ ロックインリスクも ● 極力共通化されていて欲しい ○ 開発者はオープンな規格化を求めるべき # Page. 8 ![Page Image](https://bcdn.docswell.com/page/K74WGXQ3E1.jpg) オープンスタンダードを求める合理性 ● 一つの知識を複数のツールやサービスで活用・相互運用・乗り換え可能 ○ ○ 認知負荷軽減 ロックインリスク低減 ● オープンな規格の採用に積極的なツールを選択する ○ ベンダー側にサポート圧をかける # Page. 9 ![Page Image](https://bcdn.docswell.com/page/LJ1YDNPZEG.jpg) ベンダー側の思惑 クローズにしたい・オープンにしたい、様々な思惑が交錯 ● 独自仕様でロックインしてシェアを維持したい ○ 特に成熟業界でのトップベンダー ● オープンなエコシステムを形成してマーケット拡大やシェアの奪還を図りたい ○ ○ 発展途上の業界 複数ベンダーによる連合 ■ その中でのイニシアティブの争い # Page. 10 ![Page Image](https://bcdn.docswell.com/page/GJWGY42672.jpg) ベンダー独自ファイル配置を避けたい開発者 ● 開発におけるツール選択の自由を極力留保したい ○ ○ 不必要なロックインは避けたい OSS開発の場合は特に ● 例えば自分が使わないエディタの設定が置かれていても嬉しくない ○ ○ .vscode, .idea 自分が使わないコーディングエージェントの設定についても同様 # Page. 11 ![Page Image](https://bcdn.docswell.com/page/4EZLX2DR73.jpg) GitHubとAgentHQ ● ● ● ● Copilotは Agentic Coding方面では後発 オープンスタンダードな規格に乗る動きを見せている 3rd party agent機能もある 相互運用性の高さを重要視している印象 # Page. 12 ![Page Image](https://bcdn.docswell.com/page/Y76W4V117V.jpg) GitHub Copilotと相互運用性 ● AGENTS.md サポート ○ ○ .github/copilot-instructions.md の代わりに (何なら CLAUDE.md や GEMINI.md も読む) ○ ○ .github/skills の代わり (何なら .claude/skills も読む) ● .agents/skills サポート ● 参考 ○ ○ Adding repository custom instructions for GitHub Copilot - GitHub Docs Adding agent skills for GitHub Copilot - GitHub Docs # Page. 13 ![Page Image](https://bcdn.docswell.com/page/G75MQD4L74.jpg) カスタムファイル形式多すぎ # Page. 14 ![Page Image](https://bcdn.docswell.com/page/9J29P8V3ER.jpg) Copilotカスタマイズのための各種ファイル ● 参考: Copilot customization cheat sheet - GitHub Docs ● やりたいことは分かるが多すぎて混乱することも 内容 ファイルパス ⭐ リポジトリ全体への指示 .github/copilot-instructions.md, AGENTS.md 全体に自動適用 特定のファイルパスや言語への指示 .github/instructions/*.md 適切に自動適用 定型プロンプトの再利用 .github/prompts/*.prompt.md / コマンド呼び出し カスタムエージェント .github/agents/*.md 自動呼び出し ⭐ Agent Skills .agents/skills/*/SKILL.md 自動呼び出し , / コマンド呼び出し フック機構 .github/hooks/*.json 各種イベント後の自動処理呼び出し MCP設定 .mcp.json # Page. 15 ![Page Image](https://bcdn.docswell.com/page/DEY45638JM.jpg) まずは以下の2つだけ意識すればOK これらに収束していく流れがあり、利用者としてもそれを求めるのが良いのではないか ● インストラクションファイル ○ AGENTS.md に配置 ○ .agents/skills に配置 ● Agent Skills # Page. 16 ![Page Image](https://bcdn.docswell.com/page/VJNYNZV978.jpg) 縦串と横串 ● インストラクション: ファイルツリーに対するコンテキスト・ルール ● Agent Skills: ファイルの位置を問わず、特定の機能を横断的に提供 # Page. 17 ![Page Image](https://bcdn.docswell.com/page/YE9PRZ63J3.jpg) あっても最小限に 最初はインストラクションもskillsも無くても良い ● ハーネス整備に時間をかけてAIを使わないのは本末転倒 ○ 自分で使ってみて経験知・身体知を獲得する ● 無駄なインストラクションやSkillsを作りすぎるのも無駄 ● 最近のLLMはかなり賢い ○ ○ 彼らがすでに知っていることは与えなくて良い コードベースから拾える情報は与えなくて良い ● 余計なトークン消費やハルシネーションリスクを避ける # Page. 18 ![Page Image](https://bcdn.docswell.com/page/GE8DW1ZLED.jpg) 必要になってからインストラクションやSkillsを追加 ● 置き場所は理解しておく ● なんなら、インストラクションやskillsもAIに作ってもらう ○ ○ 「AGENTS.md に追加して」 「今の作業をAgent Skills化して」 ○ チームマネジメントと同じ ● AIに自律的に改善してもらうのが理想 ● 作り過ぎに注意 # Page. 19 ![Page Image](https://bcdn.docswell.com/page/LELMNQDQ7R.jpg) インストラクションファイル (AGENTS.md) # Page. 20 ![Page Image](https://bcdn.docswell.com/page/4JMYX1WKJW.jpg) AGENTS.md ● https://agents.md ● AI Agentへのインストラクションのためのオープンフォーマット ○ ○ OpenAI の Codex CLIで使われていたものをオープンスタンダード化 Copilotも追随してサポート # Page. 21 ![Page Image](https://bcdn.docswell.com/page/PJR9NLY679.jpg) AGENTS.md を積極的に使う ● 記述内容は .github/copilot-instructions.md に書くものと基本的に同じで良い ● 書く量も必要最小限に ● サブディレクトリにも配置できるのはメリット ○ docs/AGENTS.md, src/AGENTS.md 等 # Page. 22 ![Page Image](https://bcdn.docswell.com/page/PEXQNWGDJX.jpg) copilot-instructions.md の使い所 ● Copilot固有のインストラクションを置く場所としては必要 ○ 例えば Copilot Code Review は AGENTS.md をまだ読まない 例: コードレビュー時には必ず日本語でレビューを行ってください。すべてのコメント、提案、説明は日 本語で記述してください。 Copilot Chat上でのやり取りも日本語で行うようにしてください。 # Page. 23 ![Page Image](https://bcdn.docswell.com/page/3EK9NV4DED.jpg) **.instructions.md のパス指定機能 ● ex. applyTo: "docs/**", applyTo: "**/*.ts,**/*.tsx" ● AGENTS.md や Skills に振り分けられるものはそちらに寄せるのが良いのでは ○ ○ applyTo: "docs/**" -> docs/AGENTS.md applyTo: "**/*.ts,**/*.tsx" -> TypeScript用のAgent Skills # Page. 24 ![Page Image](https://bcdn.docswell.com/page/L73WVMLP75.jpg) (備考) 各種インストラクションの適用範囲 各エディタ拡張、CLI, Code Review, Cloud Agent等でサポートされるインストラクションが異なり 複雑 ● 以下を参照 ○ Support for different types of custom instructions - GitHub Docs ● GitHub Copilot app (preview) は Copilot CLIと同等と想像 ● この辺りも統一されていく未来を期待 # Page. 25 ![Page Image](https://bcdn.docswell.com/page/87DK86N3JG.jpg) Claude CodeとAGENTS.md AGENTS.mdは主要ベンダーがネイティブサポートしているがClaude Codeはサポートを避けて いる ● コミュニティからの要望も強い ○ Feature Request: Support AGENTS.md. #6235 - anthropics/claude-code https://code.claude.com/docs/ja/memory#agents-md # Page. 26 ![Page Image](https://bcdn.docswell.com/page/VJPK8Y5PE8.jpg) Agent Skills # Page. 27 ![Page Image](https://bcdn.docswell.com/page/2EVVNGPVEQ.jpg) Agent Skillsとは ● Agentに特定タスクの専門知識・手順を教える機能 ○ .agents/skills/<スキル名>/SKILL.md に配置 ● プロンプトの内容に応じてCopilotが自動的にマッチしたスキルを読み込む ○ slashコマンドでの実行も可 ● カスタムAgentは専門家的なペルソナ、Skillsはそれに道具を渡すイメージ 参考: https://github.github.io/awesome-copilot/learning-hub/what-are-agents-skills-instructi ons/ # Page. 28 ![Page Image](https://bcdn.docswell.com/page/57GLK8P1EL.jpg) Agent Skillsのエコシステム ● オープンスタンダードとして進化中: https://agentskills.io ○ 元々はAnthropic社が提唱、GitHub Copilotも採用している ● 参考 ○ ○ ○ ○ https://claude.com/blog/equipping-agents-for-the-real-world-with-agent-skills https://code.claude.com/docs/ja/skills skill-creatorから学ぶSkill設計と、Orchestration Skillの作り方 What are Agents, Skills, and Instructions # Page. 29 ![Page Image](https://bcdn.docswell.com/page/4EQYN92NJP.jpg) Models, Agents, Skillsの関係概念図 Don't Build Agents, Build Skills Instead – Barry Zhang & Mahesh Murag, Anthropic より ただ、これは出てきた当初の図で、Skills自体が複数のagentを動かすようなオーケストレーターと して動くケースも出てきたので入れ子的になってきてはいる。 # Page. 30 ![Page Image](https://bcdn.docswell.com/page/KJ4WGXL371.jpg) SKILL.mdの書き方 ● ● ● ● YAMLフロントマター（name, description）＋ Markdown本文の構成 description がマッチングのキーになるため、いつ使うかを明記 参考: GitHub Docs: Creating agent skills 参考: VS Code Docs: Agent Skills # Page. 31 ![Page Image](https://bcdn.docswell.com/page/LE1YDNLZ7G.jpg) Skillsへの統合の流れ 各社のカスタマイズファイルがSkillsに統合され、１本化されつつある ● Claude CodeのSlash CommandはSkillsへ ○ Merging Slash Commands into Skills in Claude Code ○ ○ ○ Awesome Copilotリポジトリでは PromptsをSkillsに統合する移行が実施済 Copilot CLIはPrompts未サポート What are Agents, Skills, and Instructions | awesome-copilot ■ "Why skills over prompts" ■ Skillsはリソース同梱・Agent自動発見・クロスプラットフォーム対応で上位互換 ● CopilotもPromptsからSkillsへ Slash CommandもPromptsも使えなくなるわけではなく互換は維持される # Page. 32 ![Page Image](https://bcdn.docswell.com/page/GEWGY4V6J2.jpg) PromptsとSkillsの現状の非互換 model, tools 指定や変数を活用している場合、Skillsへの移行を急がなくても良い。 Prompts Skills Agent自動トリガー ❌ 手動のみ ✅ descriptionでマッチ リソース同梱 ❌ 単一ファイル ✅ scripts/, references/ model / tools 指定 ✅ ❌（仕様に未実装） ${file} 等の変数 ✅ ❌（仕様に未実装） クロスプラットフォーム ❌ Copilot専用 ✅ オープン仕様 # Page. 33 ![Page Image](https://bcdn.docswell.com/page/47ZLX24RJ3.jpg) Agent Skills仕様の議論状況 Promptsにある機能 Skills仕様での状況 関連Issue tools 指定 allowed-tools として存在（experimental） #144 型の明確化 model 指定 未実装 Discussion #150 ${file} 等の変数 未実装 #124 動的コンテキスト注入 # Page. 34 ![Page Image](https://bcdn.docswell.com/page/YJ6W4V31JV.jpg) 自動トリガー周りの制御 ● / コマンドだけで明示的に呼び出したい場合 ○ ○ disable-model-invocation: true でAgent自動トリガーを無効化可能 デフォルトは false ○ ○ user-invocable: false でユーザーからの呼び出しを無効化可能 デフォルトは true ● 逆に / コマンド呼び出しは不要な場合 # Page. 35 ![Page Image](https://bcdn.docswell.com/page/GJ5MQDLLJ4.jpg) PromptsもSlash CommandもSkillsに統合されつつある カスタムAgentsはどうなるか Copilotの .github/agents/CUSTOM-AGENT-NAME.md や Claude Codeの .claude/agents/CUSTOM-AGENT-NAME.md 等、特定のペルソナや専門家の役割を与える ためのファイル ● これもSkillsに寄っていくのではないか (私見) ● ペルソナを指定するプロンプトは余り意味が無いと認識されつつある ○ ○ ○ ex. 「あなたは〇〇の専門家です」 それっぽく振る舞うだけでアウトプット品質はあまり変わらない 関西弁話者などを模してもらって楽しむ分には面白いが ● 役割やペルソナを与えるのではなく、ゴールやタスクを与える方が有用 ○ ○ であれば結局Skillsにすれば良いのでは ちなみにCodexにはカスタムエージェントの機能は無い # Page. 36 ![Page Image](https://bcdn.docswell.com/page/9E29P8L37R.jpg) Skillsを作るか・有物を使うか ● まずは自分や自分たちで作ってみるのも良いのではないか ○ 「今の作業をAgent Skill化して」 ● オープンに公開されている便利なものも多いが ○ 使う場合には安全性やライセンスの検証が必須 絶対ダメ →「便利そうなものをバンバンインストールする」 # Page. 37 ![Page Image](https://bcdn.docswell.com/page/D7Y456Q8EM.jpg) gh skill でのSkillsインストール ● GitHubリポジトリの skills/ ディレクトリに配置されたAgent SkillsをGitHub CLIからイン ストール可能 ○ ○ Manage agent skills with GitHub CLI - GitHub Changelog Copilot用途に限らず利用可能 ● タグやハッシュでのpin留めやアップデートにも対応 ○ リポジトリのコミットやタグによるバージョニング # Page. 38 ![Page Image](https://bcdn.docswell.com/page/VENYNZK9J8.jpg) 課題 ● Skillsは強力である反面リスクもはらむ ○ ○ 安全な配布 ガバナンス ● 管理方法などもまだ未成熟 ○ ○ ○ ○ リリース・パッケージング バージョニング・バージョンロック 階層・名前空間 依存管理・コンフリクト解消 ● 危険だからこそ共通化して業界で解決 ○ ○ リスクの局所化 コミュニティリポジトリ上で議論はされている # Page. 39 ![Page Image](https://bcdn.docswell.com/page/Y79PRZV3E3.jpg) Agent Plugins # Page. 40 ![Page Image](https://bcdn.docswell.com/page/G78DW1PL7D.jpg) Agent Plugins ● 各種カスタムファイルの再利用性を高めるための仕組 ● Agent Skills, Hooks, MCP設定などをパッケージングして配布するための機能 ○ ○ プラグイン自体の定義方法 (plugin.json) 配布のためのマーケットプレイス (marketplace.json) ○ ○ About plugins for GitHub Copilot CLI - GitHub Docs Agent plugins in VS Code (Preview) ● GitHub Copilot CLIで先行実装されていたものがVS Codeにも展開 # Page. 41 ![Page Image](https://bcdn.docswell.com/page/L7LMNQ1QJR.jpg) ディレクトリ構造と plugin.json の中身 Pluginの構造 ● ディレクトリをPluginとして管理する ● plugin.json でプラグインのメタデータや構成を定義 # Page. 42 ![Page Image](https://bcdn.docswell.com/page/4EMYX15KEW.jpg) Claude CodeのPlugin機構とほぼ同様 https://code.claude.com/docs/ja/plugin-marketplaces ● 完全互換ではない # Page. 43 ![Page Image](https://bcdn.docswell.com/page/PER9NL36J9.jpg) Claude CodeのプラグインはCopilotで利用可能 About plugins for GitHub Copilot CLI - GitHub Docs # Page. 44 ![Page Image](https://bcdn.docswell.com/page/P7XQNW4DEX.jpg) Pluginのインストール ● スラッシュコマンドでインストール可能 ○ VSCode, CLI ○ ○ github/copilot-plugins github/awesome-copilot ● Plugin Marketplacesからのインストール ● 標準で 2つのMarketplaceが登録 # Page. 45 ![Page Image](https://bcdn.docswell.com/page/37K9NVZD7D.jpg) 独自マーケットプレイスの作成 ● Gitリポジトリに marketplace.json を配置するだけで作成可能 ○ プライベートリポジトリ可 # Page. 46 ![Page Image](https://bcdn.docswell.com/page/LJ3WVMDPJ5.jpg) SkillsやPluginsの管理 # Page. 47 ![Page Image](https://bcdn.docswell.com/page/8JDK86P3EG.jpg) エンタープライズ向けプラグイン管理 (preview) ● エンタープライズレベルで利用可能なプラグインを管理する機能 ● 現状Preview機能でCLIのみサポート ○ ○ About enterprise-managed plugin standards for Copilot CLI - GitHub Enterprise Cloud Docs Enterprise-managed plugins in GitHub Copilot CLI are now in public preview - GitHub Changelog # Page. 48 ![Page Image](https://bcdn.docswell.com/page/VEPK8YNP78.jpg) Enterprise-managed plugins利用方法 ● 管理用の .github-private リポジトリを作成 ● .github/copilot/settings.json に以下のようなファイルを配置 ● まだ機能的には不十分 ○ Configuring enterprise plugin standards for Copilot CLI - GitHub Enterprise Cloud Docs # Page. 49 ![Page Image](https://bcdn.docswell.com/page/27VVNGKV7Q.jpg) プロジェクト内でのAgent SkillsやPluginsの依存管理 APM - Agent Package Manager https://github.com/microsoft/apm ● apm.yml と言うマニフェストファイルで宣言 ● apm install コマンドでの一元インストール ● apm.lock.yaml でバージョンロック Microsoft orgで公開されているがGitHubとしてまだ強く推している訳では無い # Page. 50 ![Page Image](https://bcdn.docswell.com/page/5JGLK8Q17L.jpg) apm.ymlの例 公式リポジトリより引用 # Page. 51 ![Page Image](https://bcdn.docswell.com/page/47QYN9KNEP.jpg) APM所感 ● こういったものは絶対に必要 ○ ○ やろうとしていることの網羅性も高い 最近のサプライチェーンアタック怖すぎるので… ○ ○ ターゲットによってインストール先を変えるなど 「がんばりすぎ」感もある ■ 仕様を統一していくか・頑張って吸収するのか ● 各AI Agent間の差異を吸収するような機能も備えるが ● コミュニティ・エコシステム発祥というより実装先行 ○ ○ コミュニティにどれくらい受け入れられるかはまだ未知数 最近話を聞くようにはなってきた ● 動作パフォーマンス的にはあまり良くないとも聞く ○ 各Gitリポジトリから取得する設計なので遅くなるのは仕方なさそう ● 動向に注目 ○ 定番ツールが早く何か定着してほしい # Page. 52 ![Page Image](https://bcdn.docswell.com/page/KE4WGXP3J1.jpg) まとめ # Page. 53 ![Page Image](https://bcdn.docswell.com/page/L71YDN9ZJG.jpg) 縦串のAGENTS.md と横串の Agent Skills ● オープンスタンダードな AGENTS.md と .agents/skills への配置が個人的推奨 ○ GitHub Copilotも対応しています ○ ○ APMなども出てきている 複数リポジトリでの設定共有などにも課題感あり ● Agent Skillsやその他アセットのサプライチェーンマネジメントは重要な課題 # Page. 54 ![Page Image](https://bcdn.docswell.com/page/G7WGY4Q6E2.jpg) Thank you