0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@kai_kou(甲斐 甲)

Claude Code プラグイン入門 — Skills・Hooks・MCPをチームで共有する完全ガイド

0
Posted at

Claude Code プラグインシステム全体像

はじめに

Claude Code には、カスタムスキルや自動化フックを .claude/ ディレクトリに追加する「スタンドアロン設定」が以前から存在します。しかし、この設定はプロジェクト固有のため、チームや別プロジェクトへの共有が手間でした。

この課題を解決するのが Claude Code プラグインシステムです。Skills・Hooks・MCP サーバーを「プラグイン」という単位にパッケージ化し、1コマンドでインストール・チーム共有・公開マーケットプレイスへの配布ができます。

この記事で解説すること

  • スタンドアロン設定とプラグインの違い
  • 最初のプラグインを作成するクイックスタート
  • Skills・Hooks・MCPを含む複合プラグインの構築
  • チームや OSS コミュニティへの配布方法
  • 既存の .claude/ 設定をプラグイン化する手順

対象読者

  • Claude Code のカスタムスキルやフックをチームで共有したい方
  • 組織内や OSS として Claude Code 拡張機能を配布したい方
  • .claude/ ディレクトリの設定をより体系的に管理したい方

前提条件

  • Claude Code がインストール・認証済みであること
  • Bash・Git の基本操作を理解していること

TL;DR

  • プラグイン = Skills + Hooks + MCP を1ディレクトリにまとめ、チームや公開マーケットプレイスで共有できる Claude Code 拡張単位
  • マニフェストファイル .claude-plugin/plugin.json が必須。それ以外は skills/・hooks/・.mcp.json などをプラグインルートに配置
  • --plugin-dir ./my-plugin で開発・テスト、/plugin install name@marketplace でインストール
  • 公式マーケットプレイスへの申請は claude.ai/settings/plugins/submit から

スタンドアロン設定 vs プラグイン

Claude Code でカスタム機能を追加する方法は2種類あります。

観点 スタンドアロン（.claude/） プラグイン
スキル名 /hello /my-plugin:hello
主な用途 個人ワークフロー・単一プロジェクト チーム共有・複数プロジェクト・OSS配布
バージョン管理 手動コピー version フィールド / git SHA
インストール ファイルコピーのみ claude plugin add 1コマンド
マーケットプレイス配布 不可 公式・プライベート両対応

スタンドアロンが向くケース:

  • 単一プロジェクト内の一時的な実験
  • /hello のような短いスキル名を使いたい場合

プラグインが向くケース:

  • 同じ設定を複数プロジェクトで使い回したい場合
  • チームメンバーに 1 コマンドで配布したい場合
  • OSS として公開マーケットプレイスへ提出したい場合

スタンドアロン設定でまず動作を確認し、共有する段階でプラグイン化するのがおすすめのワークフローです。

クイックスタート: 最初のプラグインを作成する

ステップ 1: ディレクトリとマニフェストを作成する

mkdir my-first-plugin
mkdir my-first-plugin/.claude-plugin

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

{
  "name": "my-first-plugin",
  "description": "スキルのサンプルプラグイン",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}
フィールド 必須 説明
name ✅ スキルの名前空間になる（例: /my-first-plugin:hello）
description ✅ プラグインマネージャーに表示される説明
version 任意 省略時は git コミット SHA がバージョンとして使われる
author 任意 帰属表示に利用

よくある間違い: commands/・agents/・skills/・hooks/ を .claude-plugin/ の中に入れないでください。.claude-plugin/ に置くのは plugin.json のみです。それ以外はプラグインルートに配置します。

ステップ 2: スキルを追加する

mkdir -p my-first-plugin/skills/hello

my-first-plugin/skills/hello/SKILL.md を作成します:

---
description: ユーザーをフレンドリーに挨拶する
---

"$ARGUMENTS" という名前のユーザーに、温かみのある挨拶をしてください。

$ARGUMENTS はスキル呼び出し時のユーザー入力を受け取るプレースホルダーです。

ステップ 3: 開発中にテストする

claude --plugin-dir ./my-first-plugin

Claude Code が起動したら、スキルを呼び出します:

/my-first-plugin:hello Alex

変更を加えたときは再起動不要で /reload-plugins を実行するだけでプラグインが再読み込みされます。

プラグインディレクトリ構造の全体像

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

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # マニフェスト（必須）
├── skills/
│   └── code-review/
│       └── SKILL.md         # カスタムスキル
├── agents/
│   └── security-reviewer.md # カスタムエージェント定義
├── hooks/
│   └── hooks.json           # イベントハンドラ設定
├── .mcp.json                # MCPサーバー設定
├── .lsp.json                # LSPサーバー設定
├── monitors/
│   └── monitors.json        # バックグラウンドモニター設定
├── bin/                     # Bash ツール PATH に追加される実行ファイル
├── settings.json            # プラグイン有効時のデフォルト設定
└── README.md
ディレクトリ/ファイル 役割
.claude-plugin/plugin.json プラグインのメタデータ（唯一の必須ファイル）
skills/ <name>/SKILL.md 形式のカスタムスキル
agents/ カスタムエージェント定義
hooks/hooks.json イベントハンドラ設定（PreToolUse・PostToolUse等）
.mcp.json MCPサーバー設定（プラグイン有効化時に自動起動）
monitors/monitors.json バックグラウンドモニター（ログ監視など）
bin/ プラグイン有効時に PATH へ追加される実行ファイル
settings.json プラグイン有効時のデフォルト設定

各コンポーネントの実装例

Skills（カスタムスキル）

スキルはモデルが自動的に使用するカスタムコマンドです。description フィールドでいつ使うかを明示します:

# skills/code-review/SKILL.md
---
description: コードのベストプラクティスと潜在的な問題をレビューする。PRのレビューやコード品質チェック時に使用する。
---

コードをレビューする際は以下を確認してください:
1. コードの構成とアーキテクチャ
2. エラーハンドリングの適切さ
3. セキュリティ上の懸念
4. テストカバレッジ

Hooks（イベントハンドラ）

hooks/hooks.json でイベントに応じた自動処理を定義します:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix"
          }
        ]
      }
    ]
  }
}

主要なイベント（抜粋）: PreToolUse・PostToolUse・Stop・SubagentStop・SessionStart・SessionEnd・UserPromptSubmit・PreCompact・Notification（全イベントはHooks referenceを参照）

MCP サーバー（.mcp.json）

MCPサーバーをプラグインに組み込むと、プラグイン有効化時に自動起動します:

{
  "mcpServers": {
    "my-service": {
      "command": "npx",
      "args": ["-y", "@my-org/my-mcp-server"],
      "env": {
        "API_KEY": "${MY_SERVICE_API_KEY}"
      }
    }
  }
}

バックグラウンドモニター（monitors/monitors.json）

ファイルやログを監視し、変化があると Claude に通知します:

[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "アプリケーションエラーログ"
  }
]

デフォルト設定（settings.json）

プラグイン有効時に自動適用する設定を定義します。agent を指定するとプラグイン内のカスタムエージェントがメインスレッドとして使われます:

{
  "agent": "security-reviewer"
}

チームへの配布方法

Claude Code プラグイン配布フロー

インストール方法

プラグインはマーケットプレイスを経由してインストールします。まずマーケットプレイスを追加し、その後プラグインをインストールします:

# マーケットプレイスを追加する（例: Anthropic公式デモ集）
/plugin marketplace add anthropics/claude-code

# マーケットプレイスからプラグインをインストール
/plugin install commit-commands@anthropics-claude-code

# CLIから直接インストール（スコープ指定可）
claude plugin install my-plugin@my-org --scope project

開発・テスト時は --plugin-dir フラグでローカルプラグインを直接ロードできます（マーケットプレイス登録不要）:

# ローカルディレクトリから（開発時テスト）
claude --plugin-dir ./my-plugin

# ZIPアーカイブから（Claude Code 最新版）
claude --plugin-dir ./my-plugin.zip

プライベートマーケットプレイス（チーム内配布）

プライベートGitリポジトリをマーケットプレイスとして使用できます。プロジェクトの .claude/settings.json に extraKnownMarketplaces を追加すると、チームメンバーがリポジトリを信頼した際に自動的にマーケットプレイスが登録されます:

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

公開マーケットプレイスへの申請

Anthropic の公式マーケットプレイスへの申請フォームは以下から利用できます:

申請が承認されると、ユーザーは /plugin install からワンクリックでインストールできるようになります。

既存の .claude/ 設定をプラグイン化する

すでに .claude/ にスキルやフックを持っている場合、以下の手順でプラグインに移行できます。

ステップ 1: プラグイン構造を作成する

mkdir -p my-plugin/.claude-plugin
cat > my-plugin/.claude-plugin/plugin.json << 'EOF'
{
  "name": "my-plugin",
  "description": "スタンドアロン設定から移行",
  "version": "1.0.0"
}
EOF

ステップ 2: 既存ファイルをコピーする

# コマンド（旧形式）のコピー
cp -r .claude/commands my-plugin/

# スキルのコピー（新形式 skills/ がある場合）
cp -r .claude/skills my-plugin/

# エージェントのコピー
cp -r .claude/agents my-plugin/

ステップ 3: フックを移行する

.claude/settings.json の hooks セクションを my-plugin/hooks/hooks.json にコピーします。フォーマットは同一です。

ステップ 4: テストする

claude --plugin-dir ./my-plugin
スタンドアロン（.claude/） プラグイン
1プロジェクトのみ 複数プロジェクトで共有可
.claude/commands/ plugin-name/commands/
settings.json の hooks hooks/hooks.json
手動コピーで共有 /plugin install name@marketplace で配布

移行後は .claude/ の元ファイルを削除して重複を防いでください。

プラグイン管理コマンド

# プラグインマネージャーを開く（一覧・インストール・設定）
/plugin

# プラグインを無効化（アンインストールせずに）
/plugin disable my-plugin@my-marketplace

# プラグインを再有効化
/plugin enable my-plugin@my-marketplace

# プラグインをアンインストール
/plugin uninstall my-plugin@my-marketplace

# マーケットプレイスを更新（最新プラグイン一覧を取得）
/plugin marketplace update marketplace-name

# 複数プラグインを同時に読み込む（開発時）
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

プラグインの変更を反映するには /reload-plugins を実行します。スキル・エージェント・フック・MCP サーバー・LSP サーバーすべてが再読み込みされます。

まとめ

Claude Code のプラグインシステムは、スタンドアロン設定を超えたカスタマイズの「配布単位」を提供します。

  • .claude-plugin/plugin.json を作成するだけでプラグインとして認識される
  • Skills・Hooks・MCP・モニターなど多彩なコンポーネントを1パッケージにまとめられる
  • /plugin marketplace add username/repo でマーケットプレイスを追加し、チームへの配布が可能
  • プライベートマーケットプレイス（組織内）と公式マーケットプレイス（OSS）の両方に対応

チームで共通のワークフロー自動化や、OSS として Claude Code 拡張機能を公開したい場合は、ぜひプラグインシステムの活用を検討してください。

参考リンク

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?