Claude Code pluginの作り方｜最小構成のskillを作ってローカルで動かすまで

Claude Code pluginの最小構成

最小のpluginは、1つのフォルダにmanifest（plugin.json）とskill 1つを置いた構成です。manifestはpluginの名前などを書く設定ファイル、skillはClaude Codeに特定の作業手順を覚えさせる指示書のことです。

この記事で作るのは、その最小構成だけです。用意するものは、Claude Codeを起動できるPCと空の作業フォルダのみ。公開用の登録や外部サービスとの接続は要りません。pluginを選ぶ際の安全性判断はplugins-guide、skill単体の運用はskills-guideが扱っています。

pluginまわりの仕様は更新されやすい分野です。コマンド名、画面表示、manifestの項目、配置ルールは版によって変わりうるため、作業前に公式のplugin制作資料で現行の記述を確認してください。食い違うときは公式の記述が基準になります。この記事は、その資料にある最小構成をもとに整理しました。

pluginが束ねるもの

pluginは、skill、hooks、MCPサーバー設定などを1つにまとめて持ち運ぶための単位です。今回使うのはこのうちskillだけです。

今回作る完成形

完成時のディレクトリは次の形です。skills/ は .claude-plugin/ の中ではなく、pluginフォルダ直下に置きます。

my-first-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── memo-organizer/
        └── SKILL.md

plugin.jsonの最低限の記述

最小のmanifestは、name を軸にした短いJSONです。

最小のplugin.json

.claude-plugin/plugin.json に、次のダミー値で書きます。

{
  "name": "my-first-plugin",
  "description": "メモを整理する練習用の最小plugin"
}

description は任意の説明文です。version などの追加項目は、最小構成の確認には不要なので省きました。

nameが呼出しの接頭辞になる仕組み

skillは、pluginの名前を頭につけた /プラグイン名:スキル名 の形で呼び出します。複数のpluginに同じ名前のskillがあっても衝突しないよう、pluginの名前で区別する仕組みです。今回は name が my-first-plugin、skillのフォルダ名が memo-organizer なので、呼出しは /my-first-plugin:memo-organizer になります。

最初のskillの作り方

最初のskillは、外部サービスを使わず、文章を渡すと文章が返るだけのものにします。出力を目で見て判断できるため、動作の確認が簡単です。

題材：メモを3見出しに整えるskill

箇条書きのメモを渡すと、「決定事項」「未決事項」「次の行動」の3見出しに並べ直すskillを作ります。会議メモや作業ログなど、自分の業務の題材に差し替えやすい形です。

SKILL.mdの最小構成

skills/memo-organizer/SKILL.md に、次の内容を書きます。先頭の --- で囲んだ部分がfrontmatter（skillの名前や説明を書く欄）です。

---
name: memo-organizer
description: 箇条書きのメモを、決定事項・未決事項・次の行動の3見出しに整理する
---

渡されたメモを読み、次の3見出しに分けて書き直してください。

## 決定事項
## 未決事項
## 次の行動

メモにない内容は補わず、分類できない項目は「未決事項」に入れてください。

指示は短く具体的に書くのがこつです。

作ったpluginをローカルで読み込む手順

ローカルで試すには、--plugin-dir にpluginのフォルダを指定してClaude Codeを起動します。読み込まれるのはそのセッションの間だけなので、マーケットプレイスへの登録は要りません。

読込の手順

pluginフォルダの1つ上の階層で、次のように起動します。

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

セッション中のファイル編集は、/reload-plugins で反映します。Claude Code自体の起動方法に迷う場合は、起動手順の記事が参考になります。

指定先の注意

指定するのは、.claude-plugin/ を含むpluginフォルダそのものです。1つ上や1つ下のフォルダを指すと、読み込まれない原因になります。

動いたかどうかの判断基準

構造、読込、呼出しの3段階を、上から順に確認します。段階を分けておくと、止まったときに原因の範囲を絞れます。

3段階の合格基準表

段階	見るもの	合格の状態
1 構造	`claude plugin validate`	検証で問題が報告されない
2 読込	`claude --plugin-dir ./my-first-plugin plugin list`、またはそのpluginを読み込んだセッション内の `/plugin` 画面	pluginが一覧に出る。読込エラーの表示がない
3 呼出し	`/my-first-plugin:memo-organizer` に箇条書きメモを渡す	メモが3見出しに整って返る

表の使い方

通らない段階が見つかったら、そこで止めて次の節の逆引き表に進みます。

動かないときの逆引き

症状ごとに、最初に確認する段階と項目を整理します。

症状別の逆引き表

症状	止まっている段階	原因の候補	直し方
skillが出てこない	読込	`skills/` を `.claude-plugin/` の中に置いた	`skills/` をpluginフォルダ直下へ移す
pluginが読み込まれない	読込	`--plugin-dir` に親フォルダなど、別の階層を指定した	pluginフォルダそのものを指定し直す
validateでエラーが出る	構造	`plugin.json` のJSON記法の誤り	エラー文の指す箇所を修正する
編集が反映されない	読込	再読込していない	`/reload-plugins` を実行するか、起動し直す
呼べたが出力が想定と違う	呼出し	SKILL.mdの指示が曖昧	指示を具体的に書き直す

表は構成から考えられる切り分けの仮説で、各症状や原因を実機で確認した記録ではありません。症状が当てはまっても原因を確定せず、検証用フォルダで1項目ずつ確認してください。Claude Code本体のエラーメッセージが出る場合は、エラー対処の記事のほうが近い内容です。

まとめ：自分の業務のskillを育てる

次のチェックリストがすべて埋まれば、この記事の目的は達成です。

完了チェックリスト

manifestとskill 1つを入れたフォルダを作った
構造の確認（validate）が通った
読込の確認が通った
skillを呼び出して、想定どおりの出力を得た
止まったとき、構造・読込・呼出しのどの段階かを言える

この先の入口

他の人へ共有・公開したくなったら、選び方と安全性の見方をplugins-guideで確認しておくと安心です。hookを足したいときはhooks-guideから入れます。.claude/ 配下の既存設定をpluginに変換する方法は、公式資料の該当箇所にあります。

学び続ける場

自分の業務に合わせてskillを育てる段階では、生成AIを自分の手で使いこなすために学べる、月額1,980円からの学習コミュニティ「AI駆動ラボ」があります。