Claude Code skills-directoryでプラグインをそのまま動かす手順

skills-directoryプラグインとは何か

Claude Codeのプラグインは通常、マーケットプレイス経由でインストールします。ですが ~/.claude/skills/ や <プロジェクト>/.claude/skills/ の中に .claude-plugin/plugin.json を含むフォルダを置くだけでも、次のセッションから自動的にプラグインとして読み込まれます。これがskills-directoryプラグインです。

判定はマニフェストの有無だけで決まります。SKILL.md だけのフォルダは単体のスキルとして動き、同じ場所に plugin.json を足すと、そのフォルダは <name>@skills-dir という独立したプラグインになります。@ の後ろの skills-dir は、マーケットプレイス名の代わりに入る出自の名前です。登録もインストール操作も要りません。

マーケットプレイスからのインストールはプラグインキャッシュへファイルをコピーしますが、skills-directoryプラグインはコピーされず、置いた場所でそのまま読み込まれます。ファイルを直接編集すれば、次のリロードで反映されます。

claude plugin initで作って動かす

雛形は1コマンドで作れます。claude plugin init はv2.1.157以降で使えます。

次の出力はv2.1.287で、新規のホームに対して --with skills hooks を付けて実行したものです。

claude plugin init my-tool --with skills hooks

✔ Created plugin "my-tool" at ~/.claude/skills/my-tool
  It will auto-load next session as my-tool@skills-dir. Run /reload-plugins to load it now.
  Disable: claude plugin disable my-tool@skills-dir. Remove: delete the directory.

作られたファイルは5つです。

~/.claude/skills/my-tool/
├── .claude-plugin/plugin.json
├── SKILL.md
├── skills/example/SKILL.md
├── hooks/hooks.json
└── hooks-handlers/on-session-start.ts

plugin.json の中身は、name と version(0.1.0)、TODOの入った description、そして "skills": ["./"] です。作者は --author で渡せます。省略するとgitの user.name が使われ、gitの設定が無い環境では作者の欠落が警告として1件出ます。

claude plugin list は、skills-directoryプラグインを専用の見出しの下に出します。

Skills-directory plugins (.claude/skills/*):
 
  ❯ my-tool@skills-dir
    Version: 0.1.0
    Scope: user
    Path: ~/.claude/skills/my-tool
    Status: ✔ loaded

無効にすると Status が ✘ disabled に変わります。~/.claude/settings.json には "enabledPlugins": {"my-tool@skills-dir": false} が書かれ、フォルダは残ります。<name>@skills-dir の既定の有効状態はマニフェストの defaultEnabled で決まり、settingsに "<name>@skills-dir" を true か false で書くとそちらが優先されます。完全に消したいときはフォルダを削除します。マーケットプレイス用の uninstall は、この経路では使いません。

--with に渡せるのは skills agents hooks mcp lsp output-style channel の7種類で、種類ごとに編集可能なサンプルが1つ入ります。manifestの name はディレクトリ名にもなるため、スペースやパス区切り文字は使えません。

呼び出し名はどうなるか

既存のワークフローが参照している名前に影響が出るのは、スキルを skills/ の下へ移動させたときです。SKILL.md自体の書き方はClaude Code Skills完全ガイドにまとめています。

SKILL.mdが1つだけならskills/は省略できる

配布する機能がスキル1つだけなら、skills/my-skill/SKILL.md という2階層を作らず、SKILL.md をプラグインルートに直接置けます。skills/ ディレクトリも skills マニフェストキーも無いプラグインは、ルートの SKILL.md を1つのスキルとして読み込みます。

frontmatterの name は必ず書きます。マーケットプレイス経由で入れたときは、name が無いとキャッシュのディレクトリ名がスキル名になるためです。claude plugin init が plugin.json に "skills": ["./"] を書くのは、この形をマニフェスト側でも明示するためです。将来スキルを2つ以上に増やす見込みがあるなら、最初から skills/ の形にしておくと、構造の変更を避けられます。

skills以外のコンポーネントを足す

skills-directoryプラグインはスキル専用の仕組みではありません。プラグインルート(.claude-plugin/ の1つ上の階層)に agents/、hooks/hooks.json、.mcp.json、.lsp.json、monitors/monitors.json を置けば、通常のプラグインと同じ規約で読み込まれます。

よくある事故は、これらを .claude-plugin/ の中に入れてしまうことです。.claude-plugin/ に入るのは plugin.json だけです。

--with hooks が作るhookの雛形には、注意点が1つあります。hooks.json は bun "${CLAUDE_PLUGIN_ROOT}/hooks-handlers/on-session-start.ts" を呼び、ハンドラの1行目は #!/usr/bin/env bun です。bunが入っていない環境では、雛形のままでは動きません。ハンドラ内のコメントは、hooks/hooks.json の bun を node や python3 に差し替えるよう案内しています。

project scopeで使うときの信頼ゲート

~/.claude/skills/ に置くpersonal scopeは、どのプロジェクトからでも自分専用の環境として読み込まれ、project scopeのような信頼ゲートの条件は付きません。<プロジェクト>/.claude/skills/ に置くproject scopeは、cloneした全員に届く代わりに、.claude/settings.json のプロジェクト許可ルールと同じ信頼ゲートを通ります。フォルダを信頼していなければ読み込まれません。親フォルダを信頼していても、-p で起動しても足りません。

project scopeのプラグインは、セッションの主作業ディレクトリの .claude/skills/ からしか読み込まれません。通常のスキルやコマンドと違い、リポジトリルートまで親ディレクトリをさかのぼって探すことはありません。サブディレクトリでセッションを始めると、ルートに置いたプラグインが見つからないのはこのためです。リポジトリルートから起動するか、v2.1.246以降なら /cd でセッションを移動します。

変更はいつ反映されるか

SKILL.md の本文の変更は、現在のセッションにそのまま反映されます。hooks/、.mcp.json、agents/、output-styles/ の変更は、/reload-plugins を実行するかClaude Codeを再起動するまで反映されません。仕組みの詳細は/reload-pluginsで再起動なしにプラグインを反映するで扱っています。

同じ名前のプラグインがあるとどれが読み込まれるか

マニフェストの name が同じプラグインが複数の出自から有効になっていると、次の順で1つだけが読み込まれます。

1. 管理設定の enabledPlugins に載っているプラグイン
2. --plugin-dir や --plugin-url で渡した、そのセッション限りのプラグイン
3. マーケットプレイスからインストールしたプラグイン
4. skills-directoryプラグイン。~/.claude/skills/ の分が読み込まれ、プロジェクトの .claude/skills/ の分は外れる
5. claude.aiから同期されたプラグイン

負けた側は /plugin のErrorsタブに Not loaded の行として出ます。たとえば --plugin-dir で同名のプラグインを渡すと、skills-directory側が Not loaded になります。開発中のコピーを --plugin-dir で試すと、普段使いのskills-directoryプラグインが静かに外れるのは、この順序のためです。

claude.aiから同期されるプラグインとの違い

マーケットプレイスを介さずに読み込まれるプラグインには、skills-directoryプラグインのほかに <name>@synced があります。claude.aiアカウントで有効にしたプラグイン、または組織が有効にしたプラグインが、Coworkと、claude.aiでサインインしたターミナルのセッションに読み込まれます。

ターミナルでの同期はv2.1.273以降が対象です。起動のたびにバックグラウンドで1回走るので、セッションの開始後に終わることがあります。そのときは Plugins changed. Run /reload-plugins to activate. と表示されます。ANTHROPIC_AUTH_TOKEN、CLAUDE_CODE_OAUTH_TOKEN、apiKeyHelper で認証しているセッションでは、/login をしても同期されません。

claude plugin list の出力では、@skills-dir と @synced の接尾辞で区別できます。同名のプラグインが同期版と手元の版の両方にあるときは手元が勝ち、同期版は読み込まれません。claude.ai側のコピーを使いたいときは、手元の版を無効にします。

管理者の設定で読み込まれないとき

ローカルに置くだけでコードが実行されるため、組織の管理設定でこの経路を止められます。止まる条件は2つです。

• strictKnownMarketplaces(許可リスト)を設定していて、{ "source": "skills-dir" } の項目が入っていない
• blockedMarketplaces(拒否リスト)に { "source": "skills-dir" } が入っている

どちらの場合も、skills-directoryプラグインは ~/.claude/skills/ からも .claude/skills/ からも読み込まれません。SKILL.md だけの単体スキルは影響を受けません。claude plugin init と claude plugin enable は、Plugins from ~/.claude/skills/ are blocked by your organization's managed settings という趣旨のメッセージで終了します。メッセージは、許可リストに項目を足すか、拒否リストから外すよう管理者に求めています。

claude plugin validateで検証する

マニフェストの検証は claude plugin validate <path> で行います。v2.1.287での出力は次のとおりです。

claude plugin validate ./my-tool

⚠ Found 1 warning:
 
  ❯ author: No author information provided. Consider adding author details for plugin attribution
 
✔ Validation passed with warnings

JSONの文法を壊したマニフェストでは、✘ Found 1 error: に続けて json: Invalid JSON syntax が出て、終了コードは1になります。警告だけなら終了コードは0です。--strict を付けると警告も失敗として扱われ、✘ Validation failed (--strict treats warnings as errors) で終了コード1になります。CIに載せるなら --strict が向きます。

検証には、見ない部分があります。プラグインのディレクトリを渡したとき、ルートの SKILL.md は検査対象外です。.claude-plugin/ の中に skills/ を置いた誤配置も、plugin.json が正しければ検証は通ります。v2.1.287で出るのは、バージョンと説明の欠落という2件の警告だけです。コンポーネントの置き場所の誤りは、セッション内の /plugin のErrorsタブと、claude plugin list の Status で見つけます。

よくあるつまずき

• スキルが出てこない: commands/ や skills/ を .claude-plugin/ の中に置いている。skills/ をプラグインルートへ移し、/reload-plugins を実行する
• hooksが発火しない: スクリプトに実行権限がない。chmod +x で付与する。雛形のhookがbunを呼ぶ点にも注意する
• MCPサーバーが起動しない: パスに ${CLAUDE_PLUGIN_ROOT} を使わず、絶対パスを直書きしている。プラグインを別の場所へ移すと壊れる
• サブディレクトリから起動したらproject scopeのプラグインが読み込まれない: 通常のスキルと違い親ディレクトリをさかのぼらない仕様のため。リポジトリルートから起動し直す
• 手元の変更が反映されない: --plugin-dir で同名のプラグインを渡していて、skills-directory側が Not loaded になっている。Errorsタブで理由を見る

skills-directoryとマーケットプレイス配布の使い分け

skills-directoryプラグインは、個人の自動化やチーム内の実験には向いていますが、配布を前提にした設計ではありません。skills-directoryプラグインはコピーも更新もされず、置いた場所のまま読み込まれるため、マーケットプレイスのバージョンとキャッシュの仕組みは使われません。同じプラグインを複数人が手元で個別に育て始めると、設定のずれにあとから気づけなくなります。チームへの正式配布を考え始めた時点で、Claude Codeプラグイン(Plugins)完全ガイドのマーケットプレイス化の手順へ移るのが実務的な線引きです。すでに .claude/ 配下に資産があるなら、そちらを直接プラグイン化する移行手順を先に済ませる方法もあります。

まとめ

skills-directoryに置いたままでよいのは、自分かリポジトリのメンバーが同じフォルダを見ている間です。管理設定で Not loaded になる、手元ごとに中身が分かれ始める、といった症状が出たら、マーケットプレイスへ移る合図です。