Claude Codeプラグイン化の移行手順 — hooks/skills/agentsを移す
既存の.claude/配下のcommands・agents・skills・hooksをプラグイン構造へ移す具体的な手順と、CLAUDE.mdが移行対象に含まれない理由をまとめます。
なぜ.claude/構成をプラグイン化するのか
.claude/直下に置いたcommands・agents・skills・hooksは、そのプロジェクトの中だけで完結する個人設定やチーム内の暫定運用には十分です。ただし、他のプロジェクトやチームへ配ろうとすると、フォルダを手でコピーする以外の方法がありません。バージョン管理も更新通知も無く、コピーした側が古いままでも気づけないという弱点を抱えます。
プラグイン化すると、同じ中身をマーケットプレイス経由の/plugin installで配布でき、バージョンをbumpすれば利用側に更新が届きます。すでに動いているものを作り直す必要はなく、既存ファイルをコピーして構造を整えるだけで移行できます。
移行前に確認すること
移行の対象になるのは.claude/commands/、.claude/agents/、.claude/skills/、そしてsettings.jsonのhooksキーです。この4つのうち、実際に持っているものだけを移せばよく、全部揃っている必要はありません。
一点だけ、移行対象に含まれないものがあります。CLAUDE.mdです。プラグインルートにCLAUDE.mdを置いても、プロジェクトコンテキストとしては読み込まれません。プラグインはskills・agents・hooks経由でコンテキストを提供する設計になっており、Claudeのコンテキストに常時読み込ませたい指示があるなら、その内容をスキルとして書き直す必要があります。「CLAUDE.mdをそのままプラグイン化する」手順自体が存在しないため、常時読ませたい指示はスキルへの書き直しが前提になります。
Step1: プラグインの雛形を作る
既存の.claude/フォルダと同じ階層に、新しいプラグイン用のディレクトリを作ります。次のステップで使うcpの相対パスがそのまま通るように、プロジェクトルート直下に置くのがポイントです。
mkdir -p my-plugin/.claude-pluginマニフェストファイルをmy-plugin/.claude-plugin/plugin.jsonに作成します。
{
"name": "my-plugin",
"description": "Migrated from standalone configuration",
"version": "1.0.0"
}Step2: 既存のcommands/agents/skillsをコピーする
持っている設定ディレクトリを、それぞれプラグインルートへコピーします。存在しないディレクトリを指定するとcpは「No such file or directory」と出しますが、コピー対象がないだけなので無視して進めて構いません。
cp -r .claude/commands my-plugin/
cp -r .claude/agents my-plugin/
cp -r .claude/skills my-plugin/ls my-pluginでコピーしたディレクトリが並んでいることを確認します。
Step3: hooksをhooks.jsonへ移す
hooksを使っている場合は、専用のディレクトリを作ります。
mkdir my-plugin/hooksmy-plugin/hooks/hooks.jsonを作成し、settings.jsonやsettings.local.jsonにあるhooksオブジェクトの中身をそのままコピーします。フォーマット自体は変わりません。hookのコマンドは標準入力からJSONを受け取るので、ファイルパスを取り出すにはjqを使います。
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix" }]
}
]
}
}hooksの書き方そのものはClaude Code Hooks完全ガイドで扱っているイベント一覧と設定パターンがそのまま流用できます。
マニフェストで必須のフィールドはnameだけです。authorやhomepage、licenseは任意ですが、社内配布であっても後から誰が作ったプラグインかを追えるように、authorくらいは移行時点で埋めておくと運用が楽になります。
Step4: --plugin-dirでテストする
--plugin-dirフラグでプラグインを読み込み、移行が正しく終わっているか確認します。
claude --plugin-dir ./my-pluginコマンドを実際に叩き、/contextでagentsが表示されているか確認し、各hookが発火する操作を試して効果を確かめます。hookがどのイベントにマッチし、どう終了したかはデバッグログに記録されるので、想定通り発火しないときはまずそこを見ます。
Step5: 配布前にvalidateする
--plugin-dirでの動作確認が終わったら、配布に回す前にclaude plugin validateでマニフェストとコンポーネントのスキーマを検証します。
claude plugin validate ./my-plugin --strict--strictを付けると、未認識のフィールドや型の間違いといった警告もエラー扱いになります。移行元のsettings.jsonからhooksオブジェクトをコピーしただけの状態だと、キー名の大文字小文字の取り違えなど、実行時には気づきにくい間違いが混ざっていることがあるので、配布前に必ず一度通しておきます。
移行後に何が変わるか
同じ機能でも、置き場所と共有範囲が次のように変わります。
スタンドアロン(.claude/) | プラグイン |
|---|---|
| 1プロジェクトでしか使えない | プラグインマーケットプレイス経由で共有できる |
.claude/commands/にファイルを置く | プラグインplugin-name/commands/にファイルを置く |
hooksはsettings.jsonに書く | プラグインhooksはhooks/hooks.jsonに書く |
| 共有には手作業のコピーが要る | プラグイン/plugin installでインストールできる |
| バージョンという概念自体が無い | プラグインplugin.jsonのversionを上げると更新が配られる |
versionフィールドを省略した場合、gitリポジトリ内であればコミットのSHAが暫定的なバージョンとして扱われます。移行したてでまだversionを運用する自信がないなら、いったん1.0.0で固定しておき、実際に配布を始めてから更新フローを整える進め方でも問題ありません。
移行後にhooksが動かないときの追加チェック
コピーしただけのhooks.jsonが発火しないときは、次の順で確認します。
- イベント名は大文字小文字を区別する:
PostToolUseであってpostToolUseではない matcherパターンが対象のツール名と一致しているか: ファイル操作なら"Write|Edit"のように書くtypeがcommand/http/mcp_tool/prompt/agentのいずれかになっているか- スクリプトを直接実行して、スクリプト自体がエラーなく動くか
これらはsettings.jsonにあった頃から変わらない条件ですが、コピー作業の途中でmatcherの範囲を広げすぎたり、typoでイベント名を書き換えてしまったりする事故は起きやすいので、Step4のテストで一つずつ潰しておきます。
移行時に踏みがちな落とし穴
移行が終わった後、元の.claude/側のファイルを削除し忘れると重複が起きます。ただし重複の起き方はコンポーネントによって違うので、両方とも知っておく必要があります。
agentsは上書きが起きます。プロジェクトやユーザーの.claude/agents/にある定義は、同名のプラグイン同梱agentより優先されます。つまり元のファイルを消さない限り、プラグイン版のagentはいつまでも有効になりません。
skillsは上書きされず両方残ります。プラグインのskillは/plugin-name:skill-nameという名前空間付きで登録されるため、元の/skill-nameとは別物として共存します。削除し忘れても動作は壊れませんが、同じスキルが2つの呼び出し名で存在する状態になり、どちらが最新かをチームで混同しやすくなります。
移行が終わったら、.claude/側の元ファイルは速やかに削除しておくのが安全です。
なおcommands/にコピーしたフラットな.mdファイルも、agentsと違ってskillsと同じ扱いです。公式ドキュメントがプラグインの上書き規則の対象としているのはagentsとskillsで、commands/はスキルをフラットなMarkdownで置く形式なので同じ名前空間の規則が適用されます。つまりプラグインの名前空間が付いた呼び出し名になり、元の.claude/commands/側を消さなくても上書きで壊れることはありません。上書きの有無で覚えるべきは「実行のたびにClaudeが選ぶagents」と「呼び出し名で指定するskills・commands」という違いだけです。
agentのfrontmatterで使えなくなるフィールド
.claude/agents/にあったMarkdownファイルをそのままコピーしても、フロントマターの一部フィールドはプラグイン同梱agentでは扱われません。セキュリティ上の理由でhooks・mcpServers・permissionModeはプラグイン同梱agentでは非対応で、書いてあっても無視されます。
一方、次のフィールドはそのまま使えます。
name/description/model/effort/maxTurnstools/disallowedTools/skillsmemory/background/isolation(値は"worktree"のみ)
影響が出るのは自前でhooksやMCPサーバー、権限モードを埋め込んでいたagentに限られます。
もう一点、エラー時の挙動も変わります。標準の.claude/agents/では、nameが無い、あるいはフロントマターがパースできないファイルはスキップされて読み込まれません。ところがプラグイン同梱agentでは、nameが無ければファイル名から名前が補われ、パースできない場合も「my-pluginプラグインのagent」という説明文でそのまま読み込まれます。移行前に気づかず放置していた壊れたagentファイルが、移行後は静かに有効化されてしまうことがあるので、コピーしたagents/はclaude plugin validate ./my-pluginで一度検証してから使い始めます。
マーケットプレイスで配布する次のステップ
移行した時点ではまだ--plugin-dirでのローカル読み込みにすぎません。チームや社外に配るには、marketplace.jsonをgitでホストして/plugin marketplace addしてもらうか、コミュニティマーケットプレイスへ提出する必要があります。配布方法の使い分けはClaude Codeプラグイン(Plugins)完全ガイドにまとめてあるので、移行後の配布判断はそちらを参照してください。エージェント定義の書き方を見直したい場合はClaude Code Sub-agents完全ガイド、スキルの構成を作り直したい場合はClaude Code Skills完全ガイドが土台になります。
よくある質問
CLAUDE.mdはどうやってプラグイン化すればいいですか
そのままの形では移行できません。プラグインルートに置いたCLAUDE.mdはプロジェクトコンテキストとして読み込まれない仕様なので、常時読ませたい指示はスキルとして書き直します。
hooksのコマンド自体は書き換えが必要ですか
フォーマットは同じなので、settings.jsonのhooksオブジェクトをそのままhooks/hooks.jsonに貼り付けるだけで動きます。パスに${CLAUDE_PLUGIN_ROOT}を使っている場合は、移行後もそのまま有効です。
移行後、元の.claude/ファイルはいつ消せばいいですか
--plugin-dirでのテストが一通り終わり、コマンド・agents・hooksが期待通り動くことを確認してからで問題ありません。agentsは元ファイルが残っている限りプラグイン版が有効にならないので、確認後は早めに消すのが安全です。
commandsとskillsはどちらでコピーすればよいですか
新規に作るならskills/形式が推奨されますが、移行では既存の.claude/commands/をそのままcommands/としてコピーして問題ありません。フラットな.mdファイルはcommands/のままでも読み込まれます。
まとめ
.claude/配下のcommands・agents・skills・hooksは、新しいディレクトリへのコピーとマニフェストの追加だけでプラグイン化できます。ただしCLAUDE.mdは対象外で、常時コンテキストに載せたい内容はスキルへの書き直しが必要です。agentsは元ファイルが残っていると上書きされて有効にならず、skillsは名前空間が変わって両方残る、という違いを踏まえてから元ファイルを削除します。