An Epicurean

AI Agent (以下Agent) に的確な指令を与えるため、いわゆるハーネスの整備が大事だということは認識されるようになってきた。私たちがAgentに対して打ち込むプロンプトは以下の図のように入力コンテキストの中のごく一部に過ぎない。コンテキストがどの様に組み立てられているかを理解し、適切なコンテキストが組み上げられるようにするためにハーネスを整備したいところだ。

本記事では、ハーネスの土台となるAgentへのインストラクションとSkills等の取り扱いについて整理する。

乱立する指示ファイルフォーマットと混乱

Agentにヒントを与えるための多くの方式やフォーマットが存在する。各ベンダー毎に様々な方法が用意されており、当初はベンダー間の互換性などは当然考慮されていなかった。各ベンダーの試行錯誤の結果、余り使われなくなったものが後方互換のために残されていることもある。その様に、数多くの方式が乱立しており、それが初学者の混乱を招き、不必要な心理的障壁になっている。

ただ、目的を整理すると、大きく以下の2種類に大別される。

インストラクション・ガイドラインの提示
- AGENTS.md, CLAUDE.md, copilot-instructions.md 等
タスクやプロンプトの再利用
- Agent Skills, Slash Commands, Prompts 等

そして、幸いなことに、最近は、オープンスタンダードとしてそれぞれ、AGENTS.mdとAgent Skillsに収束しつつあるため、利用者はまずその2つを意識して活用するのが良い。Hooksなどもあるがコンテキスト構築とは離れる話なのでここでは取り上げない。

オープンスタンダードを求める合理性

一般論として、利用者側にとって各ベンダー独自仕様をそれぞれ追いかけるのは大変だし、徒労だ。ロックインリスクすらある。

オープンスタンダードな仕様を使えるなら、認知負荷を軽減できるし、潰しの効く技術スキルにもなる。乗り換えやすくなることで、サービス選択の自由も確保できる。開発者毎に異なるサービスを使ったり、一人の開発者が複数のサービスを併用しやすくなったりするのだ。また、セキュリティ観点からもオープンな仕様のほうが比較的安全になるという側面もある。

だから、利用者としては、オープンスタンダードな仕様を使えることが望ましいし、そういう規格のサポートに積極的なサービスを使う姿勢を見せることでベンダー側がそれらをサポートするように促す・圧をかけることでロックインリスクを低減できる。

ベンダー側にも思惑がある。単純化すると、トップベンダー、マーケットが飽和した業界の場合は特に独自規格でロックインを図りたがるだろう。また、後続ベンダーや成長業界のベンダーはオープンな規格をサポート、場合によっては自ら提唱して、他社を含めたコミュニティを形成して、シェアの奪還やマーケットの拡大を目論む。そのエコシステムの中で主導権を取り、自分たちに有利な規格にしていきたいとも考えるはずだろう。

その様に、各所の思惑を想像することも技術選定上重要なポイントだ。

縦串の`AGENTS.md`と横串のAgent Skills

話を戻すと、AGENTS.mdとAgent Skillsの2つだけをまず意識すると良いという話だった。この2つは以下のように「縦串」と「横串」として整理できる。

AGENTS.md（縦串）: ファイルツリーに沿ってコンテキストやルールを与える
Agent Skills（横串）: ファイルの位置を問わず、特定の機能を横断的に提供する

AGENTS.md

AGENTS.md は、Agentへのインストラクションのためのオープンフォーマットだ。いわゆる CLAUDE.md や copilot-instructions.md などと同様の内容を記述するファイルだ。もともとOpenAIのCodex CLIの開発で使われていたものがオープンスタンダード化されたもので、既に主要サービスの多くがネイティブサポートしている。GitHub Copilotもサポートしている。

サブディレクトリ配置サポートも嬉しいポイントで、例えば、ルートの AGENTS.md はプロジェクト全体に、docs/AGENTS.md はドキュメントに、src/AGENTS.md はソースコードに適用されると言った構成を取れる。

仕様の議論やアップデートも github.com/agentsmd/agents.md で活発に行われており、例えば、AGENTS.local.mdに関するissueなどがある。

Claude CodeとAGENTS.md

なお、AGENTS.mdは主要ベンダーがサポートしていると書いたが、Claude Codeはサポートに慎重だ。コミュニティからの要望は強く、Feature Request も出ている。

Claude Codeのドキュメント内には、 AGENTS.mdを読まない旨が明示的に記述されており、その代わりに CLAUDE.md 内に @AGENTS.md ディレクティブを記述する方法や ln -s AGENTS.md CLAUDE.md でsymlinkを貼る方法が紹介されている。

Claude Code reads CLAUDE.md, not AGENTS.md.

https://code.claude.com/docs/en/memory

Agent Skills

Agent Skillsはもともと Anthropic社が提唱した規格で、仕様は agentskills.io で公開されている。こちらも仕様の議論やアップデートはGitHub上の github.com/agentskills で行われている。

Agent Skillsは、Agentに特定タスクの専門知識・手順を教えるための仕組みだ。SKILL.md というMarkdownファイルを所定のディレクトリに配置しておけば、Agentが文脈に応じて読み込んで、実行してくれる。

SKILL.md の構造はシンプルで、YAMLフロントマター（name, description） + 本文の構成になっている。例えば、本記事の図を書いているExcalidraw用のスキルとして、excalidraw-diagram-generator というものがあるが、その冒頭は以下のようになっている。

---
name: excalidraw-diagram-generator
description: 'Generate Excalidraw diagrams from natural language descriptions. Use when asked to "create a diagram", "make a flowchart", "visualize a process", "draw a system architecture", "create a mind map", or "generate an Excalidraw file". Supports flowcharts, relationship diagrams, mind maps, and system architecture diagrams. Outputs .excalidraw JSON files that can be opened directly in Excalidraw.'
---

# Excalidraw Diagram Generator

A skill for generating Excalidraw-format diagrams from natural language descriptions. This skill helps create visual representations of processes, systems, relationships, and ideas without manual drawing.
...

スキル配置ディレクトリの優先度は各サービスで異なるが、これも相互運用のための慣例として推奨されている .agents/ ディレクトリを使うのが良いだろう。多くのサービスが対応しているため、複数のAgentを併用して開発している場合でも共通化できるメリットがある。

# プロジェクト固有スキル（リポジトリ内）
.agents/skills/{skill-name}/SKILL.md

# 個人スキル（ホームディレクトリ）
~/.agents/skills/{skill-name}/SKILL.md

カスタムエージェントはどうなる？

GitHub Copilotの .github/agents/*.md やClaude Codeの .claude/agents/*.md 、Codexの.codex/agents/*.toml など特定の役割を与えるカスタムエージェントやサブエージェント呼び出しの仕組みもある。これらの仕様は共通化されていない。

ここで気をつけるべきは、以前有効とされた「あなたは〇〇の専門家です」といったペルソナ指定は、それっぽく振る舞うだけでアウトプット品質はあまり改善しないと認識されつつあることだ。役割やペルソナより、ゴールやタスクを明確に与える方が有効だ。そういう意味でAgent Skillsと用途や記述内容が被るようになってきた。

では、カスタムエージェントはどの様に定義すると良いのか。基本的には処理の記述はAgent Skillsに寄せるのが良い。カスタムエージェントはそのSkillを呼び出したり、モデル名や推論レベルの指定などのサービス固有の設定値を与えるだけの、薄い定義にするのが良いだろう。

ハーネスをソフトウェアとしてシンプルにメンテナンスし続ける

色々書いてきたが、これらのハーネスの土台は重厚に整備しすぎ無い方が良い。何なら最初はなくても良い。ハーネス整備に時間をかけてAIを使わないのは本末転倒だ。最初はAGENTS.mdもSkillsもなくて構わない。

最近のLLMやAgentはかなり賢い。彼らがすでに知っていることやコードベースから読み取れる情報を重複して与える必要はない。余計なトークン消費や、重複・矛盾した情報によってAgentの判断精度が落ちるのを避けるためにも「必要になってから追加する」のが鉄則だ。

AGENTS.md には、リポジトリからは読み取れない情報、もしくはリポジトリからは読み取って欲しくない情報についてヒントを与えるべきだ。前者であれば例えばドメイン知識やポリシー、後者であれば、真似をして欲しくないコードファイルや使ってほしくないライブラリなどだ。コードベースが大きい場合は何らかのサマリ情報を与えても良いが、それも必要になってからで構わないだろう。

Agent Skillsについては、何らかの定型作業や定期的に発生するタスクなどが発生した際に、Skill化を試みるとよいだろう。これも、Agentに「今の作業をAgent Skill化して」と依頼して作ってもらうのが良い。このとき揺らぎを防ぐために決定論的な作業はスクリプト化してしまうのが良い。Skillにはスクリプトを同梱できる仕様もあるので、そのようにAgentに依頼してみましょう。スキルを作る上では、Anthropicが公開している skill-creator というスキルが有用なので、このスキルはインストールしておいて、作成時に参照させたり、作ったスキルをチェックさせたりすると良いでしょう。

このように、公開されている汎用Skillには便利なものも多いが、無闇矢鱈にインストールするのは避けるべきだ。そもそも、現状ではSkillは自分たちの都合に特化したものを作った方が有用になるケースが多い。また、Skillは段階的に読まれるとはいえ、チリツモで多くのコンテキストを消費してしまうのは無駄だ。それに、最近だとSkillには独自のライセンスが同梱されていることもあり、それらの検証も必要だ。また、Skillはとても強力な機能を持つため、信頼性の乏しいSkillを多数インストールすることはセキュリティ上のリスクにもなる。

今や、これらハーネスは新たなソフトウェア形態であり、ソフトウェアとして扱わなければならない。継続的に見直して変化させていく必要があるのだ。不必要になったモノは削除するなどのリファクタリングを行って、メンテナンスしやすいシンプルな状態を保つことが重要だ。

例えば、AGENTS.mdにドメイン知識を記述していたとしても、それの一部を何らかの形式言語で宣言的に記述できたのなら、そちらに切り替えて、AGENTS.mdからは削除してしまうのが良い。

コーディング規約などもコード内で徹底されている状態に置きかえられたのであれば、必要以上にAGENTS.md等に書き込む必要はない。それに、linterなどの決定論的なツールでチェックできるのであれば、そちらに任せた方が良い。

また、少し前のLLMが今ほど賢くなかった頃は、マイクロマネジメント的に逐一手順の指示を与えることが良しと言われていたこともあったが、最近のモデルだと、それをやりすぎると寧ろ精度が落ちるケースがあることも分かってきた。つまり、ティーチング的なアプローチからコーチング的なアプローチが有効になる局面が増えてきたということだ。この様に常識も移り変わっていく。

この様に、プロジェクト内外の状況の変化に応じて、ハーネスは常に見直す必要がある。重厚長大なハーネスを一度作って終わりとは行かないし、それが時と共に足枷に変化してしまうこともある。AI時代の新しい技術的負債と言える。

結局のところ、変化させやすく保つことが肝要だ。肥大化させないこと。定期的に見直すこと。メンテナンスがやりやすいようにすること。理想的にはAgentが自律的にメンテナンスしてくれるようにハーネスを構築する状態を目指したいところだ。

Agent Skillsへの要求の肥大化の課題

ただ、Agent Skillsが強力である反面、何でもSkillにやらせようとなり、期待や責務、役割が肥大化していることは新たな課題と言える。

前述の通り、Agent Skillsは強力な反面、リスクも高く、適切な管理が必要だ。なので、配置場所が .agents/skills 配下に局所化されていること、オープンに仕様が協議されていることはリスクコントロールの観点でも良いことだ。

Agent Skillsに求められる多彩な要求をどの様に分類して管理するかや、サプライチェーン周りはまだ機能や仕様不足であり、エコシステムの成熟が求められるところだ。この辺りの動きについても別途まとめようと思うが、本記事はここでいったん区切りとする。