Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Agent Skills 完全ガイド

Agent Skills 完全ガイド

MIKIO KUBO

May 17, 2026

Transcript

17 slides
  1. Agent Skillsとは? Agent Skillsは、AIエージェントの機能を専門的な知識やワークフローで拡張するため の軽量でオープンなフォーマットです。 コア: 最小限 SKILL.md というファイルを含むフォルダです。 内容:

    メタデータ(名前、説明)と、特定のタスクを実行するための指示が含まれ ます。 拡張性: スクリプト、参照資料、テンプレートなどをバンドル可能です。 Agent Skills Documentation Copyright MOAI Lab, Inc. All rights reserved. 2
  2. 仕組み(プログレッシブ・ディスクロージャー) エージェントはコンテキストを節約するため、以下の3段階でスキルを読み込みます。 1. Discovery (発見): 起動時に「名前」と「説明」だけを読み込みます(約50〜100 トークン) 。 2. Activation

    (有効化): タスクがスキルの説明に一致した場合、 SKILL.md の本文をコ ンテキストに読み込みます(推奨5000トークン以下) 。 3. Execution (実行): 指示に従い、必要に応じてバンドルされたスクリプトや参照フ ァイルを読み込みます。 Agent Skills Documentation Copyright MOAI Lab, Inc. All rights reserved. 4
  3. 仕様: ディレクトリ構造 スキルは、最低限 SKILL.md を含むディレクトリです。 my-skill/ ├── SKILL.md # 必須:

    メタデータ + 指示 ├── scripts/ # 任意: 実行可能なコード ├── references/ # 任意: 詳細なドキュメント ├── assets/ # 任意: テンプレートやリソース └── ... Agent Skills Documentation Copyright MOAI Lab, Inc. All rights reserved. 5
  4. 仕様: 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
  5. 仕様: Frontmatterの主要フィールド name (必須): 1〜64文字の英小文字、数字、ハイフン。親ディレクトリ名と一致す ること。 description (必須): 最大1024文字。スキルが何をするか、いつ使うべきかを記 述します。

    license (任意): ライセンス名。 compatibility (任意): 動作環境の要件(特定の製品、パッケージなど) 。 metadata (任意): 追加のメタデータを格納するキーバリューマップ。 allowed-tools (任意): 事前承認されたツール群(実験的) 。 Agent Skills Documentation Copyright MOAI Lab, Inc. All rights reserved. 7
  6. クイックスタート: スキルの作成 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
  7. スキル作成のベストプラクティス (2) 効果的な指示のパターン Gotchas (罠) セクション: 環境特有の「思い込みによるミス」を防ぐための注意事 項をリスト化します(例: users テーブルは論理削除を使っている、等)

    。 出力形式のテンプレート: 特定のフォーマットが必要な場合は、マークダウン等の テンプレートを直接提示します。 チェックリスト: 複数ステップのワークフローでは、進行状況を把握しやすいチェ ックリストを提供します。 計画・検証・実行: 破壊的な操作の前に、計画を作成して検証する手順を組み込み ます。 Agent Skills Documentation Copyright MOAI Lab, Inc. All rights reserved. 10
  8. スキル説明文の最適化 (Optimizing descriptions) スキルが発動するかどうかは、 description にかかっています。 命令形で書く: 「このスキルは〜する」ではなく、 「〜のときにこのスキルを使え」 と指示します。

    ユーザーの意図に焦点を当てる: 内部の実装ではなく、ユーザーが何を達成したい かを記述します。 テストによる改善: 発動すべきプロンプト群と、発動すべきでないプロンプト群を 用意し、実際にトリガーされるかテストします(過学習を防ぐためTrain/Validation に分割します) 。 Agent Skills Documentation Copyright MOAI Lab, Inc. All rights reserved. 11
  9. スキル出力品質の評価 (Evaluating skills) スキルが安定して動作するかを評価・改善するループを回します。 1. テストケースの設計: プロンプト、期待される出力、入力ファイルを含むテストケ ース( evals.json )を作成します。

    2. ベースラインとの比較: スキル「あり」と「なし」で同じタスクを実行し、トーク ン数、時間、成功率を比較します。 3. アサーション(検証): 「JSONとして有効か」 「グラフにラベルがあるか」などの 客観的な検証項目を設け、LLMまたはスクリプトで採点します。 4. レビューと反復: エラーログや人間のレビューを元に、LLMに SKILL.md の改善案 を提案させます。 Agent Skills Documentation Copyright MOAI Lab, Inc. All rights reserved. 12
  10. スクリプトの利用 (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
  11. クライアント実装者向け: スキルサポートの追加 自身のエージェント(クライアント)に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
  12. クライアント実装者向け: スキルの有効化と管理 4. スキルの有効化: ファイル読み込み: モデルが自身のファイル読み込みツールで SKILL.md を直 接読む方法。 専用ツール:

    activate_skill のようなツールを用意し、呼び出されたらスキ ル本文(フロントマターを除外などして)を返す方法。 5. コンテキストの管理: 会話が長くなりコンテキストを圧縮する際も、スキル内容は**削除対象から除 外(保護)**し、スキルの効果が途切れないようにします。 Agent Skills Documentation Copyright MOAI Lab, Inc. All rights reserved. 16

More Decks by MIKIO KUBO

Other Decks in Business