skill-writing

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 寄り:

1. よくある致命的ミス — 陥りやすい罠を先に提示
2. 手順 — 核となるステップを最短経路で
3. 使い分け — 複数パターンがある場合のみ
4. 絶対守るルール — MUST/SHOULD 明記
5. 例 — 出力品質が例に依存する場合のみ

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

スキル作成・更新後の最終確認:

• name が公式要件（文字種、長さ、予約語、XMLタグ禁止）を満たす
• description が What/When/Keywords を満たし、限定語で競合回避できている
• SKILL.md 本文が500行未満
• 一般説明が過剰でない（AI エージェントは既に知っている前提）
• テンプレート構造（よくある致命的ミス → 手順 → 使い分け → ルール → 例）に沿っている
• progressive disclosure 使用時、references が1階層でリンクされている
• 発火3件/非発火3件のテストを実施済み