この記事の目次
Claude Code pluginの作り方は、空のフォルダに .claude-plugin/plugin.json（manifest）とskill 1つを置き、claude plugin validate で検証してから claude --plugin-dir で読み込む、という流れです。マーケットプレイスへの登録は要りません。最初の1手は mkdir -p my-first-plugin/.claude-plugin で、ファイルを置いたあと claude plugin validate ./my-first-plugin が ✔ Validation passed を表示すれば検証は通過です。続けて claude --plugin-dir ./my-first-plugin で起動し、/my-first-plugin:hello を打つとClaudeが挨拶を返します。本記事は公式の制作ページ（Create a Claude Code plugin）の手順に沿い、検証エラーの読み方と、読み込めないときの確認順を足して整理します。
Claude Code pluginとは何で、いつ作るべきか
公式の定義では、pluginはskill、agent、hook、MCPサーバーと、それらに名前を付ける plugin.json（manifest）をまとめたディレクトリです。Claude Codeはこのディレクトリを1つの単位として読み込みます。
作るかどうかの判断基準も公式に書かれています。skillやhookは単体でも動き、~/.claude/skills/ に置いたskillは自分のマシンの全プロジェクトで使えます。単体の設定が1つのプロジェクトか自分だけの用途で足りているうちは、そのままでかまいません。pluginにするのは、次のどれかに当てはまるときです。
- チームメンバーに同じ設定を配りたい
- 複数のプロジェクトに入れたい
- バージョンを付けて公開したい
pluginにすると、skillとagentの呼び名にplugin名が付きます。my-plugin の hello skillは /my-plugin:hello になり、別のpluginに同じ名前のskillがあっても衝突しません。
他人が作ったpluginを選んで入れる側の話はClaude Codeのプラグインの記事、skill単体の書き方はClaude Codeのスキルの記事で扱っています。
最小のpluginはどんなファイル構成か
最小構成は、manifestとskill 1つです。公式は「必須のコンポーネントはない」としたうえで、skill 1つを構成要素を示す最小の例として使っています。前提は、Claude Codeがインストール済みで、サインインしていることだけです。
完成時のファイル配置は次のとおりです。
| 場所 | 中身 |
|---|---|
my-first-plugin/.claude-plugin/plugin.json |
manifest。pluginの名前と説明 |
my-first-plugin/skills/hello/SKILL.md |
skill本体。skillごとに1ディレクトリ |
注意したいのは skills/ の置き場所です。.claude-plugin/ の中に入れるのは plugin.json だけで、skills/ はその隣、pluginフォルダの直下に置きます。公式は、.claude-plugin/ の中に置いたコンポーネントは読み込まれないと明記しています。
後からagentやhookを足すときも、置き場所は決まっています。
| 場所 | 中身 |
|---|---|
agents/ |
subagentごとに1つのMarkdownファイル |
hooks/hooks.json |
hookの設定 |
.mcp.json |
MCPサーバーの定義 |
commands/ |
skillの旧形式。新しいpluginでは skills/ を使う |
使うディレクトリだけを足せば十分です。hookの中身の書き方はhooksの記事、MCPサーバーの設定はMCPの記事を参照してください。
plugin.jsonには何を書くか
pluginを置きたいフォルダ（例: ~/projects）でターミナルを開き、pluginのディレクトリとmanifest用のフォルダを作ります。
mkdir -p my-first-plugin/.claude-plugin次に my-first-plugin/.claude-plugin/plugin.json を保存します。公式の例は次の内容です。
{
"name": "my-first-plugin",
"description": "A greeting plugin to learn the basics",
"version": "1.0.0",
"author": {
"name": "Your Name"
}
}4つの項目の役割は次のとおりです。
| 項目 | 必須か | 役割 |
|---|---|---|
name |
必須 | pluginの識別子。すべてのskillとagentの接頭辞になる |
description |
任意 | /plugin の画面で利用者に見える説明 |
version |
任意 | 設定すると、変更するまで利用者がその版に留まる |
author |
任意 | 作者。中に入れる場合 name は必須、email と url は任意 |
manifestリファレンスでは、必須のキーは name だけです。
nameで気をつけること
name は空にできず、空白、@、:、パス区切り文字などは使えません。公式はkebab-caseを使うよう求めています。
もう1つの注意は予約名です。claude-、anthropic-、anthropics-、cc-plugin- で始まる名前は、Anthropic自身のpluginと紛らわしいとして検証でエラーになります。mcp-for-claude のように claude を単語として含むだけの名前は警告です。自作pluginには、用途を表す名前を付けます。
なお、manifest自体は省略もできます。その場合、--plugin-dir で読み込むとディレクトリ名がplugin名になります。名前を自分で決められるので、最初から書いておく方が扱いやすくなります。
最初のskillはどう書くか
skillは skills/ の下にディレクトリを1つ作り、その中に SKILL.md を置きます。
mkdir -p my-first-plugin/skills/hellomy-first-plugin/skills/hello/SKILL.md の公式の例です。
---
name: hello
description: Greet the user with a friendly message
disable-model-invocation: true
---
Greet the user warmly and ask how you can help them today.--- で囲んだ部分がfrontmatterです。disable-model-invocation: true は「Claudeが自分の判断ではこのskillを実行しない」という指定です。このskillは、利用者が /my-first-plugin:hello と打って実行します。Claudeに状況を見て自分から使わせたいskillでは、この行を消します。
この1行は、作った後の「Claudeが自分から使ってくれない」という症状の原因にもなります。後の切り分けの節で扱います。
作ったpluginはどう検証し、どう読み込むか
1. validateで構造を検証する
起動する前に、manifestとskillのfrontmatterの構造検証を行います。
claude plugin validate ./my-first-plugin成功すると、検証したmanifestのパスと ✔ Validation passed が表示されます。失敗すると ✘ Validation failed が出て、その上の各行に直すべき項目が示されます。警告も失敗として扱いたい場合は --strict を付けます。
2. –plugin-dirで読み込んで呼び出す
検証が通ったら、pluginを読み込んでClaude Codeを起動します。
claude --plugin-dir ./my-first-plugin起動後、skillを呼び出します。
/my-first-plugin:hello公式の期待結果は「Claudeが挨拶を返す」です。
--plugin-dir で読み込んだpluginは、そのセッションの間だけ有効で、設定ファイルには何も書き込まれません。セッション中にファイルを編集したら /reload-plugins で反映します。--plugin-dir は繰り返し指定でき、複数のpluginや .zip にまとめたpluginも同時に読み込めます。
毎回フラグを付けたくないとき
毎セッション自動で読み込ませたい場合は claude plugin init を使います。
claude plugin init my-toolこのコマンドは ~/.claude/skills/my-tool/ に .claude-plugin/plugin.json とルートの SKILL.md を作ります。~/.claude/skills/ 配下で .claude-plugin/plugin.json を持つフォルダは、フラグもインストールもなしで毎セッション読み込まれます。
呼び名には注意が要ります。ルートの SKILL.md は個人skillとしても扱われるため /my-tool で呼び、skills/ 配下に足したskillは /my-tool:example のように接頭辞付きになります。--with skills を付けると、skills/ 配下のskillも最初から作られます。読み込みを止めるには、claude plugin disable my-tool@skills-dir を実行するか、ディレクトリを消します。ディレクトリを消すとそのpluginのファイルもなくなるので、残したい場合は disable を使います。
リポジトリの全員に読み込ませたい場合は、<project>/.claude/skills/<name>/ に .claude-plugin/plugin.json を含む同じ構成を自分で作ります。
読み込めない・skillが出ないときは何を確認するか
公式は、変更が反映されないときに次の4つを順番に確認するよう案内しています。どこで止まったかが分かるので、上から1つずつ進めます。
| 順 | どこで | 何をする | 分かること |
|---|---|---|---|
| 1 | シェル | claude plugin validate <path> |
manifestと全skillのfrontmatterの検査。成功時は終了コード0 |
| 2 | セッション内 | /reload-plugins の後、/plugin名:skill名 を打つ |
編集が反映され、skillが読み込まれたか。Reloaded: 行に件数が出る |
| 3 | セッション内 | /plugin を開く |
Installedタブで見つかったコンポーネント、Errorsタブで読込失敗の理由 |
| 4 | シェル | claude plugin list |
読込状態（Status: ✔ loaded か読込エラー）。開発中のpluginは plugin list の前に --plugin-dir とパスを付ける |
validateのエラー文と直し方
claude plugin validate が失敗すると Found N errors と Validation failed が出て、終了コード1で終わります。代表的なメッセージを、公式のトラブルシューティングから抜き出しました。
| メッセージ | 原因 | 直し方 |
|---|---|---|
File not found: <path> |
指定したパスにmanifestがない、またはパスが存在しない | .claude-plugin/ を含むpluginのルートを指定し直す |
Invalid JSON syntax: <parse error> |
manifestか hooks/hooks.json がJSONとして不正 |
JSONの記法を直す |
YAML frontmatter failed to parse: <error> |
skillなどのfrontmatterが壊れている | --- で囲んだfrontmatterを修正する |
No frontmatter block found（警告） |
skillなどのfrontmatterが無い。警告なので、--strict を付けたときだけ検証が止まる |
--- で囲んだfrontmatterを追加する |
Plugin name "<name>" is reserved: ... |
name が予約名に当たる |
用途を表す名前に変える |
直すたびにコマンドを再実行し、エラーがなくなるまで繰り返します。kebab-caseでない name や、version・description・author の欠落は、エラーではなく Validation passed with warnings として報告されます。
症状別の原因
| 症状 | 原因 | 直し方 |
|---|---|---|
| pluginは読み込まれるがskillが出ない | skills/ が .claude-plugin/ の中にある、またはmanifestの skills が SKILL.md ファイルを指している |
skills/ をpluginのルートへ移し、skills にはSKILL.mdを含むディレクトリを指定して /reload-plugins |
| エラーなしで何も読み込まれない | --plugin-dir にマーケットプレイスのルートを渡している |
pluginのルート（.claude-plugin/plugin.json と skills/ などを含むフォルダ）を指定する |
Errorsタブに <component> path not found: <path> |
manifest内のパスが存在しない場所を指している | パスを直すかディレクトリを作り、/reload-plugins |
/ で打てば動くが、Claudeが自分から使わない |
disable-model-invocation: true が残っている、descriptionが頼み方と合っていない、skillが多くdescriptionが切り詰められている |
自分から使わせたいならその行を消し、descriptionを見直す |
manifestにパスを書く場合は、pluginのルートからの相対パスで ./ から始めます。
最後の症状に関わる点として、公式は「エラーなく読み込めても、意図どおりにClaudeの挙動を変えられるとは限らない」としています。pluginあり・なしで同じテストを走らせて差を採点する claude plugin eval があり、詳細はTest plugins with evalsにあります。Claude Code本体のエラー表示に困っている場合はエラー対処の記事の方が近い内容です。
既存の.claude/の設定をpluginにするには
すでにプロジェクトの .claude/ にskillやagent、hookがある場合は、書き直さずにpluginへ移せます。.claude/ があるプロジェクトのルートで作業します。
my-plugin/.claude-plugin/plugin.jsonを作る（上の手順と同じ）- 持っているディレクトリだけをpluginのルートへコピーする
cp -r .claude/skills my-plugin/agents や commands も同じ形でコピーします。
- hookは、
.claude/settings.jsonか.claude/settings.local.jsonにあるhooksオブジェクトをmy-plugin/hooks/hooks.jsonにコピーする。形式は同じです claude --plugin-dir ./my-pluginで読み込み、新しい名前で確認する。/deployだったskillは/my-plugin:deployになります
注意点は、元のファイルが残っている間の挙動です。skillとagentは接頭辞が付くので両方が並んで動きますが、hookには接頭辞がないため、settingsと hooks/hooks.json の両方にあるhookはイベントのたびに2回走ります。元ファイルを消すと、.claude/ に置いていたskill・agentとsettingsの hooks は元の場所から失われます。消す前に、ls -a my-plugin でコピーした各ディレクトリが .claude-plugin の隣にあることと、--plugin-dir で読み込んだpluginが動くことを確かめます。確かめたら、.claude/ の元ファイルとsettingsの hooks を消します。
作ったpluginを他の人に渡すには
作ったpluginは、そのままでは自分のマシンにしかありません。公式が挙げる渡し方は3つです。
- ディレクトリか
.zipを直接渡す（公開作業は不要） - 自分のマーケットプレイスに載せ、チームに名前でインストールしてもらう
- Anthropicのディレクトリに申請する
手順は公式のPublish and distribute a pluginにまとまっています。配る前に知っておきたい点として、有効になったpluginは使わないセッションでも、Claudeが自分で呼べるskillの名前と説明を毎ターンのコンテキストに載せます。
本記事のコマンドとメッセージは、2026年10月19日に公式ドキュメント（plugin制作・トラブルシューティング・manifestリファレンス・概要）と照合した記述です。版によって項目やメッセージが変わることがあるため、食い違う場合は公式の記述を優先してください。