skill-development

Claude Code プラグイン向けスキル開発

概要

スキルは、専門的なワークフロー、ドメイン知識、同梱リソースによって Claude の能力を拡張する、モジュール式の知識パッケージです。Claude を汎用エージェントから専門家へと変えます。

スキルでは 段階的開示 を採用しています。これは、コンテキストを効率的に管理する3段階の読み込みシステムです。

1. メタデータ（名前＋説明） - 常にコンテキスト内にあります（約100語）
2. SKILL.md 本文 - スキルが起動したときに読み込まれます（約1,500～2,000語）
3. 同梱リソース - Claude が必要に応じて読み込みます（上限なし）

スキルの構成

skill-name/
├── SKILL.md              # Required: Core instructions
├── references/           # Optional: Detailed documentation
│   ├── patterns.md       #   Loaded when Claude needs detail
│   └── advanced.md
├── examples/             # Optional: Working code examples
│   └── example.sh        #   Users can copy and adapt
├── scripts/              # Optional: Executable utilities
│   └── validate.sh       #   Token-efficient, deterministic
└── assets/               # Optional: Output resources
    └── template.html     #   Used in output, not loaded into context

実際に必要なディレクトリだけを作成してください。 最小構成のスキルは SKILL.md だけです。

SKILL.md の形式

フロントマター（必須）

新しいスキルはすべて、この標準形式に従う必要があります。これと異なる形式にすることが、スキルが一度も起動しない最大の原因です。

---
name: skill-name                                  # REQUIRED: kebab-case, matches directory name
description: One-sentence summary of what the skill covers. PROACTIVELY activate for: (1) concrete named trigger, (2) concrete named trigger, ..., (N) concrete named trigger. Provides: comma-separated capability nouns (concrete, not abstract).
---

説明が複数行にわたる場合は、次のように記述します（非常に長い説明にのみ必要です。可能であれば1行にしてください）。

---
name: skill-name
description: |
  One-sentence summary. PROACTIVELY activate for: (1) trigger, (2) trigger, ..., (N) trigger. Provides: capability list.
---

フロントマターの厳格なルール

1. name: は必須であり、親ディレクトリ名と完全に一致する必要があります（skills/skill-name/SKILL.md → name: skill-name）。
2. description: は必須であり、PROACTIVELY activate for: (1)... (N)... の列挙と、Provides: ... の機能一覧の両方を含める必要があります。
3. フロントマターがまったくない SKILL.md は壊れています。 決して起動せず、スキルの検出にも表示されません。P0 のバグとして扱ってください。SKILL.md を開いて最初の行が --- でなければ、ほかの作業に着手する前にフロントマターを修正してください。
4. 抽象的な機能ではなく、具体的で名前のあるトリガーを列挙してください。 「PROACTIVELY activate for: (1) creating Azure Functions, (2) binding config」は適切です。「Use this skill when working with Azure」は適切ではありません。
5. 何をするかではなく、いつ使うかを説明してください。 説明はルーティングを決めるため、ユーザーの視点からトリガーの一覧として読める必要があります。機能の要約は末尾の Provides: ... に記載してください。
6. 説明は1行で、YAML として安全な形式にしてください。 | ブロックスカラーを使う場合は、行の途中にエスケープされていないコロンなど、YAML の解釈を混乱させる文字を含めないでください。
7. 説明は400～1,000文字を目標にしてください。 上限は1,024文字です（Claude Code API の仕様）。現在の Claude の一覧表示では、各項目の上限は1,536文字です（v2.1.105で250文字から引き上げ）。インストール済みの全スキルで共有される合計予算は、モデルのコンテキストウィンドウの約1%です。トリガーとなるキーワードを先頭に配置してください。約1,000文字に収まりきらないほど多くのトリガーが本当に必要な場合は、肥大化した説明にするより、2つのスキルに分割してください。
8. Windows のパスやドキュメント方針など、複数の領域に関わる定型文を YAML の説明に入れないでください。 Markdown 本文に記載してください。

標準的な「良い」説明

description: Expert guide to Terraform AzureRM provider for Azure infrastructure. PROACTIVELY activate for: (1) authoring AzureRM resource blocks, (2) state management (remote backends, state locking), (3) module design and composition, (4) variable and output patterns, (5) provider version pinning, (6) debugging plan/apply errors, (7) importing existing Azure resources, (8) CI/CD for Terraform (Azure DevOps, GitHub Actions). Provides: AzureRM provider patterns, state backend templates, module scaffolding, debugging playbook, and import recipes.

壊れた説明（いずれも、信頼性の高いルーティングができません）

# BROKEN: no frontmatter at all
# (file starts with `# Skill Title` - will not appear in discovery)

# BROKEN: wrong shape, no enumeration
description: Use this skill when working with Terraform.

# BROKEN: abstract capability, no triggers
description: Provides Terraform expertise and guidance.

# BROKEN: WHAT-it-does instead of WHEN-to-use
description: This skill contains Terraform AzureRM provider documentation.

# BROKEN: second person (wrong voice)
description: You should load this skill when the user mentions Terraform.

# BROKEN: missing Provides list
description: PROACTIVELY activate for: (1) Terraform tasks. (No Provides section means the capability summary is lost.)

# BROKEN: cross-cutting Windows boilerplate inside YAML
description: |
  Terraform expert. MANDATORY: Always Use Backslashes on Windows for File Paths...
  (This is routing-match pollution. Move Windows rules to the body.)

本文 - 文体

スキル本文全体を、命令形／不定詞形（動詞から始まる指示）で記述してください。

正しい例（命令形）：

To create a hook, define the event type.
Configure the MCP server with authentication.
Validate settings before use.
Start by reading the configuration file.

誤った例（二人称）：

You should create a hook by defining the event type.
You need to configure the MCP server.
You can use the grep tool to search.

本文 - 構成

# Skill Title

## Overview
[Purpose and when to use - 2-3 sentences]

## Quick Reference
[Tables with key facts, common values, or patterns]

## Core Content
[Essential procedures and workflows - the main value]

## Additional Resources

### Reference Files
- **`references/patterns.md`** - Common patterns
- **`references/advanced.md`** - Advanced techniques

### Example Files
- **`examples/example.sh`** - Working example

本文 - サイズの目安

目標	語数
理想	1,500～2,000
最大	3,000（絶対上限）

SKILL.md が2,000語を超える場合は、詳細な内容を references/ ファイルに移してください。

サイズの管理手順：

1. SKILL.md を書いた後、単語数を数えます（フロントマターは除外）。wc -w を使うか、1行あたり約5語として見積もってください。
2. 2,000語を超える場合は、参考資料にあたるセクション（詳細な表、網羅的な一覧、サーバー固有の設定、トラブルシューティングの一覧表）を特定し、references/ に移します。
3. 移動後も3,000語を超える場合、そのスキルの対象範囲は広すぎます。2つのスキルに分割するか、さらに多くの内容を references に移してください。
4. 最初に SKILL.md に書いたというだけの理由で、セクションを残してはいけません。 各セクションがコアファイルに含まれるべきか、必ず評価してください。

本文 - コンテンツの重複を避ける

単一の SKILL.md 内では、同じ表、リスト、コンテンツのブロックを繰り返さないでください。表や参照ブロックを追加する前に、ファイル内に同様のコンテンツがすでに存在しないか検索してください。

SKILL.md と references/ の間では、情報は一か所のみに記載します。詳細な表が references/patterns.md にある場合、SKILL.md には簡単な要約と参照ファイルへのリンクのみを記載し、表をコピーしないでください。

「逐語的なコピーが 2 つ以上なら抽出」ゲート（必須）

スキルを作成または改訂する際は、段落、表、チェックリスト、フェンス付きコードブロックを SKILL.md または参照ファイルに貼り付ける前に、次の確認を実行してください。

# From the plugin root - adjust path to the candidate paragraph's first distinctive line:
grep -rn "FIRST_DISTINCTIVE_LINE_OF_THE_BLOCK" skills/ agents/ commands/ README.md

判断基準（例外なく適用）：

grep でブロックが見つかったファイル数	対応
他のファイルが 0 個	追加して問題ありません。そのまま進めてください。
他のファイルが 1 個（これが 2 つ目のコピーになります）	停止してください。 skills/_shared/<topic>.md（スキルをまたぐ共通コンテンツ）または skills/<this-skill>/references/<topic>.md（単一スキルの詳細）に抽出します。両方の呼び出し箇所を 1 行の参照に置き換えてください。
他のファイルが 2 個以上	P1 のバグとして扱います。直ちに抽出し、その後、ほかにも該当箇所がないか監査してください。

このルールは、標準手順の段落、チェックリスト、監査表、「X の唯一の正しい定義」として読めるあらゆるブロックに適用されます。短い 1 行の定義、frontmatter の例、「このスキルは次のような場合に使用します」のような一般的な表現には適用されません。これらは抽出するほどの内容がありません。

「スライスを個別に扱う」ことが問題になる理由： プラグインツリーの残りを grep せずにファイルを 1 つずつ改訂すると、同じ標準テキストが 2 つのファイルに記載されてしまいます。解決方法は機械的です。約 3 行を超えるブロックをコミットする前に、必ず grep してください。

リソースの種類

references/ - 必要に応じて読み込むドキュメント

• 詳細なパターン、高度な手法、API ドキュメント、移行ガイド
• 情報を見つけやすくしながら、SKILL.md を簡潔に保ちます
• 各ファイルの長さは 2,000～5,000 語以上でもかまいません
• 大きなファイル（10k 語超）では、SKILL.md に grep 検索パターンを記載します
• 重複を避ける：情報は SKILL.md または references/ のどちらか一方に記載し、両方には記載しません

examples/ - ユーザーがコピーして使える動作するコード

• 完全で実行可能なスクリプトと設定ファイル
• テンプレートファイルと実用的な使用例

scripts/ - 実行可能なユーティリティ

• 検証ツール、テスト用ヘルパー、自動化スクリプト
• トークン効率に優れています（コンテキストに読み込まずに実行）
• 実行可能で、ドキュメント化されている必要があります

assets/ - 出力用リソース（コンテキストには読み込まれません）

• テンプレート、画像、アイコン、定型コード、フォント
• Claude が読み込むのではなく、Claude が生成する出力内で使用します

スキル作成プロセスとよくある間違い

6 ステップのプロセス（ユースケース -> リソースの計画 -> 構成の作成 -> 内容の記述 -> 検証 -> 反復）と、よくある間違いの全一覧は references/creation-process-and-mistakes.md にあります。要点は次のとおりです。

1. ユーザーが実際に使いそうな具体的なユースケースとトリガーフレーズを特定します。
2. 再利用可能なリソースを計画します：scripts/、references/、assets/、examples/。
3. 必要なディレクトリのみを作成します。
4. まずリソースを用意し、その後、簡潔な SKILL.md を作成します（三人称の説明、命令形の本文、約 1,500～2,000 語）。
5. frontmatter、トリガーフレーズ数（5 以上）、重複ブロックがないこと、本文が 3,000 語未満であること、参照ファイルがすべて存在することを検証します。
6. 実際のタスクでの使用状況をもとに反復します。トリガーを強化し、長いセクションを references/ に抽出します。

よくある間違いの概要：トリガーが弱い、同義語が不足している、単一の SKILL.md 内にブロックが重複している、すべてを 1 つのファイルに詰め込んだ（8,000 語の）スキル、二人称の本文、1024 文字の上限を超える説明。

自動検出

Claude Code はスキルを自動的に検出します。

1. SKILL.md を含むサブディレクトリを skills/ ディレクトリ内でスキャンします
2. 起動時にメタデータ（名前＋説明）を読み込みます
3. 説明との一致に基づいてスキルが起動すると、SKILL.md の本文を読み込みます
4. Claude が必要と判断した場合、リファレンスや例を読み込みます

設定は不要です。SKILL.md を適切な場所に配置するだけです。