Skill Development

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

このスキルでは、Claude Code プラグイン向けの効果的なスキルを作成するためのガイダンスを提供します。

スキルについて

スキルは、専門知識、ワークフロー、ツールを提供してClaudeの機能を拡張する、モジュール式の自己完結型パッケージです。特定の分野やタスクに特化した「オンボーディングガイド」のようなものと考えてください。手順に関する知識を備えた専門エージェントへとClaudeを変身させます。この知識は、どのモデルも完全には備えられないものです。

スキルが提供するもの

1. 専門的なワークフロー - 特定の分野における複数の手順からなるプロセス
2. ツール連携 - 特定のファイル形式やAPIを扱うための手順
3. 分野の専門知識 - 企業固有の知識、スキーマ、ビジネスロジック
4. 同梱リソース - 複雑で反復的なタスクに使うスクリプト、リファレンス、アセット

スキルの構成

すべてのスキルは、必須のSKILL.mdファイルと任意の同梱リソースで構成されます。

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

SKILL.md（必須）

メタデータの品質： YAMLフロントマターのnameとdescriptionによって、Claudeがいつスキルを使うかが決まります。スキルの機能と使用するタイミングを具体的に記述してください。「このスキルを使用してください」ではなく、「このスキルは次のような場合に使用します」のような三人称の表現を使います。

同梱リソース（任意）

スクリプト（scripts/）

決定論的な信頼性が必要なタスクや、繰り返し書き直されるタスクに使う実行可能コード（Python/Bashなど）です。

• 含める場合：同じコードが繰り返し書き直されている場合、または決定論的な信頼性が必要な場合
• 例：PDF回転タスク用のscripts/rotate_pdf.py
• 利点：トークン効率がよく、決定論的であり、コンテキストに読み込まずに実行できる場合があります
• 注記：パッチ適用や環境固有の調整を行う際、Claudeがスクリプトを読む必要がある場合もあります

リファレンス（references/）

Claudeのプロセスや思考に役立てるため、必要に応じてコンテキストに読み込むドキュメントや参考資料です。

• 含める場合：作業中にClaudeが参照するドキュメントが必要な場合
• 例：金融スキーマ用のreferences/finance.md、企業のNDAテンプレート用のreferences/mnda.md、企業ポリシー用のreferences/policies.md、API仕様用のreferences/api_docs.md
• 使用例：データベーススキーマ、APIドキュメント、分野の専門知識、企業ポリシー、詳細なワークフローガイド
• 利点：SKILL.mdを簡潔に保ち、Claudeが必要だと判断した場合にのみ読み込みます
• ベストプラクティス：ファイルが大きい（10k語超）場合は、SKILL.mdにgrep検索パターンを含めます
• 重複を避ける：情報はSKILL.mdまたはリファレンスファイルのどちらか一方に記載し、両方には記載しないでください。スキルの中核にあたる情報でない限り、詳細情報にはリファレンスファイルを優先してください。これによりSKILL.mdを簡潔に保ちながら、コンテキストウィンドウを圧迫せず、情報を見つけやすくできます。SKILL.mdには必須の手順とワークフローガイダンスのみを残し、詳細な参考資料、スキーマ、例はリファレンスファイルに移してください。

アセット（assets/）

コンテキストへの読み込みを目的とせず、Claudeが生成する出力内で使用するファイルです。

• 含める場合：最終出力で使用するファイルがスキルに必要な場合
• 例：ブランドアセット用のassets/logo.png、PowerPointテンプレート用のassets/slides.pptx、HTML/Reactのひな形用のassets/frontend-template/、タイポグラフィ用のassets/font.ttf
• 使用例：テンプレート、画像、アイコン、ひな形コード、フォント、コピーまたは変更して使うサンプル文書
• 利点：出力用リソースをドキュメントから分離でき、Claudeはコンテキストに読み込まずにファイルを使用できます

段階的開示の設計原則

スキルでは、コンテキストを効率的に管理するために、3 段階の読み込みシステムを使用します。

1. メタデータ（名前＋説明） - 常にコンテキスト内にあります（約 100 語）
2. SKILL.md の本文 - スキルが呼び出されたときに読み込まれます（5,000 語未満）
3. バンドルされたリソース - Claude が必要に応じて読み込みます（無制限*）

*スクリプトはコンテキストウィンドウに読み込まずに実行できるため、無制限です。

スキルの作成プロセス

スキルを作成するには、適用できない明確な理由がある場合にのみ手順を省略し、「スキルの作成プロセス」の順序に従ってください。

ステップ 1：具体例を用いてスキルを理解する

スキルの使用パターンがすでに明確に理解されている場合にのみ、このステップを省略してください。既存のスキルを扱う場合でも、このステップには価値があります。

効果的なスキルを作成するには、そのスキルがどのように使われるかを具体例に基づいて明確に理解してください。この理解は、ユーザーから直接提示された例、または生成したうえでユーザーのフィードバックを得て検証した例から得られます。

たとえば、画像エディターのスキルを作成する場合、関連する質問には次のようなものがあります。

• 「画像エディターのスキルでは、どのような機能に対応すべきですか？編集、回転、それ以外にもありますか？」
• 「このスキルの使用例をいくつか教えてもらえますか？」
• 「『この画像の赤目を除去して』や『この画像を回転して』といった依頼が考えられます。他にも、このスキルがどのように使われると思いますか？」
• 「どのような依頼があったときに、このスキルを呼び出すべきですか？」

ユーザーに負担をかけないよう、1 回のメッセージで質問しすぎないでください。最も重要な質問から始め、より効果的なスキルにするために必要に応じて追加の質問をしてください。

このスキルが対応すべき機能が明確になったら、このステップを終えます。

ステップ 2：再利用可能なスキルの内容を計画する

具体例を効果的なスキルにするために、各例を次の観点から分析します。

1. その例を最初からどのように実行するかを検討する
2. これらのワークフローを繰り返し実行する際に役立つスクリプト、リファレンス、アセットを特定する

例：pdf-editor スキルで「この PDF の回転を手伝って」といった依頼に対応する場合、分析によって次のことがわかります。

1. PDF の回転には、毎回同じコードを書き直す必要がある
2. scripts/rotate_pdf.py スクリプトをスキルに含めると役立つ

例：frontend-webapp-builder スキルで「ToDo アプリを作って」や「歩数を記録するダッシュボードを作って」といった依頼に対応する場合、分析によって次のことがわかります。

1. フロントエンドの Web アプリを作成するには、毎回同じ定型の HTML／React が必要になる
2. 定型の HTML／React プロジェクトファイルを含む assets/hello-world/ テンプレートをスキルに含めると役立つ

例：big-query スキルで「今日ログインしたユーザー数は？」といった依頼に対応する場合、分析によって次のことがわかります。

1. BigQuery へのクエリでは、毎回テーブルのスキーマと関連性を調べ直す必要がある
2. テーブルのスキーマを記載した references/schema.md ファイルをスキルに含めると役立つ

Claude Code プラグインの場合： フック用のスキルを作成する場合、分析によって次のことがわかります。

1. 開発者は hooks.json を検証し、フックスクリプトをテストする必要が繰り返し生じる
2. scripts/validate-hook-schema.sh と scripts/test-hook.sh のユーティリティがあると役立つ
3. SKILL.md が肥大化しないよう、詳細なフックのパターンを記載した references/patterns.md があると役立つ

スキルの内容を決めるために、各具体例を分析し、含める再利用可能なリソース（スクリプト、リファレンス、アセット）の一覧を作成します。

ステップ 3：スキルの構造を作成する

Claude Code プラグインの場合は、スキルのディレクトリ構造を作成します。

mkdir -p plugin-name/skills/skill-name/{references,examples,scripts}
touch plugin-name/skills/skill-name/SKILL.md

注記： init_skill.py を使用する汎用の skill-creator とは異なり、プラグインのスキルはプラグインの skills/ ディレクトリ内に、よりシンプルな手動の構造で直接作成します。

ステップ 4：スキルを編集する

新規作成または既存のスキルを編集する際は、そのスキルが別の Claude インスタンスで使用されることを念頭に置いてください。Claude にとって有益で、かつ自明ではない情報を含めることに重点を置いてください。別の Claude インスタンスがタスクをより効果的に実行するために役立つ、手順に関する知識、ドメイン固有の詳細、再利用可能なアセットを検討してください。

再利用可能なスキルのコンテンツから始める

実装を始めるには、まず上で特定した再利用可能なリソース（scripts/、references/、assets/ のファイル）に取りかかります。このステップでは、ユーザーからの入力が必要になる場合があります。たとえば、brand-guidelines スキルを実装する場合、ユーザーから提供されたブランドアセットやテンプレートを assets/ に、ドキュメントを references/ に保存する必要があるかもしれません。

また、スキルに不要なサンプルファイルやディレクトリは削除してください。実際に必要なディレクトリ（references/、examples/、scripts/）だけを作成してください。

SKILL.md を更新する

文体： スキル全体を二人称ではなく、命令形／不定詞形（動詞から始まる指示）で記述してください。客観的で指示的な表現を使用してください（「X を達成するには、Y を行う」のように記述し、「X を行うべきです」や「X を行う必要がある場合」のような表現は避けます）。これにより、AI が読み取る際の一貫性と明瞭さが保たれます。

説明（Frontmatter）： 具体的なトリガーフレーズを含む三人称形式を使用してください。

---
name: Skill Name
description: This skill should be used when the user asks to "specific phrase 1", "specific phrase 2", "specific phrase 3". Include exact phrases users would say that should trigger this skill. Be concrete and specific.
version: 0.1.0
---

良い説明の例：

description: This skill should be used when the user asks to "create a hook", "add a PreToolUse hook", "validate tool use", "implement prompt-based hooks", or mentions hook events (PreToolUse, PostToolUse, Stop).

悪い説明の例：

description: Use this skill when working with hooks.  # Wrong person, vague
description: Load when user needs hook help.  # Not third person
description: Provides hook guidance.  # No trigger phrases

SKILL.md 本文を完成させるため、次の質問に答えてください。

1. スキルの目的は何ですか。数文で説明してください。
2. スキルはいつ使用すべきですか。（具体的なトリガーを含め、frontmatter の説明に記載します）
3. 実際には、Claude はスキルをどのように使用すべきですか。上で作成した再利用可能なスキルのコンテンツをすべて参照し、Claude が使い方を理解できるようにしてください。

SKILL.md は簡潔に保つ： 本文は 1,500～2,000 語を目安にしてください。詳細な内容は references/ に移してください。

• 詳細なパターン → references/patterns.md
• 高度なテクニック → references/advanced.md
• 移行ガイド → references/migration.md
• API リファレンス → references/api-reference.md

SKILL.md からリファレンスリソースを参照する：

## Additional Resources

### Reference Files

For detailed patterns and techniques, consult:
- **`references/patterns.md`** - Common patterns
- **`references/advanced.md`** - Advanced use cases

### Example Files

Working examples in `examples/`:
- **`example-script.sh`** - Working example

ステップ 5：検証とテスト

プラグインスキルの検証は、一般的なスキルとは異なります。

1. 構造を確認する：スキルディレクトリが plugin-name/skills/skill-name/ にあること
2. SKILL.md を検証する：name と description を含む frontmatter があること
3. トリガーフレーズを確認する：説明に具体的なユーザーの問い合わせが含まれていること
4. 文体を確認する：本文が二人称ではなく、命令形／不定詞形で記述されていること
5. 段階的な情報開示をテストする：SKILL.md が簡潔（約 1,500～2,000 語）で、詳細な内容が references/ にあること
6. リファレンスを確認する：参照されているすべてのファイルが存在すること
7. 例を検証する：例が完全で正確であること
8. スクリプトをテストする：スクリプトが実行可能で、正しく動作すること

skill-reviewer エージェントを使用する：

Ask: "Review my skill and check if it follows best practices"

skill-reviewer エージェントは、説明の品質、コンテンツの構成、段階的な情報開示を確認します。

ステップ 6：反復する

スキルをテストした後、ユーザーから改善を求められることがあります。多くの場合、スキルを使用した直後に、動作を把握した新鮮な状態で依頼されます。

反復のワークフロー：

1. 実際のタスクでスキルを使用する
2. 苦戦する点や非効率な点に気づく
3. SKILL.md または同梱リソースのどこを更新すべきか特定する
4. 変更を実装し、再度テストする

よくある改善：

• 説明のトリガーフレーズを強化する
• SKILL.md の長いセクションを references/ に移す
• 不足している例やスクリプトを追加する
• 曖昧な指示を明確にする
• エッジケースへの対応を追加する

プラグイン固有の考慮事項

プラグイン内のスキルの配置場所

プラグインスキルは、プラグインの skills/ ディレクトリに配置します。

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
├── agents/
└── skills/
    └── my-skill/
        ├── SKILL.md
        ├── references/
        ├── examples/
        └── scripts/

自動検出

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

• skills/ ディレクトリをスキャンする
• SKILL.md を含むサブディレクトリを見つける
• スキルのメタデータ（name と description）を常に読み込む
• スキルがトリガーされた際に SKILL.md の本文を読み込む
• 必要に応じて references/examples を読み込む

パッケージ化は不要です

プラグインスキルは個別の ZIP ファイルではなく、プラグインの一部として配布されます。ユーザーはプラグインをインストールするとスキルを利用できます。

プラグインでのテスト

プラグインをローカルにインストールしてスキルをテストします。

# Test with --plugin-dir
cc --plugin-dir /path/to/plugin

# Ask questions that should trigger the skill
# Verify skill loads correctly

Plugin-Dev の例

ベストプラクティスの例として、このプラグインのスキルを確認してください。

hook-development スキル：

• 優れたトリガーフレーズ：「フックを作成する」「PreToolUse フックを追加する」など
• 簡潔な SKILL.md（1,651 語）
• 詳細な内容を記載した references/ ファイルが 3 つ
• 動作するフックの examples/ が 3 つ
• scripts/ ユーティリティが 3 つ

agent-development スキル：

• 強力なトリガー：「エージェントを作成する」「エージェントの frontmatter」など
• 要点を絞った SKILL.md（1,438 語）
• References に Claude Code の AI 生成プロンプトを収録
• 完全なエージェントの例

plugin-settings スキル：

• 具体的なトリガー：「プラグイン設定」「.local.md ファイル」「YAML frontmatter」
• 実際の実装例を示す References（multi-agent-swarm、ralph-wiggum）
• 動作する解析スクリプト

それぞれ、段階的な情報開示と効果的なトリガーを実現しています。

段階的な情報開示の実践

SKILL.md に含める内容

含める内容（スキルがトリガーされると常に読み込まれる内容）：

• 中核となる概念と概要
• 必須の手順とワークフロー
• クイックリファレンステーブル
• References／Examples／Scripts への案内
• 最も一般的なユースケース

3,000 語未満に収め、できれば 1,500～2,000 語にします

references/ に含める内容

references/ に移す内容（必要に応じて読み込まれる内容）：

• 詳細なパターンと高度なテクニック
• 包括的な API ドキュメント
• 移行ガイド
• エッジケースとトラブルシューティング
• 詳細な例と手順解説

各 reference ファイルは大きくてもかまいません（2,000～5,000 語以上）

examples/ に含める内容

動作するコード例：

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

ユーザーがそのままコピーして調整できるものにします

scripts/ に含める内容

ユーティリティスクリプト：

• 検証ツール
• テスト用ヘルパー
• 解析ユーティリティ
• 自動化スクリプト

実行可能で、ドキュメントが整備されている必要があります

執筆スタイルの要件

命令形／不定詞形

二人称ではなく、動詞を先頭にした指示文を使用します。

正しい例（命令形）：

To create a hook, define the event type.
Configure the MCP server with authentication.
Validate settings before use.

誤った例（二人称）：

You should create a hook by defining the event type.
You need to configure the MCP server.
You must validate settings before use.

説明文では三人称を使用

Frontmatter の説明文は三人称にします。

正しい例：

description: This skill should be used when the user asks to "create X", "configure Y"...

誤った例：

description: Use this skill when you want to create X...
description: Load this skill when user asks...

客観的で指示的な表現

誰が行うべきかではなく、何をすべきかに焦点を当てます。

正しい例：

Parse the frontmatter using sed.
Extract fields with grep.
Validate values before use.

誤った例：

You can parse the frontmatter...
Claude should extract fields...
The user might validate values...

検証チェックリスト

スキルを仕上げる前に、次の項目を確認します。

構成：

• 有効な YAML frontmatter を含む SKILL.md ファイルが存在する
• Frontmatter に name と description フィールドがある
• Markdown 本文があり、十分な内容が記載されている
• 参照先のファイルが実際に存在する

説明文の品質：

• 三人称を使用している（「このスキルは次の場合に使用します……」）
• ユーザーが実際に言いそうな具体的なトリガーフレーズを含んでいる
• 具体的なシナリオを列挙している（「X を作成する」「Y を設定する」）
• 曖昧または一般的すぎる表現になっていない

内容の品質：

• SKILL.md 本文で命令形／不定詞形を使用している
• 本文の要点が絞られ、簡潔である（理想は 1,500～2,000 語、最大 5,000 語未満）
• 詳細な内容を references/ に移している
• 例が完全で、動作する
• スクリプトが実行可能で、ドキュメントが整備されている

段階的な情報開示：

• 中核となる概念を SKILL.md に記載している
• 詳細なドキュメントを references/ に配置している
• 動作するコードを examples/ に配置している
• ユーティリティを scripts/ に配置している
• SKILL.md からこれらのリソースを参照している

テスト：

• 想定されるユーザーのクエリでスキルがトリガーされる
• 内容が想定するタスクに役立つ
• ファイル間で情報が重複していない
• 必要に応じて References が読み込まれる

避けるべきよくある間違い

間違い 1：弱いトリガー説明

❌ 悪い例：

description: Provides guidance for working with hooks.

よくない理由： 曖昧で、具体的なトリガーフレーズがなく、三人称でもありません。

✅ 良い例：

description: This skill should be used when the user asks to "create a hook", "add a PreToolUse hook", "validate tool use", or mentions hook events. Provides comprehensive hooks API guidance.

良い理由： 三人称で、具体的なフレーズとシナリオが示されています。

間違い 2：SKILL.md に詰め込みすぎる

❌ 悪い例：

skill-name/
└── SKILL.md  (8,000 words - everything in one file)

問題点： スキルの読み込み時にコンテキストが肥大化し、詳細な内容が常に読み込まれます。

✅ 良い例：

skill-name/
├── SKILL.md  (1,800 words - core essentials)
└── references/
    ├── patterns.md (2,500 words)
    └── advanced.md (3,700 words)

良い点： 段階的な開示により、詳細な内容は必要なときにのみ読み込まれます。

間違い 3：二人称で書く

❌ 悪い例：

You should start by reading the configuration file.
You need to validate the input.
You can use the grep tool to search.

問題点： 二人称で書かれており、命令形ではありません。

✅ 良い例：

Start by reading the configuration file.
Validate the input before processing.
Use the grep tool to search for patterns.

良い点： 命令形で、直接的な指示になっています。

間違い 4：リソースへの参照がない

❌ 悪い例：

# SKILL.md

[Core content]

[No mention of references/ or examples/]

問題点： Claude は参照先があることを把握できません。

✅ 良い例：

# SKILL.md

[Core content]

## Additional Resources

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

### Examples
- **`examples/script.sh`** - Working example

良い点： Claude は追加情報の参照先を把握できます。

クイックリファレンス

最小限のスキル

skill-name/
└── SKILL.md

適している用途：シンプルな知識で、複雑なリソースを必要としない場合

標準的なスキル（推奨）

skill-name/
├── SKILL.md
├── references/
│   └── detailed-guide.md
└── examples/
    └── working-example.sh

適している用途：詳細なドキュメントを含む、ほとんどのプラグインスキル

完全版のスキル

skill-name/
├── SKILL.md
├── references/
│   ├── patterns.md
│   └── advanced.md
├── examples/
│   ├── example1.sh
│   └── example2.json
└── scripts/
    └── validate.sh

適している用途：検証ユーティリティを備えた複雑なドメイン

ベストプラクティスのまとめ

✅ 推奨事項：

• 説明には三人称を使用します（「このスキルは次の場合に使用します……」）
• 具体的なトリガーフレーズを含めます（「X を作成する」、「Y を設定する」）
• SKILL.md を簡潔に保ちます（1,500～2,000 語）
• 段階的な開示を活用します（詳細を references/ に移します）
• 命令形または不定詞形で書きます
• 補助ファイルを明確に参照します
• 動作する例を示します
• よくある操作にはユーティリティスクリプトを作成します
• plugin-dev のスキルをテンプレートとして調べます

❌ 避けること：

• どこでも二人称を使わないでください
• 曖昧なトリガー条件を設定しないでください
• すべてを SKILL.md に詰め込まないでください（references/ なしで 3,000 語を超える場合）
• 二人称で書かないでください（「あなたは……するべきです」）
• リソースを参照せずに放置しないでください
• 壊れた例や不完全な例を含めないでください
• 検証を省略しないでください

追加リソース

これらのスキルを調べる

Plugin-dev のスキルはベストプラクティスを示しています：

• ../hook-development/ - 段階的な開示、ユーティリティ
• ../agent-development/ - AI を活用した作成、参照
• ../mcp-integration/ - 包括的な参照
• ../plugin-settings/ - 実践的な例
• ../command-development/ - 重要な概念を明確に説明
• ../plugin-structure/ - 優れた構成

参照ファイル

skill-creator の手法全体については、以下を参照してください：

• references/skill-creator-original.md - skill-creator の原文全体

実装ワークフロー

プラグイン用のスキルを作成するには：

1. ユースケースを把握する：スキルの具体的な使用例を特定します
2. リソースを計画する：必要なスクリプト、参照、例を決定します
3. 構成を作成する：mkdir -p skills/skill-name/{references,examples,scripts}
4. SKILL.md を作成する：
   • 三人称の説明とトリガーフレーズを含むフロントマター
   • 命令形で書かれた簡潔な本文（1,500～2,000 語）
   • 補助ファイルへの参照
5. リソースを追加する：必要に応じて references/、examples/、scripts/ を作成します
6. 検証する：説明、文体、構成を確認します
7. テストする：想定したトリガーでスキルが読み込まれることを確認します
8. 反復する：使用状況に基づいて改善します

必要なときに読み込まれ、的確なガイダンスを提供する効果的なスキルを作成するには、強力なトリガーの説明、段階的な開示、命令形の文体に重点を置いてください。