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

​

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

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

​

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

​

Skills

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 を設定してください。そうしないと、マーケットプレイスのインストールはスキルをプラグイン名ではなく、そのキャッシュディレクトリの後に名前を付けます。

​

Commands

​

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

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

​

Agents

---
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、tools、disallowedTools、skills、memory、background、omitClaudeMd、isolation、color、および experimental の cacheTtl キー。唯一の有効な isolation 値は "worktree" です。各フィールドが何をするかについては、サポートされているフロントマターフィールドを参照してください。
• 無視されるフィールド: permissionMode、hooks、mcpServers、および initialPrompt。エージェントファイルは独自にフックまたは MCP サーバーを追加できないため、代わりにプラグインフックとMCP サーバーとして追加してください。
• 解析されないフロントマター: エージェントはすべてのフィールドが無視された状態で読み込まれます。ファイルの後に名前が付けられ、その説明は Agent from my-plugin plugin と読みます。シェルで claude plugin validate を実行して、これらのファイルを見つけます。

​

Hooks

{
  "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 の例の下の Hooks で行うように、${CLAUDE_PLUGIN_ROOT} パスを二重引用符で囲んで、展開されたパスを 1 つのシェルワードに保ちます。代わりに args を渡す場合、各要素は 1 つの引数として渡され、シェルなしで、クォートは不要です。exec form と shell form を参照してください。
• プラグイン独自の MCP ツールのマッチング: このプラグインが宣言する MCP サーバーからのツールは mcp__plugin_<plugin>_<server>__<tool> という名前が付けられるため、マッチャーにその完全な名前を記述します。サーバー名だけのマッチャーは発火しません。MCP ツールのマッチングを参照してください。

​

MCP servers

{
  "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 です。これは権限ルールとフックマッチャーで使用する名前です。
• 置換: ${CLAUDE_PLUGIN_ROOT} および他のパス変数は、command、args、および env で置換されます。各要素が 1 つの引数として渡されるため、args ではクォートは不要です。
• リロード: ユーザーが /reload-plugins を実行し、リロードが適用される場合、構成が変更されていないサーバーは接続を保持します。構成が変更されたサーバーは再接続し、削除したサーバーは切断されます。

​

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

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

​

LSP servers

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

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

​

Executables

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

​

Default settings

{
  "agent": "security-reviewer"
}

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

​

Themes and output styles

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

​

Channels

{
  "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
        }
      }
    }
  ]
}

​

Monitors

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

• 対話型セッションのみ: プラグインモニターは対話型セッションで開始され、-p フラグを使用した非対話型モードでは開始されません。また、Monitor ツールが利用可能な場所でのみ開始されます。
• ユーザー設定なし: command はパス変数と環境からの ${ENV_VAR} を取得しますが、${user_config.*} は取得しません。1 つを参照するモニターは開始されず、モニタープロセスは 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 の動作を意図した方法で変更することを確認します
• プラグインを公開および配布する：プラグインをバージョン管理し、マーケットプレイスに配置します
• プラグインのトラブルシューティング：コンポーネントが読み込まれない場合またはフックが発火しない場合の対処方法