{
  "markdown": "# Agent Skill Loader 🧠\n\n[![npm version](https://img.shields.io/npm/v/agent-skill-loader)](https://www.npmjs.com/package/agent-skill-loader)\n[![MCP Registry](https://img.shields.io/badge/MCP-Registry-green)](https://registry.modelcontextprotocol.io)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue)](https://www.typescriptlang.org/)\n[![MCP](https://img.shields.io/badge/MCP-Compatible-purple)](https://modelcontextprotocol.io)\n\n**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).\n\nIt 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.\n\n## 🚀 Features\n\n- **MCP Prompts**: Skills appear as slash commands in clients. No tool call needed to inject them.\n- **Live updates**: `listChanged` notification fires when skills are added or removed (via file watcher).\n- **Discovery**: `list_skills` — scans configured skill directories, with optional search filter.\n- **Dynamic Learning**: `read_skill` — fetches the `SKILL.md` content.\n- **Persistence**: `install_skill` — copies a skill permanently to your project.\n- **Configuration**: `manage_search_paths` — add/remove skill directories at runtime.\n- **Troubleshooting**: `debug_info` — diagnose configuration and path issues.\n\n## 🛠️ Setup\n\n### Prerequisites\n- Node.js >= 18\n\n### Option A: Install from npm (Recommended)\n```bash\nnpm install -g agent-skill-loader\n```\n\nThen register in `.mcp.json`:\n```json\n\"agent-skill-loader\": {\n  \"command\": \"agent-skill-loader\"\n}\n```\n\n### Option B: Build from Source\n```bash\ngit clone https://github.com/back1ply/agent-skill-loader.git\ncd agent-skill-loader\nnpm install\nnpm run build\n```\n\nThen register in `.mcp.json`:\n```json\n\"agent-skill-loader\": {\n  \"command\": \"node\",\n  \"args\": [\"<path-to-repo>/build/index.js\"]\n}\n```\n\n## 📂 Configuration\n\nThe server automatically detects its workspace and aggregates skill paths from:\n\n1. **Default**: `%USERPROFILE%\\.claude\\plugins\\cache` (Standard location)\n2. **Dynamic Config**: `skill-paths.json` (Located in the project root)\n\n### Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `MCP_SKILL_PATHS` | JSON array or semicolon/comma-separated list of additional skill paths |\n| `MCP_WORKSPACE_ROOT` | Override auto-detected workspace root |\n| `MCP_NO_WATCH` | Set to `1` to disable the file watcher (useful in CI) |\n\n### Dynamic Path Management\nYou do not need to manually edit config files. Use the tool to manage paths at runtime:\n- **Add**: `manage_search_paths(operation=\"add\", path=\"F:\\\\My\\\\Deep\\\\Skills\")`\n- **Remove**: `manage_search_paths(operation=\"remove\", path=\"...\")`\n- **List**: `manage_search_paths(operation=\"list\")` creates/updates `skill-paths.json`.\n\n## 🤖 Usage\n\n### MCP Prompts (Slash Commands)\n\nIf 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.\n\n### Tools\n\nThe agent has access to five tools:\n\n- `list_skills(query?)`: Returns a JSON list of available skills. Optional `query` filters by name/description substring (case-insensitive).\n- `read_skill(skill_name)`: Returns the markdown instructions for a skill.\n- `install_skill(skill_name, target_path?)`: Copies the skill folder to `.agent/skills/<name>`. For security, `target_path` must be within the current workspace.\n- `manage_search_paths(operation, path?)`: Add, remove, or list skill search paths.\n- `debug_info()`: Returns diagnostic information (paths, status, warnings).\n\n### Example Agent Prompt\n> \"I need to write a DAX measure but I'm not sure about the best practices.\"\n\nThe 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.\n\n## 🔧 Troubleshooting\n\nIf skills aren't being discovered, use `debug_info()` to see:\n- **search_paths**: Which directories are being scanned\n- **path_status**: Whether each path exists and is readable\n- **warnings**: Any errors encountered during scanning (permission denied, empty files, etc.)\n\nExample output:\n```json\n{\n  \"workspace_root\": \"C:/projects/agent-skill-loader\",\n  \"search_paths\": {\n    \"base\": [\"C:/Users/pc/.claude/plugins/cache\"],\n    \"dynamic\": [\"F:/My/Skills\"],\n    \"effective\": [\"C:/Users/pc/.claude/plugins/cache\", \"F:/My/Skills\"]\n  },\n  \"path_status\": [\n    { \"path\": \"C:/Users/pc/.claude/plugins/cache\", \"exists\": true, \"readable\": true },\n    { \"path\": \"F:/My/Skills\", \"exists\": false, \"readable\": false }\n  ],\n  \"skills_found\": 12,\n  \"warnings\": [\n    { \"path\": \"F:/My/Skills\", \"reason\": \"Directory does not exist\" }\n  ]\n}\n```\n\n## 📦 Project Structure\n\n- `src/index.ts`: Main server logic (tools + prompts + watcher).\n- `src/utils.ts`: Skill scanning, description extraction, prompt helpers, debounce.\n- `build/`: Compiled JavaScript output.\n- `package.json`: Dependencies (`@modelcontextprotocol/sdk`, `chokidar`, `zod`).\n\n## 🤝 Contributing\n\nTo 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.\n",
  "bytes": 5708,
  "sha": "a862b9361f15762d3c8d6acc7da9959fb3a32dd71d5c343d45f23bf89e8e8063",
  "repo_slug": "back1ply/agent-skill-loader",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_back1ply_agent_skill_loader_6587e61b/readme"
}