エージェントスキル：再利用可能な機能パッケージ

「スキル」とは何か——エージェントが必要に応じて読み込む、指示・スクリプト・素材を備えたフォルダ。

スキルとは

スキル は、エージェントに反復可能な能力を教える自己完結パッケージです。毎回指示を打ち直す代わりに、関連場面でエージェントが発見して読み込むフォルダを提供します。

整った最小構成は次のとおり：

my-skill/
├── SKILL.md        # frontmatter（name, description）+ 指示
├── scripts/        # エージェントが実行できるコード
├── references/     # 必要時にのみ読み込むドキュメント
└── assets/         # テンプレート、画像、雛形

中核の設計原則：段階的開示

コンテキスト窓を小さく保つため、情報を 3 段階で読み込みます：

1. メタデータ（常時ロード）——frontmatter の name と description。関連性の判定に足る最小限。
2. 本文（一致時にロード）——SKILL.md の主要な指示。
3. 同梱リソース（必要時にロード）——本文から参照されるスクリプトや参考資料。

すべてを第 1 層に詰め込むと、関連の有無にかかわらず毎リクエストでコンテキストを消費し、目的に反します。

実際に発火する description の書き方

description はスキルが発火するかどうかの最大のレバーです。次を含めます：

• 何をするか（What）
• いつ使うか（When）——具体的な発火条件、ファイル種別、ユーザー意図
• 何を出力するか（What format）

悪い例：ドキュメントを扱う。

良い例：PDF からテキストと表を抽出し、フォームを埋め、文書を結合する。PDF ファイルを扱う場合、またはユーザーが PDF・フォーム・文書抽出に言及した場合に使用。

よくある失敗パターン