Agent Skill Loader 🧠

Agent Skill Loader 是一个模型上下文协议 (MCP) 服务器，它充当您的静态 Claude Code 技能库与动态 AI 代理（如 Claude Desktop、Cursor 或任何 MCP 客户端）之间的桥梁。

它将技能同时公开为 MCP Prompts（斜杠命令，无需工具调用）和 MCP Tools（用于程序化使用）。技能会从配置的目录中自动发现并保持实时更新 — 添加一个新的 SKILL.md，客户端会自动收到通知。

🚀 功能

MCP Prompts：技能在客户端中显示为斜杠命令。无需工具调用即可注入它们。
实时更新：当通过文件监视器添加或删除技能时，会触发 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"]
}

📂 配置

服务器会自动检测其工作区并从以下位置聚合技能路径：

默认：%USERPROFILE%\.claude\plugins\cache（标准位置）
动态配置：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 Prompts（斜杠命令）

如果您的客户端支持 MCP Prompts（Claude Desktop、Cursor 等），技能会自动显示为斜杠命令。从斜杠命令菜单中选择一个技能即可直接注入其内容 — 无需工具调用。

工具

代理可以访问五个工具：

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 通知 — 无需重启。

agent-skill-loader