back1ply/agent-skill-loader

npm version MCP Registry License: MIT Node.js Version TypeScript MCP

Agent Skill Loader is a Model Context Protocol (MCP) server that acts as a bridge between your static Claude Code Skills library and dynamic AI agents (like Antigravity, Claude Desktop, or Cursor).

It allows agents to "learn" skills on demand without requiring you to manually copy files into every project.

🚀 Features

• Discovery: list_skills - Scans your configured skill directories.
• Dynamic Learning: read_skill - Fetches the SKILL.md content for the agent to read.
• Persistence: install_skill - Copies the skill permanently to your project if needed.
• Configuration: manage_search_paths - Add/remove skill directories at runtime.
• Troubleshooting: debug_info - Diagnose configuration and path issues.

🛠️ Setup

Prerequisites

• Node.js >= 18

Option A: Install from npm (Recommended)

npm install -g agent-skill-loader

Then register in .mcp.json:

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

Option B: Build from Source

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

Then register in .mcp.json:

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

📂 Configuration

The server automatically detects its workspace and aggregates skill paths from:

1. Default: %USERPROFILE%\.claude\plugins\cache (Standard location)
2. Dynamic Config: skill-paths.json (Located in the project root)

Dynamic Path Management

You do not need to manually edit config files. Use the tool to manage paths at runtime:

• Add: manage_search_paths(operation="add", path="F:\\My\\Deep\\Skills")
• Remove: manage_search_paths(operation="remove", path="...")
• List: manage_search_paths(operation="list") creates/updates skill-paths.json.

🤖 Usage

For Agents

The agent will see five tools:

• list_skills(): Returns a JSON list of available skills.
• read_skill(skill_name): Returns the markdown instructions.
• install_skill(skill_name, target_path?): Copies the folder to .agent/skills/<name>. For security, target_path must be within the current workspace.
• manage_search_paths(operation, path?): Add, remove, or list skill search paths.
• debug_info(): Returns diagnostic information (paths, status, warnings).

Example Agent Prompt

"I need to write a DAX measure but I'm not sure about the best practices."

The agent will automatically call list_skills, find writing-dax-measures, call read_skill, and then answer you with expert knowledge.

🔧 Troubleshooting

If skills aren't being discovered, use debug_info() to see:

• search_paths: Which directories are being scanned
• path_status: Whether each path exists and is readable
• warnings: Any errors encountered during scanning (permission denied, empty files, etc.)

Example output:

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

📦 Project Structure

• src/index.ts: Main server logic.
• build/: Compiled JavaScript output.
• package.json: Dependencies (@modelcontextprotocol/sdk, zod).

🤝 Contributing

To add new skills, simply add a folder with a SKILL.md file to one of the watched directories. The server picks them up automatically (no restart required for new files, though caching implementation may vary).