プラグインリファレンス

​

プラグインコンポーネントリファレンス

​

Skills

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (optional)
│   └── scripts/ (optional)
└── code-reviewer/
    └── SKILL.md

• Skills と commands はプラグインがインストールされると自動的に検出されます
• Claude はタスクコンテキストに基づいて自動的にそれらを呼び出すことができます
• Skills は SKILL.md の横にサポートファイルを含めることができます

​

Agents

---
name: agent-name
description: このエージェントが専門とする内容と、Claude がそれを呼び出すべき時期
---

エージェントの役割、専門知識、動作を説明する詳細なシステムプロンプト。

• Agents は /agents インターフェイスに表示されます
• Claude はタスクコンテキストに基づいて自動的にエージェントを呼び出すことができます
• Agents はユーザーが手動で呼び出すことができます
• プラグインエージェントは組み込みの Claude エージェントと一緒に動作します

​

Hooks

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

• PreToolUse: Claude がツールを使用する前
• PostToolUse: Claude がツールを正常に使用した後
• PostToolUseFailure: Claude ツール実行が失敗した後
• PermissionRequest: パーミッションダイアログが表示されるとき
• UserPromptSubmit: ユーザーがプロンプトを送信するとき
• Notification: Claude Code が通知を送信するとき
• Stop: Claude が停止を試みるとき
• SubagentStart: subagent が開始されるとき
• SubagentStop: subagent が停止を試みるとき
• SessionStart: セッションの開始時
• SessionEnd: セッションの終了時
• TeammateIdle: エージェントチームのチームメイトがアイドル状態になろうとしているとき
• TaskCompleted: タスクが完了としてマークされているとき
• PreCompact: 会話履歴がコンパクト化される前

• command: シェルコマンドまたはスクリプトを実行
• prompt: LLM でプロンプトを評価（コンテキストの $ARGUMENTS プレースホルダーを使用）
• agent: 複雑な検証タスク用のツール付き agentic verifier を実行

​

MCP servers

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    },
    "plugin-api-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

• プラグイン MCP servers はプラグインが有効になると自動的に開始されます
• Servers は Claude のツールキットに標準 MCP ツールとして表示されます
• サーバー機能は Claude の既存ツールとシームレスに統合されます
• プラグインサーバーはユーザー MCP servers とは独立して設定できます

​

LSP servers

• 即座の診断: Claude は各編集後すぐにエラーと警告を確認できます
• コードナビゲーション: 定義へのジャンプ、参照の検索、ホバー情報
• 言語認識: コードシンボルの型情報とドキュメント

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

{
  "name": "my-plugin",
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": {
        ".go": "go"
      }
    }
  }
}

​

プラグインインストールスコープ

​

プラグインマニフェストスキーマ

​

完全なスキーマ

{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "[email protected]",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "commands": ["./custom/commands/special.md"],
  "agents": "./custom/agents/",
  "skills": "./custom/skills/",
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json"
}

​

必須フィールド

​

メタデータフィールド

​

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

​

パス動作ルール

• commands/ が存在する場合、カスタムコマンドパスに加えてロードされます
• すべてのパスはプラグインルートに相対的で、./ で始まる必要があります
• カスタムパスからのコマンドは同じ命名と名前空間ルールを使用します
• 複数のパスを配列として指定して柔軟性を確保できます

{
  "commands": [
    "./specialized/deploy.md",
    "./utilities/batch-process.md"
  ],
  "agents": [
    "./custom-agents/reviewer.md",
    "./custom-agents/tester.md"
  ]
}

​

環境変数

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/process.sh"
          }
        ]
      }
    ]
  }
}

​

プラグインキャッシングとファイル解決

• claude --plugin-dir を通じて、セッションの期間。
• マーケットプレイスを通じて、将来のセッション用にインストール。

​

パストラバーサル制限

​

外部依存関係の操作

# プラグインディレクトリ内
ln -s /path/to/shared-utils ./shared-utils

​

プラグインディレクトリ構造

​

標準プラグインレイアウト

enterprise-plugin/
├── .claude-plugin/           # メタデータディレクトリ（オプション）
│   └── plugin.json             # プラグインマニフェスト
├── commands/                 # デフォルトコマンド場所
│   ├── status.md
│   └── logs.md
├── agents/                   # デフォルトエージェント場所
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── skills/                   # エージェント Skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── hooks/                    # Hook 設定
│   ├── hooks.json           # メイン hook 設定
│   └── security-hooks.json  # 追加 hooks
├── settings.json            # プラグインのデフォルト設定
├── .mcp.json                # MCP サーバー定義
├── .lsp.json                # LSP サーバー設定
├── scripts/                 # Hook とユーティリティスクリプト
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # ライセンスファイル
└── CHANGELOG.md             # バージョン履歴

​

ファイル場所リファレンス

​

CLI コマンドリファレンス

​

plugin install

claude plugin install <plugin> [options]

• <plugin>: プラグイン名または特定のマーケットプレイス用の plugin-name@marketplace-name

# ユーザースコープにインストール（デフォルト）
claude plugin install formatter@my-marketplace

# プロジェクトスコープにインストール（チームと共有）
claude plugin install formatter@my-marketplace --scope project

# ローカルスコープにインストール（gitignored）
claude plugin install formatter@my-marketplace --scope local

​

plugin uninstall

claude plugin uninstall <plugin> [options]

• <plugin>: プラグイン名または plugin-name@marketplace-name

​

plugin enable

claude plugin enable <plugin> [options]

• <plugin>: プラグイン名または plugin-name@marketplace-name

​

plugin disable

claude plugin disable <plugin> [options]

• <plugin>: プラグイン名または plugin-name@marketplace-name

​

plugin update

claude plugin update <plugin> [options]

• <plugin>: プラグイン名または plugin-name@marketplace-name

​

デバッグと開発ツール

​

デバッグコマンド

• どのプラグインが読み込まれているか
• プラグインマニフェストのエラー
• コマンド、エージェント、hook 登録
• MCP サーバー初期化

​

一般的な問題

​

エラーメッセージの例

• Invalid JSON syntax: Unexpected token } in JSON at position 142: コンマの欠落、余分なコンマ、またはクォートされていない文字列を確認
• Plugin has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Required: 必須フィールドが不足
• Plugin has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...: JSON 構文エラー

• Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.: コマンドパスが存在するが有効なコマンドファイルが含まれていない
• Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.: marketplace.json の source パスが存在しないディレクトリを指している
• Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.: 重複するコンポーネント定義を削除するか、marketplace エントリから strict: false を削除

​

Hook トラブルシューティング

1. スクリプトが実行可能であることを確認: chmod +x ./scripts/your-script.sh
2. shebang 行を確認: 最初の行は #!/bin/bash または #!/usr/bin/env bash である必要があります
3. パスが ${CLAUDE_PLUGIN_ROOT} を使用していることを確認: "command": "${CLAUDE_PLUGIN_ROOT}/scripts/your-script.sh"
4. スクリプトを手動でテスト: ./scripts/your-script.sh

1. イベント名が正しいことを確認（大文字小文字を区別）: PostToolUse、postToolUse ではない
2. マッチャーパターンがツールと一致することを確認: ファイル操作の場合 "matcher": "Write|Edit"
3. hook タイプが有効であることを確認: command、prompt、または agent

​

MCP サーバートラブルシューティング

1. コマンドが存在し、実行可能であることを確認
2. すべてのパスが ${CLAUDE_PLUGIN_ROOT} 変数を使用していることを確認
3. MCP サーバーログを確認: claude --debug は初期化エラーを表示
4. Claude Code の外部でサーバーを手動でテスト

1. サーバーが .mcp.json または plugin.json で正しく設定されていることを確認
2. サーバーが MCP プロトコルを正しく実装していることを確認
3. デバッグ出力で接続タイムアウトを確認

​

ディレクトリ構造の間違い

my-plugin/
├── .claude-plugin/
│   └── plugin.json      ← マニフェストのみここ
├── commands/            ← ルートレベル
├── agents/              ← ルートレベル
└── hooks/               ← ルートレベル

1. claude --debug を実行し、「loading plugin」メッセージを探す
2. 各コンポーネントディレクトリがデバッグ出力にリストされていることを確認
3. プラグインファイルを読み取ることができるファイルパーミッションを確認

​

配布とバージョン管理リファレンス

​

バージョン管理

{
  "name": "my-plugin",
  "version": "2.1.0"
}

• MAJOR: 破壊的変更（互換性のない API 変更）
• MINOR: 新機能（後方互換性のある追加）
• PATCH: バグ修正（後方互換性のある修正）

• 最初の安定リリースは 1.0.0 から開始
• 変更を配布する前に plugin.json のバージョンを更新
• CHANGELOG.md ファイルで変更を文書化
• テスト用に 2.0.0-beta.1 のようなプレリリースバージョンを使用

​

関連項目

• プラグイン - チュートリアルと実践的な使用法
• プラグインマーケットプレイス - マーケットプレイスの作成と管理
• Skills - Skill 開発の詳細
• Subagents - エージェント設定と機能
• Hooks - イベント処理と自動化
• MCP - 外部ツール統合
• 設定 - プラグインの設定オプション