agent-skill-loader
Retrieves and serves AI agent instructions and skill definitions that are stored and formatted as Markdown files.
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:
listChangednotification 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 theSKILL.mdcontent.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.
Related MCP server: llama-mcp-server
🛠️ Setup
Prerequisites
Node.js >= 18
Option A: Install from npm (Recommended)
npm install -g agent-skill-loaderThen 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 buildThen 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:
Default:
%USERPROFILE%\.claude\plugins\cache(Standard location)Dynamic Config:
skill-paths.json(Located in the project root)
Environment Variables
Variable | Description |
| JSON array or semicolon/comma-separated list of additional skill paths |
| Override auto-detected workspace root |
| Set to |
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/updatesskill-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. Optionalqueryfilters 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_pathmust 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.
Available Tools
5 toolsdebug_infoARead-only
Returns diagnostic information about server configuration, search paths, and any warnings from the last scan. Use this when skills aren't being found or to verify configuration.
Inputs: no named parameters.
install_skillADestructive
Copies an entire skill directory (including SKILL.md and any supporting files) to the target workspace. By default, installs to .agent/skills/<skill_name> in the current working directory.
Inputs: skill_name (required), target_path.
list_skillsARead-only
Returns a JSON list of all available skills with their names, descriptions, and source directories. Use this to discover what skills are available before reading or installing them.
Inputs: query.
manage_search_pathsADestructiveIdempotent
Add, remove, or list dynamic skill search paths without restarting the server. Persists to skill-paths.json in the workspace root.
Inputs: operation (required), path.
read_skillARead-only
Fetches and returns the full SKILL.md content for a specific skill. The content includes instructions and context that can be used to learn the skill's capabilities.
Inputs: skill_name (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clearly distinct purpose: manage_search_paths handles configuration, debug_info provides diagnostics, install_skill copies directories, list_skills enumerates available skills, and read_skill retrieves content. There is no meaningful overlap between them.
All tool names use snake_case with a consistent verb_noun structure (manage_search_paths, debug_info, install_skill, list_skills, read_skill). The pattern is predictable and easy to parse.
Five tools is well-scoped for a skill loader: discovery, reading, installation, path management, and debugging. Each tool earns its place without redundancy.
The core lifecycle of discovering, reading, and installing skills is covered, plus configuration and diagnostics. However, there is no tool to uninstall or remove an installed skill or update an existing one, which are minor gaps.
Maintenance
Related MCP Connectors
MCP server for AI dialogue using various LLM models via AceDataCloud
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
Cloud-hosted MCP server for durable AI memory
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceAn MCP server that transforms Claude-style skills and resources into callable tools for any MCP-compatible agent or client. It automatically discovers, exposes, and executes scripts from skills organized in local directories or packaged archives.MIT
- AlicenseAqualityDmaintenanceMCP server bridging Claude Code to local llama.cpp. Run local LLMs alongside Claude for experimentation, testing, and cost-effective inference.1913 npm1MIT
- AlicenseAqualityDmaintenanceMCP server that integrates OpenClaw AI assistant with Claude Code, enabling chat, task management, messaging, memory, alerts, agent spawning, and web search through configurable tools.12406 npmMIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server that provides intelligent discovery, search, and on-demand loading of Claude Code skills and agents, reducing token usage by lazy loading.-