Agent Skill Loader

Agent Skill Loader 🧠

Agent Skill Loader は、静的な Claude Code Skills ライブラリと動的な AI エージェント（Claude Desktop、Cursor、その他の MCP クライアントなど）をつなぐブリッジとして機能する、Model Context Protocol（MCP）サーバーです。

スキルは MCP プロンプト（スラッシュコマンド。ツール呼び出し不要）と MCP ツール（プログラムからの利用）の両方として公開されます。スキルは設定されたディレクトリから自動的に検出され、常に最新の状態に保たれます。新しい SKILL.md を追加すると、クライアントに自動で通知されます。

🚀 特長

• MCP プロンプト：スキルがクライアント内でスラッシュコマンドとして表示されます。スキルを挿入するためのツール呼び出しは不要です。
• ライブ更新：スキルが追加または削除されると（ファイルウォッチャー経由で）、listChanged 通知が送信されます。
• 検出：list_skills — 設定済みのスキルディレクトリをスキャンします。任意で検索フィルターを指定できます。
• 動的な読み込み：read_skill — SKILL.md の内容を取得します。
• 永続化：install_skill — スキルをプロジェクトに永続的にコピーします。
• 設定：manage_search_paths — 実行時にスキルディレクトリを追加または削除します。
• トラブルシューティング：debug_info — 設定やパスの問題を診断します。

🛠️ セットアップ

前提条件

• Node.js >= 18

オプション A：npm からインストール（推奨）

npm install -g agent-skill-loader

次に、.mcp.json に登録します：

"agent-skill-loader": {
  "command": "agent-skill-loader"
}

オプション B：ソースからビルド

git clone https://github.com/back1ply/agent-skill-loader.git
cd agent-skill-loader
npm install
npm run build

次に、.mcp.json に登録します：

"agent-skill-loader": {
  "command": "node",
  "args": ["<path-to-repo>/build/index.js"]
}

📂 設定

サーバーはワークスペースを自動的に検出し、次の場所からスキルパスを集約します：

1. デフォルト：%USERPROFILE%\.claude\plugins\cache（標準の場所）
2. 動的設定：skill-paths.json（プロジェクトのルートに配置）

環境変数

変数	説明
MCP_SKILL_PATHS	JSON 配列、または追加のスキルパスをセミコロン／カンマで区切ったリスト
MCP_WORKSPACE_ROOT	自動検出されたワークスペースのルートを上書きします
MCP_NO_WATCH	1 に設定するとファイルウォッチャーを無効にします（CI での利用に便利です）

動的なパス管理

設定ファイルを手動で編集する必要はありません。次のツールを使って、実行時にパスを管理できます：

• 追加：manage_search_paths(operation="add", path="F:\\My\\Deep\\Skills")
• 削除：manage_search_paths(operation="remove", path="...")
• 一覧表示：manage_search_paths(operation="list") は skill-paths.json を作成／更新します。

🤖 使い方

MCP プロンプト（スラッシュコマンド）

クライアントが MCP プロンプト（Claude Desktop、Cursor など）に対応している場合、スキルは自動的にスラッシュコマンドとして表示されます。スラッシュコマンドのメニューからスキルを選択すると、その内容が直接挿入されます。ツール呼び出しは不要です。

ツール

エージェントは次の 5 つのツールを利用できます：

• list_skills(query?)：利用可能なスキルの JSON リストを返します。任意の query を指定すると、名前または説明の部分文字列で絞り込みます（大文字と小文字は区別されません）。
• read_skill(skill_name)：スキルの Markdown 形式の手順を返します。
• install_skill(skill_name, target_path?)：スキルのフォルダーを .agent/skills/<name> にコピーします。セキュリティ上、target_path は現在のワークスペース内である必要があります。
• manage_search_paths(operation, path?)：スキル検索パスを追加、削除、または一覧表示します。
• debug_info()：診断情報（パス、状態、警告）を返します。

エージェントのプロンプト例

「DAX メジャーを書きたいのですが、ベストプラクティスがよく分かりません。」

エージェントは自動的に list_skills を呼び出し、writing-dax-measures を見つけて read_skill を呼び出し、専門知識をもとに回答します。または、ユーザーがスラッシュコマンドでスキルを直接呼び出すこともできます。

🔧 トラブルシューティング

スキルが見つからない場合は、debug_info() を使って次の情報を確認してください。

• search_paths：スキャン対象のディレクトリ
• path_status：各パスが存在し、読み取り可能かどうか
• warnings：スキャン中に発生したエラー（アクセス拒否、空のファイルなど）

出力例：

{
  "workspace_root": "C:/projects/agent-skill-loader",
  "search_paths": {
    "base": ["C:/Users/pc/.claude/plugins/cache"],
    "dynamic": ["F:/My/Skills"],
    "effective": ["C:/Users/pc/.claude/plugins/cache", "F:/My/Skills"]
  },
  "path_status": [
    { "path": "C:/Users/pc/.claude/plugins/cache", "exists": true, "readable": true },
    { "path": "F:/My/Skills", "exists": false, "readable": false }
  ],
  "skills_found": 12,
  "warnings": [
    { "path": "F:/My/Skills", "reason": "Directory does not exist" }
  ]
}

📦 プロジェクト構成

• src/index.ts：メインサーバーのロジック（ツール＋プロンプト＋ウォッチャー）。
• src/utils.ts：スキルのスキャン、説明の抽出、プロンプト用ヘルパー、デバウンス。
• build/：コンパイル済み JavaScript の出力先。
• package.json：依存関係（@modelcontextprotocol/sdk、chokidar、zod）。

🤝 貢献

新しいスキルを追加するには、監視対象のディレクトリのいずれかに SKILL.md ファイルを含むフォルダーを追加してください。サーバーが自動的に検出し、listChanged 通知を送信するため、再起動は不要です。