io.github.back1ply/agent-skill-loader

Agent Skill Loader 🧠

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 Claude Desktop, Cursor, or any MCP client).

It exposes skills both as MCP Prompts (slash commands, zero tool calls needed) and as MCP Tools (for programmatic use). Skills are auto-discovered from configured directories and stay live — add a new SKILL.md and the client is notified automatically.

🚀 Features

• MCP Prompts: Skills appear as slash commands in clients. No tool call needed to inject them.
• Live updates: listChanged notification fires when skills are added or removed (via file watcher).
• Discovery: list_skills — scans configured skill directories, with optional search filter.
• Dynamic Learning: read_skill — fetches the SKILL.md content.
• Persistence: install_skill — copies a skill permanently to your project.
• 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)

Environment Variables

Variable	Description
MCP_SKILL_PATHS	JSON array or semicolon/comma-separated list of additional skill paths
MCP_WORKSPACE_ROOT	Override auto-detected workspace root
MCP_NO_WATCH	Set to 1 to disable the file watcher (useful in CI)

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

MCP Prompts (Slash Commands)

If your client supports MCP Prompts (Claude Desktop, Cursor, etc.), skills appear automatically as slash commands. Select a skill from the slash command menu to inject its content directly — no tool calls needed.

Tools

The agent has access to five tools:

• list_skills(query?): Returns a JSON list of available skills. Optional query filters by name/description substring (case-insensitive).
• read_skill(skill_name): Returns the markdown instructions for a skill.
• install_skill(skill_name, target_path?): Copies the skill 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 answer with expert knowledge. Or the user can invoke the skill directly as a slash command.

🔧 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 (tools + prompts + watcher).
• src/utils.ts: Skill scanning, description extraction, prompt helpers, debounce.
• build/: Compiled JavaScript output.
• package.json: Dependencies (@modelcontextprotocol/sdk, chokidar, zod).

🤝 Contributing

To add new skills, add a folder with a SKILL.md file to one of the watched directories. The server picks them up automatically and sends a listChanged notification — no restart required.