「Claude Codeのプラグインを使ったことはあるけど、自分で作るとなると何から始めればいいのか……」
先日、社内ツールのコードレビューワークフローを標準化したくて、Claude Codeプラグインを自作してみました。調べ始めると、プラグインのディレクトリ構造・plugin.json・bin/ディレクトリ・Marketplace公開と、必要な知識が予想以上に広い。でも一度整理してしまえば、チームの開発体験がガラリと変わりました。
この記事では、Claude Codeプラグインを0から自作し、Marketplaceに公開するまでの全手順を、コピペ可能なコード・設定例とともに解説します。2026年4月時点の最新仕様（v2.1.91）に対応しています。
最初から複雑なプラグインを作ろうとすると詰まります。まず動く最小構成を作り、そこから拡張するのが正解です。
即効テクニック1：plugin.jsonだけで始める最小プラグイン
Claude Codeプラグインに最低限必要なのは、.claude-plugin/plugin.json だけです。
# プラグインディレクトリを作成
mkdir -p my-first-plugin/.claude-plugin
cd my-first-plugin// .claude-plugin/plugin.json
{
"name": "my-first-plugin",
"version": "1.0.0",
"description": "最初のプラグイン",
"author": "Your Name"
}これだけでインストール可能なプラグインになります。
# ローカルディレクトリからインストール
claude /plugin install ./my-first-plugin
# インストール確認
claude /plugin list動作環境: Claude Code v2.1.51+、macOS / Linux / Windows（cmd /c ラッパー必須）
即効テクニック2：スラッシュコマンドを追加する
プラグインにスラッシュコマンドを追加するには、commands/ ディレクトリにMarkdownファイルを配置します。
mkdir commands
cat > commands/review.md << 'EOF'
---
name: review
description: "コードレビューチェックリストを実行"
---
以下のチェックリストでコードをレビューしてください：
1. 変数名・関数名が意図を明確に表しているか
2. エラーハンドリングが適切か
3. テストカバレッジが80%以上あるか
4. セキュリティリスク（SQLインジェクション、XSS等）がないか
5. パフォーマンスのボトルネックがないか
$ARGUMENTS で指定されたファイルまたはディレクトリを対象にします。
EOFこれで /review src/ のように呼び出せます。
ポイント: $ARGUMENTS でユーザーが渡した引数を受け取れます。スラッシュコマンドはMarkdownで記述するため、プロンプトエンジニアリングの知識がそのまま使えます。
即効テクニック3：bin/ディレクトリで実行可能ファイルを追加する（v2.1.91新機能）
2026年4月1日リリースのv2.1.91から、プラグインの bin/ ディレクトリがBashツールのPATHに自動追加されます。これにより、CLIヘルパーをコマンドやエージェントと同じプラグインにパッケージングできます。
mkdir bin
# カスタムCLIツールを作成
cat > bin/check-deps </dev/null | python3 -c "
import sys, json
data = json.load(sys.stdin)
vulns = data.get('metadata', {}).get('vulnerabilities', {})
total = sum(vulns.values())
print(f'脆弱性: 合計{total}件 (high:{vulns.get("high",0)}, critical:{vulns.get("critical",0)})')
"
fi
if [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
echo "[Python] pip-audit を実行中..."
pip-audit 2>/dev/null || echo "pip-audit 未インストール: pip install pip-audit"
fi
echo "=== チェック完了 ==="
EOF
chmod +x bin/check-depsプラグインを有効にした状態でClaudeから check-deps を呼び出すだけで実行できます。絶対パスもラッパースクリプトも不要です。
プラグインの全体構造を理解する「5層アーキテクチャ」
Claude Codeプラグインは最大5つのコンポーネントで構成されます。
| コンポーネント | ディレクトリ/ファイル | 役割 | 典型的なユースケース |
|---|---|---|---|
| プラグイン定義 | .claude-plugin/plugin.json | メタデータ・依存関係 | 必須。バージョン管理、依存プラグイン指定 |
| スラッシュコマンド | commands/*.md | 頻出手順のショートカット | /review, /deploy, /test など |
| エージェント | agents/*.md | 特定タスク専用のAI | コードレビュー専門エージェント、デプロイ専門エージェント |
| 実行可能ファイル | bin/* | CLIツール（v2.1.91+） | 依存関係チェック、コード品質スキャン |
| Hooks | hooks/*.json | イベント駆動の自動実行 | ファイル保存後の自動フォーマット、コミット前検証 |
| MCPサーバー | .mcp.json | 外部ツール連携 | Slack通知、Jira更新、GitHub PR作成 |
AIエージェントの構築パターン全般については、AIエージェント構築完全ガイドで体系的にまとめています。
実践：コードレビュープラグインを完成させる
ここまでの知識を組み合わせ、実用的なコードレビュープラグインを作ります。
完成ディレクトリ構造
code-review-plugin/
├── .claude-plugin/
│ └── plugin.json
├── commands/
│ ├── review.md # /review コマンド
│ └── fix.md # /fix コマンド
├── agents/
│ └── reviewer.md # コードレビュー専門エージェント
├── hooks/
│ └── pre-commit.json # コミット前の自動チェック
├── bin/
│ └── check-deps # 依存関係チェックスクリプト
└── .mcp.json # GitHub連携plugin.json（完成版）
{
"name": "code-review-plugin",
"version": "1.0.0",
"description": "自動コードレビュー・品質チェックプラグイン",
"author": "Your Name",
"homepage": "https://github.com/yourname/code-review-plugin",
"keywords": ["code-review", "quality", "ci"],
"engines": {
"claude-code": ">=2.1.51"
}
}コミット前フック（hooks/pre-commit.json）
{
"hooks": {
"PostToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "check-deps",
"description": "依存関係の脆弱性を自動チェック"
}
]
}
],
"PermissionDenied": [
{
"matcher": "*",
"hooks": [
{
"type": "command",
"command": "echo '[Plugin] Permission denied. 別のアプローチを試みます。'",
"retry": true
}
]
}
]
}
}動作環境: Claude Code v2.1.86+（PermissionDenied hookはv2.1.91+）
ポイント: v2.1.91から新しく追加された PermissionDenied フックを使うと、権限拒否時に別アプローチを試みるよう指示できます。retry: true を返すとClaudeが別の方法を検討します。
GitHub MCP連携（.mcp.json）
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
Marketplaceへの公開手順
作ったプラグインを他の人に使ってもらうには、GitHubリポジトリに公開し、Marketplace登録します。
1. GitHubにプッシュする
cd code-review-plugin
git init
git add .
git commit -m "feat: initial code review plugin"
git remote add origin https://github.com/yourname/code-review-plugin.git
git push -u origin main2. marketplace.jsonを作成する
Marketplaceとして公開するには、GitHubリポジトリのルートに .claude-plugin/marketplace.json が必要です。
{
"name": "Code Review Tools",
"description": "コードレビュー・品質チェックプラグインのコレクション",
"plugins": [
{
"name": "code-review-plugin",
"path": ".",
"description": "自動コードレビュー・依存関係チェック"
}
]
}3. ユーザーがインストールする方法
# Marketplaceを追加（GitHubユーザー名/リポジトリ名）
claude /plugin marketplace add yourname/code-review-plugin
# プラグインをインストール
claude /plugin install code-review-plugin
# 有効化確認
claude /plugin list【要注意】よくある失敗パターンと回避策
失敗1：Windowsで「Connection closed」エラーが出る
❌ よくある間違い: npx をそのまま使う
{
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"]
}⭕ 正しいアプローチ: Windows は cmd /c ラッパーが必須
{
"command": "cmd",
"args": ["/c", "npx", "-y", "@modelcontextprotocol/server-github"]
}なぜ重要か: Windowsはnpxを直接実行できないため、cmd.exe経由でラップする必要があります。macOS/Linuxでは不要です。
失敗2：bin/スクリプトが実行されない
❌ よくある間違い: 実行権限を忘れる
# NGパターン: chmod +x していない
ls -la bin/
# -rw-r--r-- 1 user staff 512 Apr 10 10:00 check-deps⭕ 正しいアプローチ: 必ず実行権限を付与する
chmod +x bin/check-deps
ls -la bin/
# -rwxr-xr-x 1 user staff 512 Apr 10 10:00 check-depsなぜ重要か: Claude Codeはbin/ディレクトリをPATHに追加しますが、実行権限がないとPermission deniedエラーになります。Gitでの権限保持も確認してください（git update-index --chmod=+x bin/check-deps）。
失敗3：スラッシュコマンドがプラグイン無効時に消えない
❌ よくある間違い: グローバルの ~/.claude/commands/ にコマンドを混在させる
⭕ 正しいアプローチ: プラグインのコマンドはプラグインの commands/ ディレクトリのみに配置する
なぜ重要か: プラグインを無効にしたときにコマンドも一緒に無効化されるため、プロジェクト固有のコマンドはプラグイン内に閉じ込めるべきです。
失敗4：PermissionDenied hookのretryが無限ループになる
❌ よくある間違い: 条件なしで常に retry: true を返す
⭕ 正しいアプローチ: 特定のエラーパターンにのみ retry: true を返す
#!/bin/bash
# hooks/handle-permission-denied.sh
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
ERROR_MSG="${CLAUDE_TOOL_ERROR:-}"
# 書き込みエラーの場合のみリトライ
if echo "$ERROR_MSG" | grep -q "EACCES|Permission denied|read-only"; then
echo '{"retry": true, "message": "別の場所に書き込みを試みます"}'
else
echo '{"retry": false}'
fiセキュリティと運用ルール
| チェック項目 | 対策 |
|---|---|
| APIキー・シークレット | ${ENV_VAR} 形式で環境変数参照。.mcp.jsonにハードコードNG |
| bin/スクリプトの権限 | chmod +x と git update-index –chmod=+x を両方実施 |
| disableSkillShellExecution | インラインシェル実行をブロックしたい場合は設定で制御可能（v2.1.91+） |
| Marketplace公開前 | README.mdに必要な環境変数・権限を明記する |
| フック無限ループ | PermissionDenied hookは必ず条件分岐を入れる |
参考・出典
- Week 14 · March 30 – April 3, 2026 – Claude Code Docs — Anthropic公式（参照日: 2026-04-11）
- claude-code/plugins/README.md – GitHub — Anthropic公式GitHubリポジトリ（参照日: 2026-04-11）
- Customize Claude Code with plugins | Claude — Anthropic公式ブログ（参照日: 2026-04-11）
- awesome-claude-code – GitHub — コミュニティプラグインキュレーション（参照日: 2026-04-11）
まとめ：今日から始める3つのアクション
- 今日やること:
mkdir -p my-plugin/.claude-pluginとplugin.jsonを作成し、claude /plugin install ./my-pluginで最小プラグインを動かしてみる - 今週中: チームで繰り返しているワークフロー（コードレビュー、デプロイ確認、テスト実行）をスラッシュコマンドに変換し、効果を確認する
- 今月中: bin/ディレクトリにCLIツールを追加し、GitHubに公開してチームメンバーと共有する
あわせて読みたい:
- AIエージェント構築完全ガイド — エージェントアーキテクチャの基礎から実装まで
- Claude Code Hooks完全ガイド — PreToolUse/PostToolUseの実践的な使い方
著者: 佐藤傑（さとう・すぐる）
株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー10万人超。100社以上の企業向けAI研修・導入支援。著書累計3万部突破。SoftBank IT連載7回執筆（NewsPicks最大1,125ピックス）。
ご質問・ご相談は お問い合わせフォーム からお気軽にどうぞ。
