エージェントスキルとは

エージェントスキルとは MOAI Lab June 17, 2026 1 / 19

本スライドの構成 1 エージェントスキルの目的 2 段階的開示と配置場所 3 SKILL.md の構造と仕様 4 作成時のベストプラクティス 5 説明文、評価、スクリプト設計 2 / 19

エージェントスキルの定義 エージェントスキル AI エージェントに専門知識、作業手順、補助ファイルを渡すための単一ディレクトリ [1] 最低限、メタデータと手順を含む SKILL.md を持つ 必要に応じてスクリプト、参考資料、テンプレートを同梱する プロジェクト固有の文脈を、再利用可能で移動可能な形にする 目的は、エージェントの汎用能力を実務手順へ接続すること 3 / 19

• #p19

なぜ必要なのか AI エージェントは汎用的だが、組織固有のルールを最初から知らない 業務では、命名規則、認証方法、データ仕様、出力様式が重要 スキルは、それらをバージョン管理可能なフォルダとして保存する 必要なときだけ読み込めるため、長いプロンプトを常時持たせる必要がない 要点 スキルは、プロンプトではなく、エージェント向けの実務レシピ 4 / 19

段階的開示 段階的開示（Progressive Disclosure） は、必要な情報だけを順に読み込む設計 1 発見（Discovery）: 起動時に名前と説明文だけを読む 2 起動（Activation）: タスクに合う場合に SKILL.md 全体を読む 3 実行（Execution）: スクリプトや参照ファイルを必要に応じて使う 利点 コンテキスト消費を抑えつつ、必要な専門知識を適切な時点で追加できる 5 / 19

代表的な配置先 スコープ パス 用途 プロジェクト プロジェクト ユーザー ユーザー project/.agents/skills/ project/.client/skills/ home/.agents/skills/ home/.client/skills/ 共有スキル 専用スキル 個人用スキル 専用スキル 6 / 19

配置先の選び方 チームで共有するなら、project/.agents/skills/ が基本 個人環境で横断的に使うなら、home/.agents/skills/ が適切 特定ツール専用なら、.client/skills/ 系に分ける スキルとして認識される条件は、サブディレクトリ内に SKILL.md があること 例 home/.agents/skills/pdf-processing/SKILL.md 7 / 19

基本ディレクトリ構造 my-skill/ |-- SKILL.md |-- scripts/ |-- references/ |-- assets/ `-- ... SKILL.md は必須 scripts/ は実行可能な処理を置く場所 references/ は仕様書やスキーマなどの参照資料を置く場所 assets/ はテンプレートや雛形を置く場所 8 / 19

SKILL.md のフロントマター --name: pdf-processing description: PDFファイルからテキストや表を抽出し、 フォーム記入やPDF結合を行う license: MIT compatibility: clients: [codex] --name は必須であり、小文字英数字とハイフンで書く description は必須であり、起動判断に使われる license、compatibility、metadata は任意 9 / 19

重要フィールド フィールド 必須性 役割 name description license compatibility allowed-tools 必須 必須 任意 任意 任意 スキル識別子 起動判断の材料 利用条件 対応クライアント 利用可能ツールの制約 10 / 19

宣言的ではなく手続き的に書く 悪い例 orders と customers を結合し、region で絞り込んで合計する 良い例 1 スキーマを読む 2 外部キー規則で結合する 3 条件を WHERE 句にする 4 表として整形する 再利用可能な思考手順を書くことが重要 11 / 19

効果的な指示パターン 落とし穴（Gotchas）: 暗黙の前提や環境固有の注意点を明示する テンプレート（Template）: レポートや出力形式を雛形として指定する チェックリスト（Checklist）: 依存関係のある作業を段階的に検証する 参照資料（Reference）: スキーマ、規約、サンプルを必要時に読ませる 実務上の価値 エージェントの自由度を残しながら、失敗しやすい箇所を制御できる 12 / 19

説明文の役割 説明文（Description） は、スキルを起動するかどうかの最初の判断材料 悪い例 良い例 CSV ファイルを処理する CSV、TSV、表形式データを分析し、要約 統計、派生列、可視化、クレンジングを行 う 短すぎる説明文は漏れを生み、広すぎる説明文は過検知を生む 13 / 19

説明文最適化のループ 1 eval_queries.json に評価用クエリを作る 2 発動すべきクエリと発動すべきでないクエリを混ぜる 3 スキルのトリガーレートを計測する 4 過検知と漏れを分析して description を修正する 5 検証用クエリを分け、過剰適合を避ける 14 / 19

出力品質の評価 { "skill_name": "csv-analyzer", "evals": [{ "prompt": "売上トップ3の月を見つけて棒グラフを作成", "expected_output": "棒グラフ画像と軸ラベル", "assertions": ["3つの月", "両軸のラベル"] }] } ベースラインとスキルありを比較する 合格基準、実行時間、消費トークン数を確認する 15 / 19

スクリプトを同梱する理由 複雑な処理を自然言語だけに任せず、再現可能なコードに落とせる 外部パッケージは uvx や npx で一時実行できる バージョン固定により、実行結果の揺れを減らせる 自己完結型スクリプトは、環境構築の手間を小さくする 例 uvx [email protected] check . npx eslint@9 --fix . 16 / 19

エージェント向けスクリプトの設計原則 インタラクティブな入力待ちを避ける エラー時は 0 以外の終了コードを返す 原因は標準エラー出力、stderr、に書く 標準出力は要約し、大量ログはファイルに出す 単一コマンドで実行できる形を目指す 17 / 19

まとめ 1 エージェントスキルは、業務知識と手順を配布可能な形にする 2 段階的開示により、必要な情報だけをコンテキストに入れる 3 SKILL.md の説明文は、スキル起動の精度を左右する 4 良いスキルは、宣言ではなく再利用可能な手順を記述する 5 評価とスクリプトにより、エージェントの実行品質を安定化できる 18 / 19

参考文献 I Agent Skills. Agent skills documentation. Project website, 2026. 19 / 19