| name | skill-writing |
| description | スキル定義ファイル（SKILL.md）の作成・更新を支援する。frontmatter 設計、description のトリガーキーワード調整、本文構成、progressive disclosure 設計、発火テストを含む。スキル作成、SKILL.md、frontmatter、description、.agents/skills、発火しない、トリガーワード、name フィールド、スキル競合などの言及時に使用。 |
| user-invokable | false |
Skill Writing
Quick Reference
- 実行手順:
.agents/prompts/99_create-skill.prompt.md
- 雛形生成:
.agents/skills/99_skill-writing/scripts/init_skill.sh <name>
- 記述原則「短く強く」/ ファイルパスリンク判断:
.agents/skills/99_copilot-instructions-maintenance/SKILL.md
- スクリプト作成:
.agents/skills/agent-script-writing/SKILL.md
よくある致命的ミス
1. name が不正 → スキル認識されない
- ❌
name: MySkill, name: スキル名
- ✅
name: my-skill（要件は Frontmatter > MUST 参照）
2. description が曖昧 → 発火しない / 競合に負ける
- ❌
description: ドキュメントを扱う
- ✅
description: Excelスプレッドシートを分析し、ピボットテーブルを作成する。Excelファイル、.xlsxファイルを分析する際に使用。
3. 本文が冗長 → コンテキスト圧迫
AI エージェントは既に賢い。手順・制約・例（必要最小限）に絞る。
Frontmatter
発火の決定打。name と description の2フィールドのみ。
---
name: your-skill-name
description: [何をする]。[いつ使う]に使用。[トリガーワード]などの言及時に使用。
---
MUST（バリデーション要件）
name: 小文字・数字・ハイフンのみ、64文字以内、XMLタグ/予約語（anthropic, claude）禁止description: 空禁止、1024文字以内、XMLタグ禁止、三人称で書く- 上記2フィールド以外を frontmatter に書かない
SHOULD（発火率・競合耐性）
description の構造: What（何をするか）+ When（いつ使うか）+ Keywords（トリガーワード）
Keywords の書き方:
- 具体的な拡張子・ツール名・固有名詞を含める（例:
.xlsx, gh pr diff, SKILL.md）
- 表記揺れを吸収する（例:
PR, pull request, プルリクエスト）
- 競合を避ける限定語を最低1つ含める
避けること:
- 一般語だけで構成しない
- 一人称・二人称を使わない
- 本文に "When to Use" セクションを書かない（description に集約）
自由度の設計
タスクの脆弱性に合わせて指示の具体度を調整する。
- High（目的＋ヒント）: 複数の正解があり、状況で変わる → テキストベース指示
- Medium（推奨パターン＋パラメータ）: 既定パターンがあるが設定で変わる → 疑似コード
- Low（手順固定）: 失敗が致命的、順序厳守 → 具体コマンド/スクリプト
複数手段がある場合はデフォルトを1つ提示し、必要なときだけ例外を示す。
Anatomy of a skill
.agents/skills/{name}/
├── SKILL.md # 必須: メイン指示（発火時に読み込まれる）
├── scripts/ # 任意: 実行可能コード
├── references/ # 任意: 必要時に読む詳細ドキュメント
└── assets/ # 任意: 出力用素材（コンテキストに読み込まない）
- ディレクトリ名: プレフィックスなし（メタスキルのみ
99_）
- 詳細:
.agents/docs/prefix-naming-convention.md
1スキル = 1能力。トリガーワード・入出力・失敗パターンのいずれかが別物なら分割する。
SKILL.md 本文の構成
記述トーン: 命令形/不定詞で統一する（「〜する」「〜を確認」）。説明文体（「〜します」「〜できます」）は使わない。
構成パターンの選択
スキルの性質に合わせて構成を選ぶ:
- Workflow-Based: 順序のある手順 → 「Step 1 → Step 2 → ...」
- Task-Based: 独立した操作の集合 → 「Quick Start → タスクA → タスクB」
- Reference/Guidelines: 基準や仕様 → 「Guidelines → Specifications → Usage」
- Capabilities-Based: 相互関連する機能群 → 「Core Capabilities → 1. Feature → 2. Feature」
パターンは混合可能。init_skill.sh が生成するデフォルト（下記）は Workflow-Based 寄り:
- よくある致命的ミス — 陥りやすい罠を先に提示
- 手順 — 核となるステップを最短経路で
- 使い分け — 複数パターンがある場合のみ
- 絶対守るルール — MUST/SHOULD 明記
- 例 — 出力品質が例に依存する場合のみ
500行以内に収める。超えそうなら progressive disclosure で分離。
共通パターン
本文で使えるパターン。詳細は公式 BP: Common patterns 参照。
- テンプレート: 出力形式を固定する場合。厳格さの度合いを明示
- 入出力例: 説明より例が効果的な場合、Input/Output ペアで示す
- 条件分岐: 「〜なら → A手順」形式。大きくなったら別ファイルに分離
- ワークフロー & フィードバックループ: 複雑な多段作業にはチェックリスト型 + 検証ループ。詳細
- plan-validate-execute: 破壊的操作やバッチ処理向け。詳細
Progressive disclosure
SKILL.md が肥大化する場合、詳細を references/ に分離。
- 参照ファイルは SKILL.md から直接リンクする（ネスト参照禁止）
- 100行超の references は冒頭に目次を付ける
- 大サイズ（>10k words）の references は、SKILL.md に grep パターンを記載して部分参照を可能にする
- 同じ情報を SKILL.md と references の両方に書かない
## 応用
- **詳細仕様**: [references/details.md](references/details.md)
- **API参照**: [references/api.md](references/api.md)
Anti-patterns
- パスは
/ を使う（Windows形式 \ は避ける）
- time-sensitive 情報を本文に書かない（現在推奨のみ記載）
- MCP ツール参照時は完全修飾名を使う（
ServerName:tool_name）
- README, CHANGELOG, INSTALLATION_GUIDE 等の補助ドキュメントを含めない（スキルは AI エージェントが仕事に使う情報のみ）
テストと評価
発火テスト（最低6ケース）
- 発火すべき3件: トリガーワードを含む自然な質問
- 発火しないべき3件: 似た語を含むが別スキル向きの質問
runSubagent でテスト可能。テスト時は「スキル定義を読み込ませず」純粋なユーザーとして振る舞わせる。
反復改善は公式 BP: Develop Skills iteratively 参照。
Checklist
スキル作成・更新後の最終確認:
