Agent Skill Loader

Agent Skill Loader 🧠

Agent Skill Loader 是一个 Model Context Protocol（MCP）服务，充当静态 Claude Code 技能库与动态 AI Agent（如 Claude Desktop、Cursor 或任何 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 等），技能会自动显示为斜杠命令。从斜杠命令菜单中选择技能，即可直接注入其内容——无需调用工具。

工具

Agent 可使用五种工具：

• 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()：返回诊断信息（路径、状态、警告）。

示例 Agent 提示词

“我需要编写一个 DAX 度量值，但不确定最佳实践是什么。”

Agent 会自动调用 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 通知——无需重启。