developing-claude-code-plugins

Claude Code プラグインの開発

概要

このスキルでは、Claude Code プラグインを効率よく作成するためのワークフローを紹介します。プラグイン開発を迅速かつ正確に進めるために使用してください。公式ドキュメントを実践的な手順にまとめ、動作するサンプルも提供します。

使用する場面

次のような場合に、このスキルを使用してください。

• Claude Code プラグインをゼロから作成する
• 既存のプラグインにコンポーネント（スキル、コマンド、フック、MCP サーバー）を追加する
• テスト用の開発マーケットプレイスを設定する
• プラグインの構造に関する問題をトラブルシューティングする
• プラグインのアーキテクチャとパターンを理解する
• プラグインをリリースする（バージョン管理、タグ付け、マーケットプレイスでの配布）
• 更新を公開する、または既存のプラグインを保守する

包括的な公式ドキュメントについては、working-with-claude-code スキルを使用して、ドキュメント全体にアクセスしてください。

クイックリファレンス

必要な内容	参照先	公式ドキュメント
ディレクトリ構造を理解する	references/plugin-structure.md	plugins.md
プラグインのパターンを選ぶ	references/common-patterns.md	plugins.md
フックをクロスプラットフォームで動作させる	references/polyglot-hooks.md	hooks.md
プラグインの問題をデバッグする	references/troubleshooting.md	各種
動作するサンプルを見る	examples/ ディレクトリ	該当なし

プラグイン開発ワークフロー

フェーズ 1：計画

コードを書く前に、次のことを行います。

1. プラグインの目的を定義する

   • どのような問題を解決しますか？
   • 誰が使用しますか？
   • どのようなコンポーネントが必要ですか？

2. パターンを選ぶ（references/common-patterns.md を参照）

   • 1 つのスキルを備えたシンプルなプラグインですか？
   • ガイダンスを備えた MCP 統合ですか？
   • コマンド集ですか？
   • 多機能なプラットフォームですか？

3. サンプルを確認する

   • examples/simple-greeter-plugin/ - 最小構成のプラグイン
   • examples/full-featured-plugin/ - すべてのコンポーネントを備えたプラグイン
   • ~/.claude/plugins/ にインストールされているプラグイン

フェーズ 2：構造の作成

1. ディレクトリを作成する（詳細は references/plugin-structure.md を参照）：

   mkdir -p my-plugin/.claude-plugin
   mkdir -p my-plugin/skills
   # Add other component directories as needed
   

2. plugin.json を作成する（必須）：

   {
     "name": "my-plugin",
     "version": "1.0.0",
     "description": "What your plugin does",
     "author": {"name": "Your Name"}
   }
   

   完全な形式については、references/plugin-structure.md を参照してください。

3. 開発用マーケットプレイスを作成する（ローカルテスト用）：

   .claude-plugin/marketplace.json を作成します。

   {
     "name": "my-dev",
     "plugins": [{
       "name": "my-plugin",
       "source": "./"
     }]
   }
   

   完全な形式については、references/plugin-structure.md を参照してください。

フェーズ 3：コンポーネントの追加

TodoWrite を使用して、コンポーネントの作成状況を追跡します。

例：

- Create skill: main-workflow
- Add command: /hello
- Configure hooks
- Write README
- Test installation

各コンポーネントの種類については、次を参照してください。

• 形式／構文：references/plugin-structure.md
• 使用する場面：references/common-patterns.md
• 動作するコード：examples/ ディレクトリ

フェーズ 4：ローカルでテスト

1. テスト用にインストールする：

   /plugin marketplace add /path/to/my-plugin
   /plugin install my-plugin@my-dev
   

   その後、Claude Code を再起動します。

2. 各コンポーネントをテストする：

   • スキル：スキルの説明に一致するタスクを依頼します
   • コマンド：/your-command を実行します
   • MCP サーバー：ツールが利用可能であることを確認します
   • フック：関連するイベントを発生させます

3. 繰り返し改善する：

   /plugin uninstall my-plugin@my-dev
   # Make changes
   /plugin install my-plugin@my-dev
   # Restart Claude Code
   

フェーズ 5：デバッグと調整

問題が発生した場合は、references/troubleshooting.md で次の内容を確認してください。

• プラグインが読み込まれない
• スキルが起動しない
• コマンドが表示されない
• MCP サーバーが起動しない
• フックが実行されない

よくある問題は、通常次のとおりです。

• ディレクトリ構造が正しくない
• パスがハードコードされている（${CLAUDE_PLUGIN_ROOT} を使用してください）
• Claude Code を再起動し忘れている
• スクリプトに実行権限が付与されていない

フェーズ 6：リリースと配布

1. README を作成し、以下を記載します。

   • プラグインの機能
   • インストール手順
   • 使用例
   • コンポーネントの説明

2. セマンティックバージョニングを使用してリリースのバージョンを設定します。

   • .claude-plugin/plugin.json の version を更新します
   • 変更内容を CHANGELOG.md または RELEASE-NOTES.md に記録します
   • 例："version": "1.2.1"（major.minor.patch）

3. リリースをコミットしてタグ付けします。

   git add .
   git commit -m "Release v1.2.1: [brief description]"
   git tag v1.2.1
   git push origin main
   git push origin v1.2.1
   

4. 配布方法を選択します。

   オプション A：GitHub から直接配布

   • ユーザーは次を追加します：/plugin marketplace add your-org/your-plugin-repo
   • プラグインの plugin.json がマニフェストとして機能します

   オプション B：マーケットプレイスで配布（複数プラグインのコレクションに推奨）

   • マーケットプレイス用のリポジトリを別途作成します
   • プラグインへの参照を含む .claude-plugin/marketplace.json を追加します。

     {
       "name": "my-marketplace",
       "owner": {"name": "Your Name"},
       "plugins": [{
         "name": "your-plugin",
         "source": {
           "source": "url",
           "url": "https://github.com/your-org/your-plugin.git"
         },
         "version": "1.2.1",
         "description": "Plugin description"
       }]
     }
     

   • ユーザーは次を追加します：/plugin marketplace add your-org/your-marketplace
   • プラグインをリリースするたびにマーケットプレイスのマニフェストを更新します

   オプション C：非公開／チーム内で配布

   • チームの .claude/settings.json で設定します。

     {
       "extraKnownMarketplaces": {
         "team-tools": {
           "source": {"source": "github", "repo": "your-org/plugins"}
         }
       }
     }
     

5. リリースをテストします。

   # Test fresh installation
   /plugin marketplace add your-marketplace-source
   /plugin install your-plugin@marketplace-name
   # Verify functionality, then clean up
   /plugin uninstall your-plugin@marketplace-name
   

6. 告知してメンテナンスします。

   • GitHub リリース（任意）
   • チームへの通知
   • 問題やユーザーからのフィードバックを監視します
   • メンテナンスアップデートを計画します

重要なルール

以下を必ず守ってください（references/plugin-structure.md より）。

1. .claude-plugin/ にはマニフェストのみを配置します（plugin.json と任意の marketplace.json）

   • ❌ スキル、コマンド、その他のコンポーネントを中に配置しないでください
   • ✅ プラグインのルートに配置してください

2. 設定ファイル内のすべてのパスに ${CLAUDE_PLUGIN_ROOT} を使用します

   • プラグインをさまざまなシステムで利用できるようになります
   • フック、MCP サーバー、スクリプトで必須です

3. plugin.json では相対パスを使用します

   • ./ で始めます
   • プラグインのルートからの相対パスです

4. スクリプトを実行可能にします

   • chmod +x script.sh
   • フックと MCP サーバーで必須です

このスキルのリソース

• references/plugin-structure.md - ディレクトリ構成、ファイル形式、コンポーネントの構文
• references/common-patterns.md - 各プラグインパターンを使う場面と例
• references/polyglot-hooks.md - Windows/macOS/Linux 向けのクロスプラットフォーム対応フックラッパー
• references/troubleshooting.md - よくある問題のデバッグガイド
• examples/simple-greeter-plugin/ - 最小限の動作するプラグイン（スキル 1 つ）
• examples/full-featured-plugin/ - すべてのコンポーネントを含む完全なプラグイン（run-hook.cmd を含む）

関連資料

公式ドキュメントを詳しく確認するには、working-with-claude-code スキルを使用して、以下にアクセスします。

• plugins.md - プラグイン開発の概要
• plugins-reference.md - API リファレンス全般
• skills.md - スキル作成ガイド
• slash-commands.md - コマンド形式
• hooks.md、hooks-guide.md - フックシステム
• mcp.md - MCP サーバーの統合
• plugin-marketplaces.md - 配布

ベストプラクティス

1. シンプルに始める - 最小限の構成から始め、必要に応じて複雑さを加えます
2. こまめにテストする - インストール → テスト → アンインストール → 変更、を繰り返します
3. 例を活用する - 動作するプラグインのパターンをコピーします
4. 規約に従う - 既存のプラグインのスタイルに合わせます
5. すべてを文書化する - 明確な README はユーザーと将来の自分に役立ちます
6. 適切にバージョンを設定する - セマンティックバージョニング（major.minor.patch）を使用します

ワークフローの概要

Plan → Choose pattern, review examples
Create → Make structure, write manifests
Add → Build components (skills, commands, etc.)
Test → Install via dev marketplace
Debug → Use troubleshooting guide
Release → Version, tag, distribute via marketplace
Maintain → Monitor, update, support users

正しい手順が最短の手順です。 リファレンスを活用し、パターンに従い、こまめにテストしてください。