プラグインにコンポーネントを追加する

​

プラグインディレクトリを探索する

• レビュースキルと about コマンド
• セキュリティレビューサブエージェント
• Claude がファイルを編集した後にファイルをフォーマットするフック、およびそれが呼び出す scripts/ フォルダ
• ログモニター
• 出力スタイルとカラーテーマ
• ルート監査ワークフロー
• hello-plugin 実行可能ファイル
• デフォルト設定
• ローカル MCP サーバーと Go 言語サーバー

​

各種類のコンポーネントを追加する

​

スキル

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── review/
        └── SKILL.md

---
description: Reviews a pull request for style and test coverage. Use when asked to review code.
---

Review the changed files. Report style problems first, then missing tests.

• コマンド名: /<plugin>:<directory> となるため、my-plugin 内の skills/review/SKILL.md は /my-plugin:review になります。フロントマターで name を設定すると、最後のセグメントが置き換えられ、プラグインのプレフィックスはそのまま残ります。スキルのコマンド名の決まり方を参照してください
• 呼び出せる主体: Claude、ユーザー、またはその両方で、フロントマターで制御します。スキルを呼び出せる主体を制御するを参照してください

• 追加のディレクトリ: skills マニフェストキーに列挙します。commands や agents とは異なり、デフォルトの skills/ のスキャンを置き換えるのではなく、それに追加��れます
• プラグインルートの単一スキル: skills/ ディレクトリも skills マニフェストキーもない場合、プラグインルートの SKILL.md が 1 つのスキルとして読み込まれます。フロントマターで name を設定してください。設定しないと、マーケットプレイスからのインストール時に、スキル名がプラグイン名ではなくキャッシュディレクトリの名前になります

​

コマンド

​

マニフェストでコマンドを定義する

{
  "name": "my-plugin",
  "commands": {
    "about": {
      "content": "Summarize what this repository does in three sentences.",
      "description": "Summarize the repository"
    }
  }
}

​

エージェント

---
name: security-reviewer
description: Reviews code changes for security issues. Use after edits to authentication or input handling.
model: sonnet
---

You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.

​

エージェントをサブフォルダーで整理する

• フロントマターの name: ファイル名の部分だけを置き換えるため、agents/review/security.md 内の name: audit は my-plugin:review:audit として読み込まれます
• マニフェストの agents フィールド: ここに列挙したファイルはサブフォルダー名なしで読み込まれるため、"agents": "./custom/review/security.md" は my-plugin:security として読み込まれます

​

プラグインエージェントのフロントマターフィールド

• サポートされるフィールド: name、description、model、effort、maxTurns、autoCompactWindow、tools、disallowedTools、skills、memory、background、omitClaudeMd、isolation、color、および experimental の cacheTtl キーです。isolation の有効な値は "worktree" のみです。各フィールドの役割については、サポートされるフロントマターフィールドを参照してください
• 無視されるフィールド: permissionMode、hooks、mcpServers、initialPrompt です。エージェントファイル単独ではフックや MCP サーバーを追加できないため、代わりにプラグインのフックと MCP サーバーとして追加してください
• 256 文字を超える name: Claude Code はこれを無視し、このフィールドがない場合と同様に、エージェントの名前をファイル名にします
• 解析できないフロントマター: エージェントはすべてのフィールドが無視された状態で読み込まれます。名前はファイル名になり、説明は Agent from my-plugin plugin になります。このようなファイルを見つけるには、シェルで claude plugin validate を実行してください

​

フック

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

​

プラグインのフックが発火するタイミング

​

環境、クォート、MCP ツールのマッチング

• 環境: すべてのフックプロセスは、環境変数として CLAUDE_PLUGIN_ROOT と CLAUDE_PLUGIN_DATA、さらに各ユーザー設定値に対応する CLAUDE_PLUGIN_OPTION_<KEY> を受け取るため、スクリプトはそこからこれらを読み取れます
• クォート: command に args がない場合はシェルを介して実行されるため、フックの hooks/hooks.json の例のように ${CLAUDE_PLUGIN_ROOT} のパスを二重引用符で囲み、展開後のパスが 1 つのシェルワードになるようにしてください。代わりに args を渡す場合、各要素はシェルを介さずに 1 つの引数として渡されるため、クォートは不要です。exec 形式と shell 形式を参照してください
• プラグイン自身の MCP ツールのマッチング: このプラグインが宣言する MCP サーバーのツールは mcp__plugin_<plugin>_<server>__<tool> という名前になるため、matcher にはこの完全な名前を記述してください。サーバー名だけの matcher は決して発火しません。MCP ツールのマッチングを参照してください

​

MCP サーバー

{
  "mcpServers": {
    "db": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  }
}

​

claude.ai と Cowork のユーザーに届ける

​

サーバー名、ツール名、再読み込み

• サーバー名: plugin:<plugin>:<server> となるため、my-plugin 内の db サーバーは /mcp で plugin:my-plugin:db になります。mcp_tool フックでサーバーを指定する場合も同じ形式を使用してください
• ツール名: mcp__plugin_<plugin>_<server>__<tool> となるため、その db サーバー上の query ツールは mcp__plugin_my-plugin_db__query になります。これが権限ルールとフックの matcher で使用する名前です
• 置換: ${CLAUDE_PLUGIN_ROOT} とその他のパス変数は、command、args、env 内で置換されます。args では各要素が 1 つの引数として渡されるため、クォートは不要です
• 再読み込み: ユーザーが /reload-plugins を実行し、再読み込みが適用されると、設定が変更されていないサーバーは接続を維持します。設定が変更されたサーバーは再接続し、削除したサーバーは切断されます

​

パッケージ化された MCPB サーバーを含める

{
  "name": "my-plugin",
  "mcpServers": "./servers/db.mcpb"
}

• /plugin で指定する: Installed タブでプラグインを選択し、Configure を選びます
• インストール時にシェルから指定する: claude plugin install に --config <server>.<key>=<value> を渡します。Claude Code v2.1.285 以降が必要で、プラグイン内にパッケージ化されたバンドルに対してのみ機能します。

​

LSP サーバー

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

• バイナリがない場合: Claude Code はユーザーの PATH から名前で command を起動します。バイナリがそこにない場合、サーバーは起動に失敗し、claude --debug は LSP server <name> failed to start をログに記録します
• 拡張子の競合: 有効な 2 つのサーバーが同じ拡張子を要求する場合、サーバーが 1 つのプラグインからのものか 2 つのプラグインからのものかにかかわらず、最初に登録されたサーバーがそれらのファイルを処理し、もう一方はそれらのファイルには使用されません。/plugin の Errors タブには LSP server "<name>" is not used for <ext> files という警告が表示されます

​

実行可能ファイル

#!/bin/bash
echo "hello from my-plugin"

​

デフォルト設定

{
  "agent": "security-reviewer"
}

• マニフェストよりファイルを優先: 両方が存在し、settings.json がサポートされるキーを少なくとも 1 つ設定している場合、settings.json が適用され、マニフェストの settings は無視されます
• プラグインのデフォルトよりユーザー設定を優先: 設定ソースの中で、プラグインのデフォルトは最も低いレイヤーであるため、~/.claude/settings.json 内のユーザー自身の agent がプラグインの値を上書きします
• 2 つのプラグインが同じキーを設定する場合: 最後に読み込まれたプラグインの値が適用され、claude --debug は overrides setting をログに記録します

​

テーマと出力スタイル

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555"
  }
}

​

チャネル

{
  "name": "my-plugin",
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": { "BOT_TOKEN": "${user_config.bot_token}" }
    }
  },
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        }
      }
    }
  ]
}

​

モニター

[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]

• 対話セッションのみ: プラグインのモニターは、-p フラグを使用した非対話モードでは起動しません
• 最小バージョン: Amazon Bedrock、Claude Platform on AWS、Google Cloud の Agent Platform、Microsoft Foundry のいずれかを使用している場合、または DISABLE_TELEMETRY か CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC が設定されている場合、モニターには Claude Code v2.1.310 以降が必要です。この要件は機能フラグの取得がオフの場合に適用されます
• ユーザー設定は使用不可: command はパス変数と環境からの ${ENV_VAR} を取得しますが、${user_config.*} は決して取得しません。これを参照するモニターは起動せず、モニタープロセスは CLAUDE_PLUGIN_OPTION_<KEY> も受け取りません
• セッション途中での無効化: セッションの途中でプラグインを無効にしても、Claude Code はすでに実行中のモニターを停止しません。モニターはセッションの終了時に停止します

​

ユーザーに設定値を求める

{
  "name": "my-plugin",
  "userConfig": {
    "api_url": {
      "type": "string",
      "title": "API URL",
      "description": "Base URL of your team's API"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "Token for your team's API",
      "sensitive": true
    }
  }
}

​

設定ダイアログが表示されるとき

• /plugin でプラグインをインストールする
• セッション内で /plugin install <plugin>@<marketplace> を実行する
• /plugin の Installed タブからプラグインを有効にする

​

プラグインパスを参照し、データを保存する

• ${CLAUDE_PLUGIN_ROOT}：プラグインのインストールディレクトリ。各バージョンは独自のキャッシュディレクトリを持つため、プラグインが更新されるとパスが変更されます。そこに状態を書き込まないでください
• ${CLAUDE_PLUGIN_DATA}：更新を生き残るディレクトリ。node_modules、仮想環境、キャッシュ用。~/.claude/plugins/data/<id>/ に解決され、最初に参照されるときに作成されます
• ${CLAUDE_PROJECT_DIR}：プロジェクトルート。フックが受け取るのと同じ値

​

データディレクトリに依存関係をインストールする

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
          }
        ]
      }
    ]
  }
}

​

次のステップ

• プラグインマニフェストリファレンス：plugin.json フィールド、パスルール、標準レイアウト
• evals でプラグインをテストする：追加したコンポーネントが Claude の動作を意図した方法で変更することを確認します
• プラグインを公開および配布する：プラグインをバージョン管理し、マーケットプレイスに配置します
• プラグインのトラブルシューティング：コンポーネントが読み込まれない場合またはフックが発火しない場合の対処方法