Agent Skills 完全ガイド

Transcript

1. Agent Skills 完全ガイド AIエージェントの機能を拡張するためのオープンフォーマット Agent Skills Documentation Copyright MOAI Lab, Inc. All rights reserved. 1
2. Agent Skillsとは？ Agent Skillsは、AIエージェントの機能を専門的な知識やワークフローで拡張するため の軽量でオープンなフォーマットです。 コア: 最小限 SKILL.md というファイルを含むフォルダです。 内容: メタデータ（名前、説明）と、特定のタスクを実行するための指示が含まれ ます。 拡張性: スクリプト、参照資料、テンプレートなどをバンドル可能です。 Agent Skills Documentation Copyright MOAI Lab, Inc. All rights reserved. 2
3. なぜAgent Skillsが必要なのか？ エージェントは賢くなっていますが、実際の仕事を行うための「コンテキスト」が不 足しがちです。 ドメイン専門知識の付与: 法務レビュープロセス、データ分析パイプラインなど、 専門知識を再利用可能な形で提供できます。 反復可能なワークフロー: 複数ステップのタスクを一貫した手順に変えます。 クロスプロダクトでの再利用: 一度作成したスキルは、対応するどのエージェント でも利用可能です。 Agent Skills Documentation Copyright MOAI Lab, Inc. All rights reserved. 3
4. 仕組み（プログレッシブ・ディスクロージャー） エージェントはコンテキストを節約するため、以下の3段階でスキルを読み込みます。 1. Discovery (発見): 起動時に「名前」と「説明」だけを読み込みます（約50〜100 トークン） 。 2. Activation (有効化): タスクがスキルの説明に一致した場合、 SKILL.md の本文をコ ンテキストに読み込みます（推奨5000トークン以下） 。 3. Execution (実行): 指示に従い、必要に応じてバンドルされたスクリプトや参照フ ァイルを読み込みます。 Agent Skills Documentation Copyright MOAI Lab, Inc. All rights reserved. 4
5. 仕様: ディレクトリ構造 スキルは、最低限 SKILL.md を含むディレクトリです。 my-skill/ ├── SKILL.md # 必須: メタデータ + 指示 ├── scripts/ # 任意: 実行可能なコード ├── references/ # 任意: 詳細なドキュメント ├── assets/ # 任意: テンプレートやリソース └── ... Agent Skills Documentation Copyright MOAI Lab, Inc. All rights reserved. 5
6. 仕様: SKILL.md フォーマット SKILL.md はYAMLフロントマターと、それに続くMarkdown本文で構成されます。 --- name: pdf-processing description: PDFからテキストを抽出し、フォームに入力し、ファイルを結合します。 license: Apache-2.0 --- ## PDFからのテキスト抽出 pdfplumberを使用してテキストを抽出します... Agent Skills Documentation Copyright MOAI Lab, Inc. All rights reserved. 6
7. 仕様: Frontmatterの主要フィールド name (必須): 1〜64文字の英小文字、数字、ハイフン。親ディレクトリ名と一致す ること。 description (必須): 最大1024文字。スキルが何をするか、いつ使うべきかを記 述します。 license (任意): ライセンス名。 compatibility (任意): 動作環境の要件（特定の製品、パッケージなど） 。 metadata (任意): 追加のメタデータを格納するキーバリューマップ。 allowed-tools (任意): 事前承認されたツール群（実験的） 。 Agent Skills Documentation Copyright MOAI Lab, Inc. All rights reserved. 7
8. クイックスタート: スキルの作成 VS CodeとCopilotなどで動かす「サイコロを振る」スキルの例: .agents/skills/roll-dice/SKILL.md を作成します。 --- name: roll-dice description: サイコロを振るように頼まれたときに使用します。 --- サイコロを振るには、以下のコマンドを使用します: `bash echo $(( RANDOM % <sides> + 1 )) ` `<sides>` には面数（例：6や20）を入れます。 保存後、エージェントに「d20を振って」と頼むと、このスキルが発動します。 Agent Skills Documentation Copyright MOAI Lab, Inc. All rights reserved. 8
9. スキル作成のベストプラクティス (1) 実際の専門知識から始める 一般的なLLMの知識に頼るのではなく、実際のプロジェクトのアーティファクト（内 部ドキュメント、API仕様、レビューコメントなど）を元にスキルを作成します。 コンテキストを賢く使う エージェントが知らないことだけを書く: HTTPの仕組みなどの一般知識は省き、 プロジェクト固有の規則やエッジケースに集中します。 適度な詳細さ: 全てのエッジケースを網羅するより、簡潔なステップと実例を示す 方が効果的です。長くなる場合は references/ に分割します。 Agent Skills Documentation Copyright MOAI Lab, Inc. All rights reserved. 9
10. スキル作成のベストプラクティス (2) 効果的な指示のパターン Gotchas (罠) セクション: 環境特有の「思い込みによるミス」を防ぐための注意事 項をリスト化します（例: users テーブルは論理削除を使っている、等） 。 出力形式のテンプレート: 特定のフォーマットが必要な場合は、マークダウン等の テンプレートを直接提示します。 チェックリスト: 複数ステップのワークフローでは、進行状況を把握しやすいチェ ックリストを提供します。 計画・検証・実行: 破壊的な操作の前に、計画を作成して検証する手順を組み込み ます。 Agent Skills Documentation Copyright MOAI Lab, Inc. All rights reserved. 10
11. スキル説明文の最適化 (Optimizing descriptions) スキルが発動するかどうかは、 description にかかっています。 命令形で書く: 「このスキルは〜する」ではなく、 「〜のときにこのスキルを使え」 と指示します。 ユーザーの意図に焦点を当てる: 内部の実装ではなく、ユーザーが何を達成したい かを記述します。 テストによる改善: 発動すべきプロンプト群と、発動すべきでないプロンプト群を 用意し、実際にトリガーされるかテストします（過学習を防ぐためTrain/Validation に分割します） 。 Agent Skills Documentation Copyright MOAI Lab, Inc. All rights reserved. 11
12. スキル出力品質の評価 (Evaluating skills) スキルが安定して動作するかを評価・改善するループを回します。 1. テストケースの設計: プロンプト、期待される出力、入力ファイルを含むテストケ ース( evals.json )を作成します。 2. ベースラインとの比較: スキル「あり」と「なし」で同じタスクを実行し、トーク ン数、時間、成功率を比較します。 3. アサーション（検証）: 「JSONとして有効か」 「グラフにラベルがあるか」などの 客観的な検証項目を設け、LLMまたはスクリプトで採点します。 4. レビューと反復: エラーログや人間のレビューを元に、LLMに SKILL.md の改善案 を提案させます。 Agent Skills Documentation Copyright MOAI Lab, Inc. All rights reserved. 12
13. スクリプトの利用 (Using scripts) スキルには再利用可能なスクリプトを同梱（ scripts/ ）できます。 ワンライナー: uvx , npx , deno run , go run などを利用すれば、スクリプトを用 意せずとも直接ツールを実行できます。 自己完結型スクリプト: Python (PEP 723)、Deno、Bun、Rubyの機能を使えば、ス クリプトファイル内に依存関係を記述でき、単一のコマンドで実行可能です。 Agent Skills Documentation Copyright MOAI Lab, Inc. All rights reserved. 13
14. エージェント向けスクリプトの設計 エージェントがスクリプトを扱いやすくするためのルール: 対話型プロンプトを避ける: エージェントは入力を待つプロンプトに対応できずフ リーズします。引数や環境変数で入力を受け取ります。 --help を充実させる: エージェントはヘルプを見て使い方を学びます。 役立つエラーメッセージ: 「無効な入力です」ではなく、 「〜が必要です。オプシ ョンは〜です」と具体的に書きます。 構造化出力: 自由形式のテキストより、JSONやCSVなどの構造化データを出力さ せます。 Agent Skills Documentation Copyright MOAI Lab, Inc. All rights reserved. 14
15. クライアント実装者向け: スキルサポートの追加 自身のエージェント（クライアント）にAgent Skillsを対応させる方法: 1. スキルの発見: プロジェクトの .agents/skills/ やユーザーの ~/.agents/skills/ などをスキャンします。 2. SKILL.md のパース: YAMLフロントマターを読み取り、 name と description を抽 出します（多少のフォーマット違反には寛容に） 。 3. モデルへの開示: システムプロンプトや専用ツールの中に、スキルの名前と説明の 「カタログ」を含めます。 Agent Skills Documentation Copyright MOAI Lab, Inc. All rights reserved. 15
16. クライアント実装者向け: スキルの有効化と管理 4. スキルの有効化: ファイル読み込み: モデルが自身のファイル読み込みツールで SKILL.md を直 接読む方法。 専用ツール: activate_skill のようなツールを用意し、呼び出されたらスキ ル本文（フロントマターを除外などして）を返す方法。 5. コンテキストの管理: 会話が長くなりコンテキストを圧縮する際も、スキル内容は**削除対象から除 外（保護）**し、スキルの効果が途切れないようにします。 Agent Skills Documentation Copyright MOAI Lab, Inc. All rights reserved. 16
17. まとめ Agent Skills は、AIエージェントに専門知識と手順を与える強力でポータブルな手 段です。 プログレッシブ・ディスクロージャーにより、コンテキストを圧迫せずに多数の スキルを待機させられます。 優れたスキルを作るには、具体的な知識、明確なトリガー（説明文） 、反復的な評 価、エージェントフレンドリーなスクリプト設計が重要です。 Agent Skills Documentation Copyright MOAI Lab, Inc. All rights reserved. 17