---
title: エージェントスキルとは
tags: 
author: [MIKIO KUBO](https://www.docswell.com/user/mikiokubo)
site: [Docswell](https://www.docswell.com/)
thumbnail: https://bcdn.docswell.com/page/4JMYQW9MJW.jpg?width=480
description: エージェントスキルとは by MIKIO KUBO
published: June 17, 26
canonical: https://www.docswell.com/s/mikiokubo/ZMQ6RL-skill
---
# Page. 1

![Page Image](https://bcdn.docswell.com/page/4JMYQW9MJW.jpg)

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


# Page. 2

![Page Image](https://bcdn.docswell.com/page/PJR98YGL79.jpg)

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


# Page. 3

![Page Image](https://bcdn.docswell.com/page/PEXQ8GQ6JX.jpg)

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


# Page. 4

![Page Image](https://bcdn.docswell.com/page/3EK9K49GED.jpg)

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


# Page. 5

![Page Image](https://bcdn.docswell.com/page/L73WZLW575.jpg)

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


# Page. 6

![Page Image](https://bcdn.docswell.com/page/87DKRNKYJG.jpg)

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


# Page. 7

![Page Image](https://bcdn.docswell.com/page/VJPKW5K2E8.jpg)

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


# Page. 8

![Page Image](https://bcdn.docswell.com/page/2EVV8PVXEQ.jpg)

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


# Page. 9

![Page Image](https://bcdn.docswell.com/page/57GL5PLREL.jpg)

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


# Page. 10

![Page Image](https://bcdn.docswell.com/page/4EQYZ2YYJP.jpg)

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


# Page. 11

![Page Image](https://bcdn.docswell.com/page/KJ4W3LWZ71.jpg)

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


# Page. 12

![Page Image](https://bcdn.docswell.com/page/LE1Y1LYD7G.jpg)

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


# Page. 13

![Page Image](https://bcdn.docswell.com/page/GEWG8VG8J2.jpg)

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


# Page. 14

![Page Image](https://bcdn.docswell.com/page/47ZL84L9J3.jpg)

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


# Page. 15

![Page Image](https://bcdn.docswell.com/page/YJ6WP3WDJV.jpg)

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


# Page. 16

![Page Image](https://bcdn.docswell.com/page/GJ5MKLM8J4.jpg)

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


# Page. 17

![Page Image](https://bcdn.docswell.com/page/LE3WZLWGE5.jpg)

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


# Page. 18

![Page Image](https://bcdn.docswell.com/page/8EDKRNKN7G.jpg)

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


# Page. 19

![Page Image](https://bcdn.docswell.com/page/V7PKW5KNJ8.jpg)

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