Claude Code のスキル開発

概要

スキルは、特殊な知識、ワークフロー、リソースを提供することで Claude の機能を拡張するモジュール型パッケージです。「オンボーディングガイド」として考えると、Claude を汎用エージェントから手続き知識を備えた専門エージェントへと変えるものです。

主な機能:

• 適切な構造とフロントマターを備えた新しいスキルを作成
• 既存スキルの説明、指示、構造を編集して発見性を向上
• プログレッシブディスクロージャーを使用してスキルを整理
• ベストプラクティスに対してスキルを検証
• 配布用スキルをパッケージ化

このスキルの使用場面

このスキルを使用する場面:

• 新しいスキルをゼロから作成する
• 既存スキルの説明、指示、構造を編集する
• トークン最適化またはプログレッシブディスクロージャーのためにスキルをリファクタリングする
• スキル構造とフロントマターを検証する
• SKILL.md、references/、examples/、scripts/ 全体でスキルコンテンツを整理する

スキルの構成

すべてのスキルは必須の SKILL.md とオプションのバンドルリソースで構成されます:

skill-name/
├── SKILL.md (必須)
│   ├── YAML フロントマター (name、description)
│   └── Markdown 本文 (コア指示)
└── バンドルリソース (オプション)
    ├── references/    - 必要に応じて読み込まれる詳細ドキュメント
    ├── examples/      - 動作するコード例
    └── scripts/       - ユーティリティスクリプト

プログレッシブディスクロージャー

スキルはコンテキストを管理するための 3 レベルの読み込みを使用します:

レベル	読み込みタイミング	サイズ制限	コンテンツ
メタデータ	常に (起動時)	約 100 語	フロントマターの name と description
指示	トリガー時	<5k 語 (理想: 1,500-2,000 語)	SKILL.md 本文
リソース	必要に応じて	制限なし	references/、examples/、scripts/

設計原則: SKILL.md は精簡に保つ。詳細なコンテンツは references/ に移す。

クイックスタート: 作成または編集?

コンテキストから、ユーザーが作成を希望しているか編集を希望しているかを判断します。不明な場合は尋ねます:

{
  "questions": [
    {
      "question": "何をしたいですか?",
      "header": "アクション",
      "multiSelect": false,
      "options": [
        { "label": "新しいスキルを作成", "description": "ゼロから開始" },
        { "label": "既存スキルを編集", "description": "すでに存在するスキルを更新" }
      ]
    }
  ]
}

その後、適切なワークフローに従います:

• 作成: references/creating-skills.md で詳細な作成プロセスを確認
• 編集: references/editing-skills.md で詳細な編集プロセスを確認

コアワークフロー (作成)

1. 理解を検証し、要件を収集

原則: ユーザーがすでに述べたことを尋ねないこと。 まずコンテキストから抽出し、不足していることだけを尋ねます。

常にこれら 2 つの質問を一緒に尋ねます:

{
  "questions": [
    {
      "question": "[要約] 向けのスキルを作成したいということですね。正しいですか?",
      "header": "確認",
      "multiSelect": false,
      "options": [
        { "label": "はい、そうです!", "description": "作成を進める" },
        { "label": "ほぼそうですが...", "description": "もっと説明します" }
      ]
    },
    {
      "question": "スキルの複雑さはどのくらいですか?",
      "header": "構造",
      "multiSelect": false,
      "options": [
        { "label": "シンプル", "description": "直接的な指示のみの SKILL.md" },
        { "label": "中程度", "description": "SKILL.md + examples または references" },
        { "label": "完全", "description": "SKILL.md + references + examples + scripts" }
      ]
    }
  ]
}

条件付き質問 (必要な場合のみ):

• インタラクティビティ: 複雑さが中程度以上で、コンテキストが必要性を示唆する場合
• 場所: 明らかでない場合のみ (デフォルト: ~/.claude/skills/)

2. スキル構造を設計

何をどこに配置するかを決定します:

SKILL.md (トリガー時に常に読み込まれる):

• コアコンセプトと概要
• 必須の手順とワークフロー
• クイックリファレンステーブル
• references/examples/scripts へのポインタ
• 最も一般的な使用例

references/ (必要に応じて読み込まれる):

• 詳細なパターンと高度な技法
• 包括的な API ドキュメント
• マイグレーションガイド
• エッジケースとトラブルシューティング
• 広範な例とチュートリアル

examples/ (動作するコード):

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

scripts/ (ユーティリティ):

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

3. 効果的なフロントマターを作成

必須フィールド:

---
name: skill-name
description: This skill should be used when the user asks to "特定のトリガー 1"、"特定のトリガー 2"、または特定の用語を述べる場合。何をするかについての簡潔な説明。
---

オプションフィールド:

---
name: skill-name
description: トリガーベースの説明
user-invocable: true          # スラッシュコマンドリストに表示 (デフォルト: /skills/ では true)
context: fork                 # 分離されたコンテキストで実行 (デフォルト: 継承)
agent: swe                    # スキルを実行する特定のエージェントタイプ (デフォルト: main)
language: portuguese          # 会話言語に関わらず応答言語を強制 (デフォルト: ユーザーの言語に一致)
allowed-tools:                # YAML 形式リスト (カンマ区切りより見やすい)
  - Bash
  - Read
  - Write
  - Edit
hooks:                        # このスキルにスコープされたインラインフック
  - type: PreToolUse
    once: true               # セッション中に 1 回だけ実行
  - type: PostToolUse
---

オプションフィールドをいつ使用するか:

• user-invocable: false: / コマンドリストからスキルを非表示 (スキルは説明を通じてのみ自動トリガー)
• context: fork: メイン会話からスキル実行を分離 (実験的またはスキル修正に有用)
• agent: type: スキルを特定のエージェントにルーティング (例: コード処理タスク向け swe)
• language: 会話言語に関わらず特定言語での応答を強制
• allowed-tools: スキルが使用できるツールを制限 (セキュリティ/スコープ制御)
• hooks: スキル実行のみにスコープされた PreToolUse/PostToolUse/Stop フックを追加

命名規則:

• 小文字、数字、ハイフンのみ
• 最大 64 文字
• ジェルンド形式を使用 (動詞+ing): analyzing-code、writing-documentation
• 具体的で、汎用的ではない

説明の要件:

• 最大 1024 文字
• 三人称: 「This skill should be used when...」(NOT 「Use this skill when...」や「I help you...」)
• 何をするかと、いつ使用するかの両方を含める
• ユーザーが述べるであろう特定のトリガーワードを使用
• ファイルタイプ、操作、コンテキストに言及

良い例:

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 (PreToolUse, PostToolUse, Stop). Provides comprehensive hooks API guidance.

悪い例:

description: Helps with hooks  # 曖昧で、三人称ではない
description: Use this skill for hook development  # 間違った人称
description: I can help you create hooks  # 一人称

4. 明確な指示を作成

文体:

• 命令/不定詞形を使用 (動詞最初の指示)
• 二人称ではない (「You should...」)
• 客観的で、教育的な言語

正しい:

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.

必要に応じてインタラクティブパターンを追加:

スキルが何かを作成/設定するのに役立つ場合、AskUserQuestion を含めて要件を収集します:

## 指示

### ステップ 1: 要件を収集

AskUserQuestion を使用して作成内容を理解します:

\`\`\`json
{
  "questions": [
    {
      "question": "これは何をすべきですか?",
      "header": "目的",
      "options": [...]
    }
  ]
}
\`\`\`

### ステップ 2: 回答に基づいて作成

ユーザーの選択に基づいて、適切な構造を作成します...

追加する場合: コマンド、フック、設定の作成、またはユーザー決定が必要なもの向けのスキル

確認: examples/interactive-workflow-example.md で完全なパターンを参照

5. ツールアクセス許可とフックを設定

YAML リストでのツールアクセス許可 (推奨):

---
allowed-tools:
  - Bash
  - Read
  - Write
  - Edit
  - Grep
  - Glob
---

カンマ区切りより見やすく、エラーが少ない: allowed-tools: Bash, Read, Write

柔軟なアクセス許可のための Bash ワイルドカード:

---
allowed-tools:
  - Bash(npm *)              # 任意の npm コマンドを許可
  - Bash(git * main)         # 'main' を含む git コマンドを許可
  - Bash(* install)          # 'install' で終わる任意のコマンドを許可
  - Read
  - Write
---

スキルが各コマンドをリストアップせずにコマンド変異が必要な場合、ワイルドカードを使用します。

スキルスコープの自動化向けインラインフック:

---
hooks:
  - type: PreToolUse         # ツール実行前に検証
    once: true               # 1 回だけ実行 (セットアップに有用)
  - type: PostToolUse        # ツール結果に反応
  - type: Stop               # スキル完了時にクリーンアップ
---

フックはこのスキルがアクティブな場合のみ実行されます。以下で使用:

• スキル操作に固有の検証
• スキルアクションのログ記録/追跡
• スキルライフサイクル内のセットアップ/ティアダウン

確認: ../hook-development/ で完全なフックドキュメントを参照

6. コンテンツを整理

SKILL.md は精簡に保つ (理想: 1,500-2,000 語、最大 5k):

• 詳細なコンテンツを references/ に移す
• 例を examples/ に移す
• ユーティリティを scripts/ に移す
• SKILL.md でこれらのリソースをはっきり参照

SKILL.md でリソースを参照:

## その他のリソース

### リファレンスファイル
- **`references/patterns.md`** - 一般的なパターン
- **`references/advanced.md`** - 高度な技法

### 例
- **`examples/basic-example.sh`** - 動作例

7. スキルを検証

重要: スキルを作成または編集した後、常に自動検証を実行します。

検証スクリプトを実行:

bash ~/.claude/skills/skill-development/scripts/validate-skill.sh path/to/skill-name

スクリプトは自動的に以下をチェック:

• ✓ SKILL.md が有効な YAML フロントマター で存在
• ✓ 必須フィールド (name、description) が存在で有効
• ✓ 名前形式 (小文字、ハイフン、最大 64 文字)
• ✓ 説明形式 (三人称、<1024 文字、特定のトリガー)
• ✓ 行数 (<500 行、>400 行で警告)
• ✓ 参照ファイルが存在
• ✓ 二人称の使用なし (「you should」)

検証に失敗した場合:

1. 報告されたエラーを修正
2. 検証スクリプトを再実行
3. すべてのチェックに合格した後、テストを進める

追加的な手動確認:

• 命令形での明確な指示
• 具体的な例を提供
• サポートファイルを明確に参照

8. スキルをテスト

プラグインスキルの場合:

cc --plugin-dir /path/to/plugin

個人/プロジェクトスキルの場合:

~/.claude/skills/ または .claude/skills/ 内のスキルは自動的にホットリロードされます - 再起動は不要です!

1. スキルファイルを編集
2. 説明に一致するトリガーフレーズを試す
3. スキルが更新されたコンテンツで自動的にアクティベートすることを確認
4. 指示が明確で実行可能なことを確認

注: プラグインスキルは引き続きプラグイン再読み込みが必要です (マーケットプレイスから削除して再追加)

必要に応じてデバッグ:

claude --debug  # スキル読み込みとアクティベーションログを確認

一般的なパターン

最小スキル (シンプルな知識)

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

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

スキルの場所

プラグインスキルは plugin-name/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 本文を読み込み
• Claude が必要と判断したときに references/examples を読み込み

プラグインでのテスト

# --plugin-dir でテスト
cc --plugin-dir /path/to/plugin

# スキルが正しく読み込まれてトリガーされることを確認

ベストプラクティス

すべきこと:

• ✅ 説明で三人称を使用 (「This skill should be used when...」)
• ✅ 特定のトリガーフレーズを含める (「create X」、「configure Y」)
• ✅ SKILL.md を精簡に保つ (理想: 1,500-2,000 語)
• ✅ プログレッシブディスクロージャーを使用 (詳細を references/ に移す)
• ✅ 命令/不定詞形で記述
• ✅ サポートファイルを明確に参照
• ✅ 動作する例を提供
• ✅ ジェルンド命名を使用 (code-analyzer ではなく analyzing-code)
• ✅ allowed-tools に YAML リストを使用 (カンマ区切りより見やすい)
• ✅ Bash アクセス許可でワイルドカードを使用 (適切な場合: Bash(npm *))
• ✅ 内部のみのスキルに user-invocable: false を設定
• ✅ 実験的または高リスク操作に context: fork を使用
• ✅ スキル固有の自動化のためにインラインフックを追加

してはいけないこと:

• ❌ どこでも二人称を使用
• ❌ 曖昧なトリガー条件を持つ
• ❌ references/ なしで SKILL.md にすべてを入れる (>3,000 語)
• ❌ 参照されていないリソースを残す
• ❌ 破損または不完全な例を含める
• ❌ 検証をスキップ
• ❌ すべてのスキルをユーザー呼び出し可能にする (自動トリガーのみのものもある)
• ❌ ワイルドカードがより適切な場合、カンマ区切り allowed-tools で過度に制限

その他のリソース

リファレンスファイル

詳細なプロセスと技法については、以下を参照:

• references/creating-skills.md - AskUserQuestion パターンを含む完全なスキル作成プロセス
• references/editing-skills.md - 詳細な編集ワークフローとリファクタリングパターン
• references/best-practices.md - 検証規則、一般的な間違い、最適化技法

スキル例

これらのスキルをテンプレートとして学習:

• ../hook-development/ - プログレッシブディスクロージャー、ユーティリティ、完全な構造
• ../command-development/ - 明確な重要コンセプト、良い整理
• ../sync-claude-md/ - 良く構造化された分析スキル

実装ワークフロー概要

スキルを作成するには:

1. 使用例を理解: 質問し、例を収集
2. リソースを計画: 必要なスクリプト/references/examples を決定
3. 構造を作成: mkdir -p skills/skill-name/{references,examples,scripts}
4. SKILL.md を作成:
   • 三人称の説明とトリガーフレーズを含むフロントマター
   • 命令形で精簡な本文 (1,500-2,000 語)
   • サポートファイルを参照
5. リソースを追加: 必要に応じて references/、examples/、scripts/ を作成
6. 検証: 説明、文体、整理をチェック
7. テスト: スキルが予期されたトリガーで読み込まれることを確認
8. イテレート: 使用に基づいて改善

スキルを編集するには:

1. 現在のスキルを読む: 構造、コンテンツ、行数を分析
2. 編集タイプを決定: 説明、指示、新規セクション、またはリファクタリング
3. 変更を加える: Edit ツールを使用して特定セクションを更新
4. 検証: すべての要件が依然として満たされているかをチェック
5. テスト: スキルが正しくアクティベートすることを確認

強いトリガー説明、プログレッシブディスクロージャー、命令形の文体に焦点を当てることで、必要なときに読み込まれ、対象を絞ったガイダンスを提供する効果的なスキルを実現します。