Claude Code プラグインリファレンスマニュアル

プラグインは Claude Code の機能拡張の中核であり、カスタムスラッシュコマンド、サブエージェント、自動化フックなどの機能を追加できます。本チュートリアルでは、コアコンポーネント、設定仕様、CLI管理の3つの観点から、プラグインの使用と開発のポイントを素早く習得できます。

プラグインのコアコンポーネント：5種類の拡張機能

プラグインは5種類のコンポーネントで機能拡張を実現します。各コンポーネントには固定の保存場所とフォーマット要件があります。

コンポーネントの種類	保存場所	ファイル形式	主な役割
コマンド	プラグインルートディレクトリ`commands/`	フロントマター付きMarkdownファイル	カスタムスラッシュコマンドを追加。例：`/deploy` `/code-review`
エージェント	プラグインルートディレクトリ`agents/`	Markdownファイル	専用サブエージェントを提供。例：コードレビューエージェント、パフォーマンステストエージェント
スキル	プラグインルートディレクトリ`skills/`	を含む`SKILL.md`ディレクトリ	Claudeがシナリオを自動認識して呼び出せるようにする。例：PDF解析、データ可視化
フック	プラグインルートディレクトリ`hooks/hooks.json` 或 `plugin.json`インライン	JSON設定ファイル	Claudeのイベントを監視して自動応答する。例：ファイル編集後にコードを自動フォーマット
MCPサーバー	プラグインルートディレクトリ`.mcp.json` 或 `plugin.json`インライン	JSON設定ファイル	外部ツール（GitHub、Jiraなど）に接続し、その機能をClaudeで利用可能なツールに変換する
LSPサーバー	プラグインルートディレクトリ`.lsp.json` 或 `plugin.json`インライン	JSON設定ファイル	コードインテリジェンス機能を提供。例：構文チェック、定義へのジャンプ、ホバー表示

主要コンポーネントの例

1. フック設定の例：ファイル編集後の自動フォーマット

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh"
          }
        ]
      }
    ]
  }

}

：Go言語のスマートヒントをサポート

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

プラグイン基本仕様：インストール範囲とマニフェスト

1. インストール範囲：プラグインの利用可能範囲を決定する

プラグインのインストール時には範囲を選択する必要があります。範囲によって対応する設定ファイルと使用シナリオが異なります：

範囲	設定ファイルのパス	適用シナリオ
`user`	`~/.claude/settings.json`	個人のすべてのプロジェクトで共通（デフォルト）
`project`	`.claude/settings.json`	チーム共有、コードリポジトリと同期
`local`	`.claude/settings.local.json`	プロジェクト専用、`.gitignore`によって無視される
`managed`	`managed-settings.json`	ホスト型プラグイン、読み取り専用で自動更新

2. プラグインマニフェスト：`plugin.json`知っておくべきポイント

plugin.jsonはプラグインのコア設定ファイルであり、.claude-plugin/ディレクトリに格納され、プラグインのメタデータとコンポーネントのパスを定義します。

a. 必須フィールド

フィールド	型	要件	例
`name`	string	一意の識別子、kebab-case形式	`"go-code-helper"`

b. コアメタデータフィールド

{
  "version": "1.0.0", // 语义化版本
  "description": "提供 Go 语言代码智能和调试能力",
  "author": {
    "name": "Dev Team",
    "email": "[email protected]"
  },
  "license": "MIT"
}

c. コンポーネントパスフィールド

カスタムコンポーネントの場所を指定するために使用します。パスはプラグインルートディレクトリからの相対パスかつ./で始まる必要があります：

{
  "commands": ["./custom-commands/deploy.md"],
  "agents": "./custom-agents/",
  "hooks": "./hooks.json"
}

d. 環境変数

${CLAUDE_PLUGIN_ROOT}：プラグインルートディレクトリの絶対パス。スクリプトや設定でプラグイン内のファイルを参照するために使用し、パスエラーを防ぎます。

3. 標準的なプラグインディレクトリ構造

my-plugin/
├── .claude-plugin/           # 元数据目录
│   └── plugin.json          # 插件清单（必需）
├── commands/                 # 自定义斜杠命令
├── agents/                   # 子代理定义
├── skills/                   # 自动技能
├── hooks/                    # 事件钩子配置
├── .mcp.json                # MCP 服务器配置
├── .lsp.json                # LSP 服务器配置
└── scripts/                 # 钩子执行脚本

注意：commands/ agents/などのコンポーネントディレクトリはプラグインのルートディレクトリに配置する必要があり、.claude-plugin/内には配置できません。

プラグイン管理：CLIコマンド早見表

Claude Code CLIを使用すると、プラグインのインストール、アンインストール、有効化/無効化などの操作をすばやく実行でき、スクリプトや自動化のシナリオに適しています。

コマンド	用途	例
`claude plugin install <插件名> -s <范围>`	プラグインをインストール	`claude plugin install go-lsp --scope project`
`claude plugin uninstall <插件名>`	プラグインをアンインストール	`claude plugin uninstall go-lsp`
`claude plugin enable <插件名>`	無効化されたプラグインを有効化	`claude plugin enable go-lsp`
`claude plugin disable <插件名>`	プラグインを無効化（アンインストールしない）	`claude plugin disable go-lsp`
`claude plugin update <插件名>`	プラグインを最新バージョンに更新	`claude plugin update go-lsp`

デバッグとトラブルシューティング：よくある問題の解決

1. デバッグコマンド

以下のコマンドを実行してプラグインの読み込み詳細を確認し、設定や読み込みの問題を特定します：

claude --debug

確認できる項目：プラグインの読み込み状態、マニフェストの構文エラー、コンポーネントの登録状況、MCP/LSPサーバーの初期化ログ。

2. 頻出問題と解決策

問題	原因	解決方法
プラグインが読み込まれない	`plugin.json`構文エラーまたは必須フィールドの欠落	用 `claude plugin validate`JSON構文を検証し、不足している`name`フィールドを補完する
カスタムコマンドが表示されない	コマンドファイルが`.claude-plugin/` 内	将 `commands/`ディレクトリにあるため、プラグインのルートディレクトリに移動する
フックスクリプトが実行されない	スクリプトに実行権限がない	を実行して`chmod +x scripts/your-script.sh`権限を付与する
LSPの警告`Executable not found`	対応する言語サーバーがインストールされていない	バイナリファイルをインストールする（例：Goの場合は`gopls`）
MCPサーバーの起動失敗	パスに絶対パスを使用しており、`${CLAUDE_PLUGIN_ROOT}`	を使用していない。環境変数参照に置き換える。例：`${CLAUDE_PLUGIN_ROOT}/server`

バージョン管理と配布

バージョン仕様：セマンティックバージョニングに従うMAJOR.MINOR.PATCH。例：1.2.3
配布チャネル：プラグインマーケットを通じて配布するか、プラグインディレクトリを直接共有します（完全な構造を含める必要があります）
更新ログ：プラグインのルートディレクトリに CHANGELOG.md を追加し、CHANGELOG.mdバージョン更新内容を記録することを推奨します

その他の拡張