Claude Code skills-directoryでプラグインをそのまま動かす手順
スキルディレクトリに置くだけでプラグインとして自動読み込みされる仕組みと、personal/project scopeの違い、配布に切り替えるタイミングをまとめます。
skills-directoryプラグインとは何か
Claude Codeのプラグインは通常、マーケットプレイス経由でインストールします。ですが ~/.claude/skills/ や <プロジェクト>/.claude/skills/ の中に .claude-plugin/plugin.json を含むフォルダを置くだけでも、次のセッションから自動的にプラグインとして読み込まれます。これがskills-directoryプラグインです。
判定はマニフェストの有無だけで決まります。SKILL.md だけのフォルダは名前空間なしの素のスキルとして動きますが、同じ場所に plugin.json を追加した瞬間、そのフォルダは <name>@skills-dir という独立したプラグインになります。マーケットプレイスへの登録もインストール操作も不要です。
通常のマーケットプレイスインストールはプラグインキャッシュへファイルをコピーしますが、skills-directoryプラグインはコピーされずその場で読み込まれます。ファイルを直接編集すれば、次のリロードでそのまま反映される仕組みです。
通常のskillsとプラグインでは何が変わるか
スキルディレクトリの中身は次の3パターンのいずれかになります。混同すると「スキルが動かない」の原因調査で迷います。
| 配置 | 実体 |
|---|---|
<skills-dir>/foo/SKILL.md(マニフェストなし) | 実体名前空間なしのプレーンなスキルfoo |
<skills-dir>/foo/.claude-plugin/plugin.json | 実体プラグインfoo@skills-dir。自身のスキル・エージェント・hooksを束ねられる |
<plugin>/skills/bar/SKILL.md | 実体プラグインに同梱されたスキルbar |
プラグインになると、スキルは /plugin-name:skill-name の形に名前空間化されます。単体のスキルだった頃の /skill-name という呼び出し方は失われるため、既存のワークフローや他のスキルからの参照がある場合は呼び出し名の変更を先に洗い出しておきます。SKILL.md自体の書き方はClaude Code Skills完全ガイドにまとめています。
SKILL.mdが1つだけならskills/は省略できる
配布する機能がスキル1つだけのプラグインでは、skills/my-skill/SKILL.mdという2階層を作らず、SKILL.mdをプラグインルートに直接置けます。この場合、呼び出し名はfrontmatterのnameフィールドから取られ、skillsマニフェストフィールドに"./"を明示する必要もありません。将来スキルを2つ以上に増やす見込みがあるなら、最初からskills/ディレクトリの形にしておいたほうが、あとからの構造変更を避けられます。
claude plugin initでプラグインを作る
雛形は1コマンドで生成できます。
claude plugin init my-toolこれで ~/.claude/skills/my-tool/ に .claude-plugin/plugin.json と最小限の SKILL.md が作られます。次回セッションから my-tool@skills-dir として自動的に読み込まれ、/plugin のUIや claude plugin list にも表示されます。
manifestの name はディレクトリ名としても使われるため、スペースやパス区切り文字は使えません。スキル以外のコンポーネントも同時に足場だけ用意したいときは --with オプションを使います。
claude plugin init my-tool --with skills hooks--with に渡せるのは skills agents hooks mcp lsp output-style channel の7種類で、それぞれ編集可能なサンプルファイルが1つ追加されます。組織のmanaged settingsで strictKnownMarketplaces を有効にしているか、blockedMarketplaces に {"source": "skills-dir"} を追加している環境では、claude plugin init はファイルを書き込む前に失敗します。
skills以外のコンポーネントを足す
skills-directoryプラグインはスキル専用の仕組みではありません。プラグインルート(.claude-plugin/ の1つ上の階層)に agents/、hooks/hooks.json、.mcp.json、.lsp.json、monitors/monitors.json を置けば、通常のプラグインと同じ規約でそのまま読み込まれます。
ここでよくある事故は、これらのディレクトリを .claude-plugin/ の中に入れてしまうことです。.claude-plugin/ の中に入るのは plugin.json だけで、それ以外のコンポーネントは必ずプラグインルート直下に置きます。
project scopeで使うときの信頼ゲート
~/.claude/skills/ に置くpersonal scopeは、どのプロジェクトからでも自分専用の環境として読み込まれ、追加の制限はありません。一方で <プロジェクト>/.claude/skills/ に置くproject scopeは、リポジトリをcloneした全員に届く代わりに、.claude/settings.json のプロジェクト許可ルールと同じ信頼ゲートを通ります。フォルダを信頼していなければ読み込まれず、実行を伴うコンポーネントにはさらに個別の制限がかかります。
- MCPサーバーは、プロジェクトの
.mcp.jsonと同じサーバー単位の承認を経由する - LSPサーバーは、ワークスペースを信頼した後にだけ起動する
- バックグラウンドモニターは、project scopeでは一切読み込まれない
親フォルダをすでに信頼していても、-p フラグでの起動だけでは足りません。project scopeのskills-directoryプラグインは、セッションの主作業ディレクトリの .claude/skills/ からしか読み込まれず、通常のスキルやコマンドのようにリポジトリルートまで遡って探索することはありません。サブディレクトリでセッションを起動するとプラグインが見つからないという事故につながるので、リポジトリルートから起動するか、v2.1.246以降なら /cd でセッションを移動します。
変更の反映と無効化
SKILL.md の変更は、現在のセッションに即座に反映されます。一方で hooks/、.mcp.json、agents/、output-styles/ といったその他のコンポーネントの変更は、/reload-plugins を実行するかClaude Codeを再起動するまで反映されません。仕組みの詳細は/reload-pluginsで再起動なしにプラグインを反映するで扱っています。
マーケットプレイスインストールと違い、skills-directoryプラグインにuninstallという概念はありません。使うのをやめるときは、フォルダそのものを削除するか、名前を指定して無効化するだけです。
claude plugin disable my-tool@skills-dirskills-directoryとマーケットプレイス配布の使い分け
skills-directoryプラグインは、個人の自動化やチーム内の実験には向いていますが、配布を前提にした設計ではありません。バージョン管理やインストール記録、plugin.json のバージョンフィールドによる更新通知は、マーケットプレイス経由のインストールが前提になっている仕組みです。同じプラグインを複数人が手元で個別に育て始めると、設定のずれにあとから気づけなくなります。チームへの正式配布を考え始めた時点で、Claude Codeプラグイン(Plugins)完全ガイドのマーケットプレイス化の手順に移るのが実務的な線引きです。すでに.claude/配下に資産があるなら、そちらを直接プラグイン化する移行手順を先に済ませておく方法もあります。
claude.aiから同期されるプラグインとの違い
マーケットプレイスを介さずに読み込まれるプラグインには、skills-directoryプラグイン以外にもう1種類あります。Coworkやクラウドセッションでは、claude.aiアカウントで有効にしているプラグインが~/.claude/plugins/synced/へダウンロードされ、<name>@syncedとして読み込まれます。ただしこの同期は、自分のターミナルで直接始めたセッションには反映されません。同じ名前のプラグインがskills-directoryプラグインや--plugin-dirプラグインとしても存在する場合は、そちら側が優先され、同期版は「読み込まれていない」扱いになります。両者は見た目の挙動が似ているぶん、claude plugin listで表示元の接尾辞(@skills-dirか@syncedか)を確認しておくと混同を避けられます。
よくあるつまずき
- スキルが出てこない:
commands/やskills/を.claude-plugin/の中に置いてしまっている。claude --debugでロードされたディレクトリを確認する - hooksが発火しない: スクリプトに実行権限がない。
chmod +xで付与する - MCPサーバーが起動しない: パスに
${CLAUDE_PLUGIN_ROOT}を使わず、絶対パスや相対パスを直書きしている - サブディレクトリから起動したらproject scopeのプラグインが読み込まれない: 通常のスキルと違い親ディレクトリを遡らない仕様のため。リポジトリルートから起動し直す
manifestの検証にはclaude plugin validateが使えます。JSON構文エラーや必須フィールドの欠落はここで実行前に潰しておくと、--debugでのあとの原因調査が要らなくなります。
管理者がstrictKnownMarketplacesやblockedMarketplacesでこの経路を塞ぐのは、ローカルに置くだけでコードが実行されるプラグインを、供給元の分からないまま組織内に広げないための対策です。個人利用では意識しない設定ですが、企業のワークスペースでskills-directoryプラグインが急に読み込まれなくなったときは、まずこのポリシーの有無を確認します。
よくある質問
skills-directoryプラグインはチーム全員に共有できますか
~/.claude/skills/のpersonal scopeは自分だけの環境なので共有されません。<プロジェクト>/.claude/skills/のproject scopeならリポジトリ経由でチームに届きますが、各メンバーがフォルダを信頼するまで読み込まれない点は変わりません。
名前空間のmy-tool:部分は変更できますか
できます。plugin.jsonのnameフィールドを変えると、スキルの呼び出し名がその名前で再構成されます。
/plugin listに出てこないのですが
インタラクティブな/plugin listはマーケットプレイスインストール分のみを表示します。skills-directoryプラグインは/pluginのUIとclaude plugin list(CLIコマンド)には表示されるので、確認はそちらで行います。
管理者がskills-directoryプラグインを禁止できますか
できます。組織のmanaged settingsでstrictKnownMarketplacesを有効にするか、blockedMarketplacesに{"source": "skills-dir"}を追加すると、claude plugin initはファイルを書き込む前に失敗します。
削除するときアンインストール操作は必要ですか
不要です。マーケットプレイスから何かをインストールしたわけではないので、フォルダを削除するか名前を指定して無効化するだけで完了します。
まとめ
skills-directoryプラグインは、.claude-plugin/plugin.jsonをスキルディレクトリに置くだけでマーケットプレイスなしにプラグイン化できる仕組みです。個人の自動化ならpersonal scope、チーム内の実験ならproject scopeを選び、project scopeは信頼ゲートとMCP/LSP/モニターの制限を伴うことを踏まえて設計します。配布を前提にした瞬間にマーケットプレイス化を検討するのが、実務上の切り替えラインです。