Agent Skill 作成ガイド

Agent Skillsは、AIエージェントに専門的な知識やワークフローを提供するためのオープン標準フォーマットである。このSkillでは、ベストプラクティスに沿った高品質なSkillを作成する手順を示す。

Skillとは

Skillは SKILL.md ファイルを含むディレクトリで構成される。エージェントはタスクに応じて必要なSkillを自動検出し、段階的にコンテンツを読み込む。

code

skill-name/
├── SKILL.md          # 必須: メタデータ＋指示
├── scripts/          # 任意: 実行可能コード
├── references/       # 任意: 参照ドキュメント
└── assets/           # 任意: テンプレート、リソース

Skill作成ワークフロー

以下のチェックリストに従って進める:

code

作成チェックリスト:
- [ ] Step 1: 目的と対象タスクを明確化する
- [ ] Step 2: SKILL.md のフロントマターを記述する
- [ ] Step 3: 本文（指示）を記述する
- [ ] Step 4: 必要に応じて補助ファイルを作成する
- [ ] Step 5: レビューと検証を行う

Step 1: 目的と対象タスクを明確化する

Skillを書き始める前に以下を整理する:

•何をするSkillか: 具体的な機能や対象タスクを定義する
•いつ使われるべきか: エージェントがこのSkillを選択すべきトリガーとなるキーワードや状況を特定する
•自由度の設定: タスクの性質に応じて指示の厳密さを決める

自由度の判断基準:

•高自由度（テキストベースの指示）: 複数のアプローチが有効で、コンテキストによって判断が異なる場合
•中自由度（疑似コードやパラメータ付きスクリプト）: 推奨パターンがあるが、ある程度の変更が許容される場合
•低自由度（具体的なスクリプト、パラメータなし）: 操作がフラジャイルで、一貫性が必須な場合

具体例から要件を固める（推奨）

効果的なSkillにするには、まず「ユーザーが実際に言いそうな依頼」を具体例として集める。例:

•ユーザーはどんな言い回しで依頼するか（トリガー文言）
•入力は何か（ファイル拡張子、フォルダ構成、前提ツール）
•期待する出力は何か（ファイル、フォーマット、品質条件）
•失敗しやすい点は何か（手順の抜け、選択肢過多、破壊的操作）

一度に質問しすぎない。最重要の2〜3個から聞き、追加は必要になってから行う。

Step 2: フロントマターを記述する

YAML フロントマターの必須・任意フィールドの詳細は FRONTMATTER.md を参照。

最低限の構成:

yaml

---
name: my-skill-name
description: このSkillが何をするか、いつ使うかを具体的に記述する
---

name のルール:

•最大64文字、小文字英数字とハイフンのみ
•ハイフンで始めたり終えたりしない、連続ハイフン禁止
•親ディレクトリ名と一致させる
•動名詞形を推奨（例: processing-pdfs、analyzing-data）
•曖昧な名前（helper、utils）は避ける

description のルール:

•最大1024文字、空にしない
•何をするか と いつ使うか の両方を含める
•三人称で記述する（「Processes ...」「Use when ...」）
•キーワードを含め、エージェントが正しくSkillを選択できるようにする

重要: 「いつ使うか（トリガー）」の情報は description に集約する。本文はSkillが有効化された後にしか読み込まれないため、本文に「When to use」セクションを書いても、Skill選択（発火）には寄与しない。

description の良い例:

yaml

description: PDFファイルからテキストと表を抽出し、フォーム入力やドキュメント結合を行う。PDF、フォーム、文書抽出に関する作業をしているとき、またはユーザーがそれらに言及したときに使用する

description の悪い例:

yaml

description: ドキュメントを手伝う

Step 3: 本文（指示）を記述する

フロントマター以降のMarkdown本文にSkillの指示を記述する。

核心原則: 簡潔さが鍵

•エージェントは既に高い汎用知識を持っている。エージェントが既に知っている説明は省く
•各段落が「このトークンコストに見合うか？」を問う
•SKILL.md本文は 500行以下 に抑える。超える場合は参照ファイルに分割する

書き方の指針: 命令形（〜する）で、実行手順・判断基準・期待出力を短く書く。説明のための説明は避け、例と手順を優先する。

重複を避ける: 同じ情報を SKILL.md と参照ファイルに二重に置かない。コアの手順は SKILL.md、詳細な仕様・データ・大量の例は参照ファイルに寄せる。

推奨する本文構成:

•概要（このSkillが何をするか、1〜2文）
•手順やワークフロー（ステップバイステップ）
•入出力の具体例
•エッジケースや注意事項
•補助ファイルへの参照リンク

良い例（簡潔、約50トークン）:

markdown

## PDF テキスト抽出

pdfplumber でテキストを抽出する:

\```python
import pdfplumber

with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
\```

悪い例（冗長、約150トークン）:

markdown

## PDF テキスト抽出

PDF（Portable Document Format）ファイルは、テキストや画像などの
コンテンツを含む一般的なファイル形式です。PDFからテキストを抽出
するにはライブラリが必要です。多くのライブラリがありますが…

Step 4: 補助ファイルの作成

SKILL.md が長くなる場合や、ドメイン別に内容を分ける場合は補助ファイルを作成する。

プログレッシブ・ディスクロージャー（段階的開示）:

エージェントは3段階でSkillを読み込む:

•検出（Discovery）: 全Skillの name と description のみ読み込む（約100トークン）
•有効化（Activation）: タスクに合致したSkillの SKILL.md 本文を読み込む（5000トークン以下推奨）
•実行（Execution）: 必要に応じて参照ファイルやスクリプトを読み込む

ファイル構成パターン:

エージェントはSKILL.mdから直接参照されるファイルのみ確実に読む。参照は 1階層まで に留める。

パターン1: 高レベルガイド＋参照ファイル

markdown

# PDF Processing

## クイックスタート
[基本的な使い方をここに記述]

## 高度な機能
**フォーム入力**: [FORMS.md](FORMS.md) を参照
**APIリファレンス**: [REFERENCE.md](REFERENCE.md) を参照

パターン2: ドメイン別構成

code

bigquery-skill/
├── SKILL.md（概要とナビゲーション）
└── references/
    ├── finance.md
    ├── sales.md
    └── product.md

パターン3: 条件付き詳細

markdown

## ドキュメント編集
簡単な編集は XML を直接変更する。

**変更追跡が必要な場合**: [REDLINING.md](REDLINING.md) を参照

深いネストを避ける:

code

# 悪い例（深すぎる参照チェーン）
SKILL.md → advanced.md → details.md

# 良い例（1階層の参照）
SKILL.md → advanced.md
SKILL.md → reference.md
SKILL.md → examples.md

100行を超える参照ファイル には冒頭に目次を付ける。

大きい参照ファイルの扱い: 参照ファイルが大きい（目安: 1万語以上）場合、SKILL.md側に grep などの検索例を添えて、必要箇所に素早く辿り着けるようにする。

Step 5: レビューと検証

作成したSkillを以下の観点でレビューする。完全なチェックリストは CHECKLIST.md を参照。

品質チェック:

•description が具体的で、何をするか・いつ使うかの両方を含んでいるか
•SKILL.md 本文が500行以下か
•用語が統一されているか（同じ概念に複数の用語を使っていないか）
•時間依存の情報を含んでいないか
•ファイルパスにフォワードスラッシュ（/）が使われているか（バックスラッシュ不可）
•参照が1階層以内か
•不要な補助ドキュメント（README、CHANGELOG、インストール手順書等）を増やしていないか（エージェントの実行に必要なものだけを同梱する）

反復的な改善プロセス:

•Skillなしでタスクを実行し、繰り返し提供するコンテキストを特定する
•そのコンテキストを元にSkillを作成する
•別のエージェントセッションでSkillをテストする
•観察結果に基づいてSkillを改善する
•テスト→改善のサイクルを繰り返す

VS Code固有の設定

VS CodeでのAgent Skills配置場所（指示がなければ .github/skills/）:

種別	パス
プロジェクトSkill	`.github/skills/`、`.claude/skills/`、`.agents/skills/`
個人Skill	`~/.copilot/skills/`、`~/.claude/skills/`、`~/.agents/skills/`

VS Code追加フロントマターフィールド:

フィールド	説明
`argument-hint`	スラッシュコマンド時のヒントテキスト
`user-invocable`	`/` メニューに表示するか（デフォルト: `true`）
`disable-model-invocation`	モデルの自動呼び出しを無効化するか（デフォルト: `false`）

よくあるパターンと具体例

テンプレートパターン、入出力例パターン、条件分岐ワークフローパターンなどの詳細は PATTERNS.md を参照。

参照ファイル一覧

•FRONTMATTER.md: フロントマター全フィールドのリファレンス
•PATTERNS.md: よくあるパターンと具体例
•CHECKLIST.md: Skill品質チェックリスト

付属スクリプト（任意）

このSkillには、雛形生成と簡易検証のためのスクリプトを同梱できる。

•scripts/init_skill.py: Skillディレクトリ雛形を生成する
•scripts/validate_skill.py: SKILL.md の基本チェック（name/description など）を行う