Agent Skills入門

2026年7月20日

はじめに

Agent Skillsの仕組みと使い方を解説する入門ドキュメントです。公式サイトのドキュメントをもとにしています。

1章: Agent Skillsとは？

1.1 Agent Skillsの概要

Agent Skillsとは、AIエージェントに新しい機能や専門知識を追加するための軽量なオープンフォーマットです。

簡単に言うと、エージェントに新しいことを教えるための仕組みです。

Agent Skillsでは、SKILL.mdというファイルを含むフォルダを「スキル」として定義します。このファイルには、エージェントに実行してほしい手順や、必要な情報が記載されています。

my-skill/
├── SKILL.md          # 必須: メタデータと手順
├── scripts/          # オプション: 実行可能なスクリプト
├── references/       # オプション: 参照資料
├── assets/           # オプション: テンプレートやリソース
└── ...               # その他のファイルやディレクトリ

スキルを作成すると、エージェントは必要に応じてそれを読み込み、指示に従って作業を行います。これにより、エージェントはあなたのプロジェクトやチーム固有の知識を活用できるようになります。

1.2 なぜAgent Skillsなのか

AIエージェントはどんどん賢くなっていますが、すべてのコンテキストを最初から知っているわけではありません。Agent Skillsは、以下の理由で役立ちます。

ドメイン固有の知識を取得できる

法律のレビュー方法からデータ分析のパイプライン、プレゼンテーションのフォーマットまで、専門的な知識を再利用可能な手順として記録できます。

反復可能なワークフローを実現できる

複数ステップのタスクを、一貫して再現可能な手順に変換できます。これにより、作業の品質が安定し、監査も可能になります。

複数の製品で再利用できる

一度スキルを作成すれば、Agent Skillsに対応したあらゆるエージェントで使えます。同じスキルを何度も作り直す必要はありません。

1.3 対応ツール一覧

Agent Skillsはオープンスタンダードであり、Claude Code、OpenCode、Piなど、多くのAIツールやエージェントクライアントでサポートされています。対応ツールの最新情報は公式サイトでご確認ください。

2章: はじめてのスキル作成

2.1 Quickstart（Pi編）

実際にスキルを作成して、Pi Coding Agentで動かしてみましょう。

スキルの保存場所

Piでは、以下の場所にスキルを保存できます。

  • グローバル: ~/.pi/agent/skills/ または ~/.agents/skills/
  • プロジェクト: .pi/skills/ または .agents/skills/

プロジェクト固有のスキルを作成する場合は、プロジェクトのルートディレクトリに.pi/skills/フォルダを作成するのがおすすめです。

スキルを作成する

まず、スキル用のフォルダを作成します。ここではroll-diceという名前のスキルを作成してみましょう。

mkdir -p .pi/skills/roll-dice

次に、SKILL.mdファイルを作成します。

---
name: roll-dice
description: サイコロを振るために乱数ジェネレーターを使用する。d6、d20などのダイスを振るよう求められた場合、またはランダムなサイコロの目を生成する場合に使用。
---

ダイスを振るには、1から指定された目までの乱数を生成するコマンドを使用します：

```bash
echo $((RANDOM % <sides> + 1))
``` \

```powershell
Get-Random -Minimum 1 -Maximum (<sides> + 1)
``` \

`<sides>`にはダイスの目を指定します（例：標準的なダイスなら6、d20なら20）。

これで完了です！たったの1ファイル、20行未満でスキルが完成しました。

SKILL.mdの各部分の説明

  • name — スキルの短い識別子。フォルダ名と一致する必要があります。
  • description — エージェントがこのスキルをいつ使うべきかを説明します。これがエージェントがスキルを有効化する判断材料になります。
  • 本文 — スキルが有効化されたときにエージェントが従う手順。ここでは、ターミナルコマンドを使って乱数を生成する方法が指示されています。

スキルを試す

  1. Piを起動
  2. /skill:roll-dice と入力してスキルをロード
  3. 「d20を振って」などと入力

エージェントがroll-diceスキルを有効化し、コマンドを実行して1から20の間の乱数を返します。

スキルの読み込みプロセス

  1. 発見（Discovery）: Pi起動時に、エージェントはデフォルトのスキルディレクトリをスキャンし、各スキルのnameとdescriptionを読み取ります。これだけで、そのスキルがどんな時に役立つかを判断できます。
  2. 有効化（Activation）: ユーザーのタスクがスキルの説明と一致すると、エージェントは完全なSKILL.mdの内容をコンテキストに読み込みます。
  3. 実行（Execution）: エージェントは指示に従って作業を行います。

この段階的開示（Progressive Disclosure）という仕組みにより、エージェントは多数のスキルを保持しつつ、必要なときだけ詳細をロードできます。

スキルコマンド

Piでは、以下のコマンドでスキルを操作できます。

  • /skill:名前 — スキルをロードして実行
  • /skill:名前 引数 — 引数を指定して実行（例: /skill:roll-dice 20）

注意点

  • PiはAgent Skills標準の厳密な名前ルールを強制しません
  • スキル名は親ディレクトリ名と異なっていても動作します

2.2 SKILL.mdの書き方

SKILL.mdは、YAMLのフロントマターとMarkdown本文で構成されます。

フロントマター

フィールド 必須 制約
name ○ 最大64文字。小文字の英数字とハイフンのみ。ハイフンで始まらない/終わらない
description ○ 最大1024文字。空でないこと。スキルが何をするか、いつ使うかを説明
license - ライセンス名またはバンドルされたライセンスファイルへの参照
compatibility - 最大500文字。環境の要件（対象製品、システムパッケージ、ネットワークアクセスなど）
metadata - 任意のキーバリューマップ。追加メタデータ用
allowed-tools - 事前に承認されたツールのスペース区切り文字列（実験的機能）

最小限の例

---
name: my-skill
description: このスキルが何をするか、いつ使うかを説明。
---

ここにスキルの手順を記載します。

オプションフィールドを含む例

---
name: pdf-processing
description: PDFテキストの抽出、フォーム入力、ファイル結合。PDFを扱う際に使用。
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

ここにスキルの手順を記載します。

本文の内容

フロントマターの後のMarkdown本文には、スキルの手順を記載します。フォーマットの制限はありません。エージェントがタスクを効果的に実行するために必要なことを書きましょう。

推奨されるセクション：

  • ステップバイステップの手順
  • 入出力の例
  • 一般的な注意点（エッジケース）

Tip: エージェントは一度スキルが有効化されると、ファイル全体をコンテキストに読み込みます。長いSKILL.mdの内容がある場合は、参照ファイルに分割することを検討しましょう。

2.3 スキルのテスト方法

作成したスキルが正しく動作するか確認する方法を紹介します。

スキルが認識されているか確認する

Piでは、/skill コマンドで利用可能なスキルのリストを確認できます。

/skill

スキルがリストに表示されていれば、正常に読み込まれています。

実際に使ってみる

スキルが有効化される条件を満たす指示を出して、正しく動作するか確認します。

例えば、roll-diceスキルの場合は：

d20を振って

または

サイコロを1回振って

などの指示で、スキルが有効化されるはずです。

エージェントの実行トレースを確認する

エージェントがスキルを正しく読み込んだか確認するには、実行トレース（実行ログ）を確認します。エージェントがスキルのSKILL.mdをロードし、その指示に従ってコマンドを実行していれば成功です。

注意すべき点

  • モデルによってツールの使用信頼性が異なります。一部のモデルはスキルの指示に従ってコマンドを実行しますが、他のモデルは自分で回答を試みる場合があります。
  • エージェントがターミナルコマンドの実行を求めた場合は、許可を与えてください。
  • 異なるモデルで試してみて、最適な動作を確認することをおすすめします。

3章: 仕様と構造

3.1 ディレクトリ構成

スキルの標準的なディレクトリ構成は以下の通りです。

skill-name/
├── SKILL.md          # 必須: メタデータと手順
├── scripts/          # オプション: 実行可能なコード
├── references/       # オプション: ドキュメント
├── assets/           # オプション: テンプレート、リソース
└── ...               # その他のファイルやディレクトリ

各ディレクトリの役割

ディレクトリ 用途
SKILL.md スキルの必須ファイル。メタデータと手順を記載
scripts/ エージェントが実行できるスクリプトを配置
references/ 必要に応じてエージェントが読み取る追加ドキュメント
assets/ テンプレート、画像、データファイルなどの静的リソース

Note: references/内のファイルは、必要に応じてエージェントが読み取ります。ファイルは小さく保ち、エージェントのコンテキスト使用量を最適化しましょう。

3.2 SKILL.mdフォーマット

SKILL.mdはYAMLフロントマターとMarkdown本文で構成されます。

---
name: skill-name
description: スキルの説明
---

ここに手順や指示を記載します。

フロントマターのルール

  • nameとdescriptionは必須フィールド
  • nameは小文字の英数字とハイフンのみ使用
  • nameはハイフンで始まったり終わったりしてはいけない
  • descriptionはスキルが何をするか、いつ使うかを明確に説明
  • その他のフィールドはオプション

3.3 必須フィールド

nameフィールド

スキルの識別子です。以下のルールに従ってください。

  • 1〜64文字
  • 小文字の英数字（a-z, 0-9）とハイフンのみ使用可能
  • ハイフンで始まらない・終わらない
  • 連続するハイフン（--）を含めない
  • 親ディレクトリ名と一致すること

有効な例:

name: pdf-processing
name: data-analysis
name: code-review

無効な例:

name: PDF-Processing  # 大文字は不可
name: -pdf            # ハイフンで始まらない
name: pdf--processing # 連続ハイフンは不可

descriptionフィールド

エージェントがいつこのスキルを使うべきかを判断するための説明です。

  • 1〜1024文字
  • 空にしてはいけない
  • スキルが何をするか、いつ使うかを説明
  • エージェントが関連するタスクを識別するのに役立つ具体的なキーワードを含める

良い例:

description: PDFファイルからテキストとテーブルを抽出し、PDFフォームに入力し、複数のPDFを結合します。PDFドキュメントを扱っている場合や、ユーザーがPDF、フォーム、ドキュメント抽出について言及した場合に使用。

良くない例:

description: PDFに役立ちます。

Tip: 説明的な表現（「〜してください」）を使い、ユーザーの意図に焦点を当てましょう。

3.4 オプションフィールド

licenseフィールド

スキルのライセンスを指定します。

license: Apache-2.0

または

license: Proprietary. LICENSE.txtに完全な条項があります

短い記述を推奨します。

compatibilityフィールド

スキルが特定の環境を必要とする場合に記載します。

compatibility: Claude Code（または類似製品）向けに設計
compatibility: git、docker、jqが必要で、インターネットアクセスが必要です
compatibility: Python 3.14+とuvが必要です

Note: ほとんどのスキルにはこのフィールドは不要です。

metadataフィールド

追加のメタデータを格納するためのキーバリューマップです。

metadata:
  author: example-org
  version: "1.0"

衝突を避けるために、キー名は十分にユニークにしましょう。

allowed-toolsフィールド

事前に承認されたツールのリストです（実験的機能）。

allowed-tools: Bash(git:*) Bash(jq:*) Read

Note: このフィールドのサポートはエージェントの実装によって異なります。

3.5 段階的開示の仕組み

Agent Skillsの最大の特徴が段階的開示（Progressive Disclosure）です。

エージェントはスキルを段階的にロードします：

  1. メタデータ（約100トークン）: 起動時に、すべてのスキルのnameとdescriptionがロードされます。これだけで、そのスキルがどんな時に役立つかを判断できます。

  2. 手順（推奨5000トークン以下）: スキルが有効化されると、完全なSKILL.mdの本文がコンテキストに読み込まれます。

  3. リソース（必要に応じて）: scripts/、references/、assets/内のファイルは、必要に応じてのみロードされます。

段階的開示を活用する

  • メインのSKILL.mdを500行以下に保つ
  • 詳細な参照資料は別ファイルに移動する
  • エージェントに「いつ」各ファイルを読み取るかを指示する
    • 良い例: 「APIが200以外のステータスを返した場合、references/api-errors.mdを読んでください」
    • 良くない例: 「詳細はreferences/を参照してください」

これにより、エージェントは多数のスキルを保持しつつ、最小限のコンテキストで動作できます。

4章: ベストプラクティス

4.1 スキルの設計原則

効果的なスキルを作成するための設計原則を紹介します。

実際の専門知識から始める

よくある失敗は、ドメイン固有のコンテキストを提供せずにLLMにスキルを生成させることです。その結果、曖昧で汎用的な手順（「適切にエラーを処理する」、「ベストプラクティスに従う」）になりがちです。

効果的なスキルは、実際の専門知識に基づいています。

実務のタスクから抽出する

エージェントと会話をしながら実際のタスクを完了し、その際に提供したコンテキスト、修正、好みなどを記録します。その後、再利用可能なパターンとしてスキルに抽出します。

注目すべき点：

  • うまくいった手順 — 成功につながったアクションの順序
  • あなたが修正した箇所 — エージェントのアプローチを誘導した箇所
  • 入出力フォーマット — 入力と出力のデータ形式
  • 提供したコンテキスト — エージェントがすでに知っていたくないプロジェクト固有の事実

既存のプロジェクト資料から合成する

既存の知識がある場合は、それをLLMにフィードバックしてスキルを生成させます。実際のインシデントレポートやランブック（運用手順書）から合成されたデータパイプラインスキルは、一般的な「データエンジニアリングのベストプラクティス」記事から合成されたものよりも優れています。

良いソースマテリアル：

  • 内部ドキュメント、ランブック、スタイルガイド
  • API仕様、スキーマ、設定ファイル
  • コードレビューコメントと課題トラッカー
  • バージョン管理の履歴、特にパッチと修正
  • 現実世界の失敗事例とその解決策

実際の実行で洗練する

スキルの上書きは通常、洗練が必要です。実際のタスクでスキルを実行し、結果（失敗だけでなくすべて）をフィードバックします。

  • 何が誤検知を引き起こしたか？
  • 何が聞き漏れられたか？
  • 何がカットできるか？

1回の「実行→見直し」のサイクルで品質が明らかに向上します。

4.2 説明文の最適化

スキルの説明文（descriptionフィールド）は、エージェントがスキルを有効化するかどうかを判断する主要な材料です。

効果的な説明文の書き方

  • 命令形で記述する — 「〜してください」とエージェントに指示する形にする
  • ユーザーの意図に焦点を当てる — 内部の仕組みではなく、ユーザーが達成したいことを記述
  • 積極的に記述する — スキルが適用されるコンテキストを具体的にリスト化
  • 簡潔に保つ — 数文から短い段落が適切。1024文字の制限内に収める

説明文の例

Before:

description: CSVファイルを処理します。

After:

description: >
  CSVおよび表形式のデータファイルを分析する — 要約統計の計算、
  派生列の追加、チャートの生成、汚れたデータのクリーンアップ。
  ユーザーがCSV、TSV、またはExcelファイルを持ち、データを探索、
  変換、または可視化したい場合に使用。
  「CSV」や「分析」を明示的に言及していない場合でも適用。

説明文の最適化プロセス

  1. 評価: 現在の説明文をテスト
  2. 失敗の特定: 誤ってトリガーされないケース、トリガーされるべきなのにされないケース
  3. 修正: 説明文を改善
  4. 検証: 改善が一般化しているか確認
  5. 繰り返し: 十分な改善が見られるまで手順1-4を繰り返す

4.3 スクリプトの活用

スキルにスクリプトをバンドルすると、エージェントの作業を効率化できます。

スクリプトの配置

my-skill/
├── SKILL.md
└── scripts/
    ├── analyze.py
    ├── validate.py
    └── generate.py

スクリプトの書き方

  • 自己完結型にするか、依存関係を明確に文書化する
  • 有用なエラーメッセージを含める
  • エッジケースを適切に処理する

対応言語はエージェントの実装によりますが、一般的にPython、Bash、JavaScriptが使用できます。

スクリプトの呼び出し

SKILL.mdでスクリプトを呼び出す方法：

分析スクリプトを実行します：

```bash
python scripts/analyze.py input.csv
``` \

スクリプトを活用するタイミング

  • 複数のテストケースで同じロジックを繰り返している場合
  • チャートの作成、特定フォーマットの解析、出力の検証など
  • テスト済みのスクリプトを一度作成してバンドルする

4.4 参照ファイルの整理

スキルの内容が増えた場合は、参照ファイルを整理して段階的開示を活用しましょう。

参照ファイルの配置

my-skill/
├── SKILL.md
├── references/
│   ├── REFERENCE.md    # 詳細な技術参照
│   ├── FORMS.md        # フォームテンプレート
│   └── finance.md      # ドメイン固有ファイル
└── assets/
    ├── template.md     # ドキュメントテンプレート
    └── schema.json     # スキーマファイル

参照ファイルのルール

  • 相対パスで参照する（スキルルートからの相対）
  • 参照は1階層深くまでにする
  • 深くネストされた参照チェーンを避ける
  • 個別の参照ファイルを集中させる（小さく保つ）

参照の例

詳細は[参照ガイド](references/REFERENCE.md)をご覧ください。

抽出スクリプトを実行：
scripts/extract.py

「いつ」読むかを指示する

参照ファイルを配置するだけでなく、エージェントに「いつ」読むかを指示しましょう。

## APIエラー処理

APIが200以外のステータスを返した場合：

1. `references/api-errors.md`を読んでエラーコードを確認
2. 適切なエラーハンドリングを実装

これにより、エージェントは必要なときだけコンテキストをロードできます。

5章: 高度な活用

5.1 スキルの評価方法

スキルが実際に良い出力を生成するか評価する方法を紹介します。

テストケースの設計

テストケースは3つの要素で構成されます：

  • プロンプト: 現実的なユーザーメッセージ
  • 期待される出力: 成功の状態を人間が読める形で記述
  • 入力ファイル（オプション）: スキルが作業に必要なファイル
{
  "skill_name": "csv-analyzer",
  "evals": [
    {
      "id": 1,
      "prompt": "data/sales_2025.csvに月次売上データのCSVがあります。売上トップ3の月を見つけて棒グラフを作成してください。",
      "expected_output": "売上のトップ3の月を示す棒グラフ画像。軸ラベルと値付き。",
      "files": ["evals/files/sales_2025.csv"]
    }
  ]
}

良いテストプロンプトの書き方

  • 2-3つのテストケースから始める — 最初の結果を見る前に過剰投資しない
  • プロンプトを変化させる — 異なる表現、詳細度、形式を使用
  • エッジケースをカバーする — 壊れた入力、珍しいリクエスト、スキルの指示が曖昧になるケース
  • 現実的なコンテキストを使用 — ファイルパス、列名、個人的なコンテキストを含める

アサーションの記述

アサーションは、出力に含まれるべきまたは達成すべきことを検証可能な形で記述します。

良いアサーション:

  • 「出力ファイルは有効なJSON形式です」
  • 「棒グラフには軸ラベルがあります」
  • 「レポートには少なくとも3つの推奨事項が含まれています」

良くないアサーション:

  • 「出力が良い」— 曖昧すぎて検証不可
  • 「出力が正確に’総収入: $X’というフレーズを使用する」— 堅すぎて正しい出力でも失敗する可能性

評価の実行

各テストケースを2回実行します：

  1. スキルありで実行
  2. スキルなし（または旧バージョン）で実行

これにより、ベースラインと比較できます。

結果の集計

各イテレーションの完了後、要約統計を計算します：

  • パス率: どのくらいのアサーションがパスしたか
  • 時間: 実行にかかった時間
  • トークン数: 使用したトークン数

スキルがもたらすトレードオフ（時間/トークンの増加 vs 品質の向上）を理解できます。

5.2 複数LLMでの動作確認

Agent Skillsはオープンフォーマットなので、複数のLLM/エージェントで動作確認できます。

動作確認のポイント

  1. 異なるエージェントで試す
    • Claude Code、Cursor、Gemini CLIなど
    • 各エージェントでスキルの読み込みと実行を確認
  2. モデルの違いによる影響
    • ツール使用の信頼性はモデルによって異なる
    • 一部のモデルはスキルの指示を厳密に-followするが、他のモデルは自分で判断する傾向がある
  3. 検証方法
    • 各エージェントで同じプロンプトを試す
    • スキルが正しく有効化されるか確認
    • 出力が期待通りか確認

推奨されるテスト方法

# Claude Codeでテスト
claude -p "d20を振って"

# Gemini CLIでテスト
gemini -p "d20を振って"

# Cursorでテスト
# Copilotチャットで「d20を振って」と入力

Note: モデルによってツールの使用信頼性が異なるため、複数のモデルでテストすることをおすすめします。

まとめ

Agent Skillsは、AIエージェントに専門知識を追加する強力な仕組みです。

  • 軽量: 1つのファイルでスキルを定義可能
  • 再利用可能: 一度作成すれば、複数のエージェントで使用可能
  • 構造化: 段階的開示により、効率的なコンテキスト管理
  • 拡張可能: スクリプト、参照資料、リソースをバンドル可能

このドキュメントが、Agent Skillsの世界への第一歩になれば幸いです。

参考文献