Agent Skill Loader

🚀 Agent Skill Loader 🧠

Agent Skill Loader 是一个模型上下文协议（MCP）服务器，它在你的静态 Claude 代码技能库和动态 AI 代理（如 Antigravity、Claude Desktop 或 Cursor）之间架起了一座桥梁。它允许代理按需“学习”技能，而无需你手动将文件复制到每个项目中。

🚀 快速开始

前提条件

• 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"]
}

✨ 主要特性

• 发现功能：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"]
}

💻 使用示例

对于代理

代理将看到五个工具：

• list_skills()：返回可用技能的 JSON 列表。
• 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，然后用专业知识回答你。

🔧 技术细节

配置

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

1. 默认位置：%USERPROFILE%\.claude\plugins\cache（标准位置）
2. 动态配置：skill-paths.json（位于项目根目录）

动态路径管理

你无需手动编辑配置文件。使用工具在运行时管理路径：

• 添加：manage_search_paths(operation="add", path="F:\\My\\Deep\\Skills")
• 删除：manage_search_paths(operation="remove", path="...")
• 列出：manage_search_paths(operation="list") 创建/更新 skill-paths.json。

故障排除

如果技能未被发现，使用 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：主服务器逻辑。
• build/：编译后的 JavaScript 输出。
• package.json：依赖项（@modelcontextprotocol/sdk，zod）。

贡献

要添加新技能，只需将包含 SKILL.md 文件的文件夹添加到其中一个监视目录中。服务器会自动获取它们（新文件无需重启，不过缓存实现可能会有所不同）。

📄 许可证

本项目采用 MIT 许可证。