AI駆動開発におけるスキル作成の効率化および効果の最適化について
はじめまして！DP向上部の朱です。インフォマートに入社して1年2か月です。
主にフロントエンドを担当しております。
今はAI駆動開発におけるフロントエンドのプロンプトセットを整備しています。この中で特にスキル（Skills）について、どのように作成すれば最大限の効果を引き出せるか試行錯誤しており、せっかく溜まってきたスキル作成の効率化や効果の最適化の知見を記事にしてみようと思いました。
※エージェント（Agent）ごとにスキルの実装標準が多少異なりますが、本稿ではGitHub Copilotの標準仕様に準ずるものとします。
スキルの基本
スキルとは
まだ馴染みがない方もいらっしゃるかと思いますのでまず簡単に紹介します。
スキルとは、AIエージェントの機能を専門知識やワークフローで拡張するための、スクリプト、およびリソースをまとめたフォルダのことです。
フォルダの構成は以下のイメージです。
スキルの核心は、SKILL.md ファイルであり、その中にはメタデータ（最低限 name と description）と、エージェントに特定のタスクを実行させるための指示（プロンプト）が含まれています。
また、スキルにはスクリプト、参照資料、テンプレートなどを同梱することも可能です。
スキルの仕組み
スキルは、コンテキストを効率的に管理するために「段階的開示（Progressive Disclosure）」という仕組みとなっています。
発見: エージェントは起動時、各スキルのnameとdescriptionのみを読み込みます。これは、そのスキルが関連しそうかどうかを判断するのに最低限必要な情報です。
アクティブ化: タスクがスキルのdescriptionと一致すると、エージェントは SKILL.md 全体をコンテキストに読み込みます。
実行: エージェントはSKILL.md内の指示に従い、必要に応じてreferencesをロードしたり、scriptsのコードを実行したりします。
SKILL.mdの構成について
SKILL.mdファイルは、冒頭にYAMLフロントマター（frontmatter）を記述し、その後にMarkdown形式のコンテンツを続ける構成になります。
YAMLフロントマター
YAMLフロントマターに下記のフィールドが含まれています。
オプションフィールド付きの例：
コンテンツ
コンテンツは、スキルがアクティブ化されたらエージェントが従うべき指示の内容となります。Markdown形式で記述はしますが、その構成に特に制約はありません。
コンテンツ例：
以上、スキルの基本について解説しました。
次は、スキルの作成の効率化について紹介します。
スキル作成の効率化
SKILLファイルを一から手書きすることは可能ですが、より効率的なのはエージェント自身に書かせることです。
ここでよくある「ハマりどころ」は、ドメイン固有のコンテキストを与えずに、LLMの既存知識のみに頼ってスキルを生成させてしまうことです。その結果、「適切にエラーを処理する」「認証のベストプラクティスに従う」といった、曖昧で汎用的な手順ばかりが生成されてしまいます。価値のあるスキルの作成に有益なのは、特定のAPIパターンやエッジケース、プロジェクト固有の規約などが挙げられます。
さて、上記観点を踏まえて、エージェントにスキルを書かせるのは、以下2つのアプローチがあります。
実作業から抽出
まずはエージェントとの対話を通じて、実際のタスクを完遂させましょう。その過程で提供したコンテキストや修正、自分好みの指示などをエージェントに記憶させます。
タスク完了後、これまでのやり取りをベースに、エージェントにまとめてスキルを書かせます。
/create-skillコマンドを叩いて、スキルを作成するためのスキルを利用するのもよいでしょう。
既存から抽出
既存の成果物がある場合は、それをLLMに読み込ませて「スキル」として定義することも可能で、一般的なベストプラクティスに基づいて作成されたスキルよりも効果的になります。
なぜなら、そこにはチーム独自のスキーマや過去の失敗パターン、具体的な復旧手順などが反映されており、スキル作成において重要なインプットとなるのは、汎用的な情報ではなく、プロジェクト固有の知識なのです。
スキル効果の最適化
以上、効率的なスキル作成方法について解説しました。次は、スキルを最適化するにあたり意識すべき改善ポイントと注意点について紹介します。
不足の補完と既知の省略
「スキル」に記述する内容は、「エージェントがその記載なしには知り得ないこと」に焦点を当ててください。
具体的には、プロジェクト固有の規約や暗黙のルール、ドメイン特有の手順、一見しただけでは判別できないエッジケース、使用すべき特定のツールやAPIなどがこれに該当します。
反対に、PDFの定義やHTTPの仕組み、一般的なデータベースマイグレーションの手法など、公知の情報について説明する必要はありません。
「これがなくても、エージェントは正しく実行できる」という記載は削除すべきです。
段階的開示を用いてスキルを構造化
`SKILL.md` のコンテンツは、500行かつ5,000トークン以内に収めることが推奨されています。ここには、エージェントがタスクの完遂に必要とする「コアな指示」だけを記述し、それ以上記載が必要な場合は、参照資料(references/xxxxx)として別ファイルに切り出して、それを参照する形で記載してください。
前でも説明しましたが、スキルは、コンテキストを効率的に管理するために「段階的開示」という仕組みとなってるため、「段階」条件の提示が大事です。
例：
これにより、エージェントは最初からではなく、必要に応じて参照資料を読み込むことができます。これは、「段階的開示」という仕組みの狙いになります。
選択肢よりデフォルトを提示
複数のツールや手法が機能する場合は、それらを選択肢として提示するのではなく、1つを指定し、残りを代替案としてください。
「ハマりどころ」の提示
スキルの最も価値が高いコンテンツになります。
これは、エージェントが持っている一般的な知識で通用しない、そのプロジェクト固有の知識を指します。
例：
上記の例のように、エージェントがなかなか気づけないプロジェクトの暗黙ルール論理削除を「ハマりどころ」に記載することで、ミスによる手戻り発生の減少とスキル精度の向上ができます。
エージェントが間違えた実装など、その修正内容を含めて「ハマりどころ」に追加することで、スキルの改善にとても有効です。
チェックリストとバリデーション
スキルの記載にチェックリストを提供することで、エージェントは進捗を正確に把握し、ステップの飛ばしを防ぐことができます。
特にステップ間に依存関係があったり、検証プロセスが必要なタスクに対して効果的です。
例：
さらに、バリデーションで結果を確認するような指示を出したらよいです。
バリデーションは無限ループにならないような仕組みを入れるとよいです。
例：
同じエラーで5回失敗したらユーザーに確認してください。
descriptionの最適化
スキルは、アクティブ化されて初めてその価値を発揮します。
そのため、エージェントが「与えられたタスクに対してそのスキルをロードすべきか」を判断する際、description（説明文）は主要な判断基準となります。
この説明が不足していれば、本来必要なスキルが呼び出されず、逆に説明が広すぎると、不要なスキルまでアクティブ化されてしまいます。
したがって、スキルの役割をdescriptionへ適切に記述することが極めて重要です。
エージェントは通常、「自分の能力では対処できないタスク」のみ、スキルを参照します。
例：「このPDFを読んで」といった単純な依頼の場合、たとえdescriptionが一致であっても、PDFスキルがアクティブ化されないことがあります。これは、エージェントが標準機能だけで対応できると判断するからです。
descriptionの作成には、以下のポイントがあります。
命令形を用いる
「このスキルは～をします」という説明的な表現だけではなく、「～のときにはこのスキルを使用して」という、エージェントへの指示として記述してください。エージェントは「今動くべきかどうか」を判断しているため、いつ行動すべきかを明確に伝えます。
実装ではなく「ユーザーの意図」にフォーカスする
スキルの内部的な仕組みではなく、ユーザーが何を達成しようとしているかを記述してください。
エージェントは、ユーザーのプロンプトとdescriptionを照らし合わせて判断します。
あえて「強気」に書く
そのスキルが適用されるコンテキストを明示的にリストアップしてください。
ユーザーがドメイン名を直接口にしない場合も想定します。
簡潔に保つ
仕様上の制限は1024文字以内ですが、スキルの内容をカバーしつつ、多くのスキルを読み込んでもコンテキストを圧迫しない程度に抑えたらよいでしょう。
まとめ
以上、スキル作成の効率化や効果の最適化について解説しました。
主に以下のポイントを押さえていただけると嬉しいです。
スキルは、タスク解決に至るまでのコンテキストや、既存プロジェクト内の成果物など、実務経験から生成してください。
スキルに書く内容は、「エージェントがこの記載なしで知り得ないこと」に焦点を当ててください。
例：
プロジェクト固有の規約、暗黙ルール
ドメイン特有の手順
一見しただけでは分からないエッジケース
使用すべき特定のツールやAPIなど
3.段階的開示を意識してスキルを構造化してください
例：
XXXXXの結果は、scripts/xxxxxを実行して取得してください。
XXXXXの場合は、references/xxxxxを読み込んで、参照してください。
XXXXXの出力は、assets/xxxxxのテンプレートの構造に従って行ってください。
スキルは、曖昧より具体的、冗長より簡潔に記載してください。
最後ですが、スキルは、一回作成して終わりではなく、「実行、検証、修正」のサイクルを通じて洗練させていくことが重要です。
実際に使用してみたフィードバックを反映し続けることで、スキルはより実用的で堅牢なものへと進化していくでしょう。
参考リンク
https://github.com/agentskills/agentskills
https://agentskills.io/
《お知らせ》
インフォマートでは、ともに開発するメンバーを募集しています。
ご興味のある方は、ぜひ採用サイトをご覧ください。
たくさんのご応募をお待ちしております！
