| name | skill-creator |
| description | Agent Skillsのオープン標準仕様に沿ってSKILL.mdとディレクトリ構成を生成・レビューする。ユーザーがSkillの作成、新規Skill生成、SKILL.mdの書き方、Agent Skillsの設計について質問したときに使用する |
Agent Skill 作成ガイド
Agent Skillsは、AIエージェントに専門的な知識やワークフローを提供するためのオープン標準フォーマットである。このSkillでは、ベストプラクティスに沿った高品質なSkillを作成する手順を示す。
Skillとは
Skillは SKILL.md ファイルを含むディレクトリで構成される。エージェントはタスクに応じて必要なSkillを自動検出し、段階的にコンテンツを読み込む。
skill-name/
├── SKILL.md # 必須: メタデータ＋指示
├── scripts/ # 任意: 実行可能コード
├── references/ # 任意: 参照ドキュメント
└── assets/ # 任意: テンプレート、リソース
Skill作成ワークフロー
以下のチェックリストに従って進める:
作成チェックリスト:
- [ ] 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 を参照。
最低限の構成:
---
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 の良い例:
description: PDFファイルからテキストと表を抽出し、フォーム入力やドキュメント結合を行う。PDF、フォーム、文書抽出に関する作業をしているとき、またはユーザーがそれらに言及したときに使用する
description の悪い例:
description: ドキュメントを手伝う
Step 3: 本文（指示）を記述する
フロントマター以降のMarkdown本文にSkillの指示を記述する。
核心原則: 簡潔さが鍵
- エージェントは既に高い汎用知識を持っている。エージェントが既に知っている説明は省く
- 各段落が「このトークンコストに見合うか？」を問う
- SKILL.md本文は 500行以下 に抑える。超える場合は参照ファイルに分割する
書き方の指針: 命令形（〜する）で、実行手順・判断基準・期待出力を短く書く。説明のための説明は避け、例と手順を優先する。
重複を避ける: 同じ情報を SKILL.md と参照ファイルに二重に置かない。コアの手順は SKILL.md、詳細な仕様・データ・大量の例は参照ファイルに寄せる。
推奨する本文構成:
- 概要（このSkillが何をするか、1〜2文）
- 手順やワークフロー（ステップバイステップ）
- 入出力の具体例
- エッジケースや注意事項
- 補助ファイルへの参照リンク
良い例（簡潔、約50トークン）:
## PDF テキスト抽出
pdfplumber でテキストを抽出する:
\```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
\```
悪い例（冗長、約150トークン）:
## 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: 高レベルガイド＋参照ファイル
# PDF Processing
## クイックスタート
[基本的な使い方をここに記述]
## 高度な機能
**フォーム入力**: [FORMS.md](FORMS.md) を参照
**APIリファレンス**: [REFERENCE.md](REFERENCE.md) を参照
パターン2: ドメイン別構成
bigquery-skill/
├── SKILL.md（概要とナビゲーション）
└── references/
├── finance.md
├── sales.md
└── product.md
パターン3: 条件付き詳細
## ドキュメント編集
簡単な編集は XML を直接変更する。
**変更追跡が必要な場合**: [REDLINING.md](REDLINING.md) を参照
深いネストを避ける:
# 悪い例（深すぎる参照チェーン）
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/ |
追加の探索場所は chat.skillsLocations で設定できる。モノレポで親リポジトリの Skill も拾いたい場合は chat.useCustomizationsInParentRepositories を確認する。
VS Code追加フロントマターフィールド:
| フィールド | 説明 |
|---|
argument-hint | スラッシュコマンド時のヒントテキスト |
user-invocable | / メニューに表示するか（デフォルト: true） |
disable-model-invocation | モデルの自動呼び出しを無効化するか（デフォルト: false） |
作成と確認の導線:
/skills で Configure Skills メニューを開ける/create-skill や Chat Customizations editor（Preview）の Generate Skill で初期ドラフトを生成できる
よくあるパターンと具体例
テンプレートパターン、入出力例パターン、条件分岐ワークフローパターンなどの詳細は PATTERNS.md を参照。
参照ファイル一覧
付属スクリプト（任意）
このSkillには、雛形生成と簡易検証のためのスクリプトを同梱できる。
scripts/init_skill.py: Skillディレクトリ雛形を生成するscripts/validate_skill.py: SKILL.md の基本チェック（name/description など）を行う
