Agent Skill Loader

Servidor MCP para cargar dinámicamente habilidades de Claude Code en agentes de IA

Documentación

Agent Skill Loader 🧠

Agent Skill Loader es un servidor de Model Context Protocol (MCP) que actúa como puente entre tu biblioteca estática de Claude Code Skills y agentes de IA dinámicos (como Claude Desktop, Cursor o cualquier cliente MCP).

Expone las habilidades tanto como MCP Prompts (comandos de barra, sin necesidad de llamadas a herramientas) como MCP Tools (para uso programático). Las habilidades se descubren automáticamente desde directorios configurados y permanecen activas: agrega un nuevo SKILL.md y el cliente es notificado automáticamente.

🚀 Características

MCP Prompts: Las habilidades aparecen como comandos de barra en los clientes. No se necesita llamada a herramienta para inyectarlas.
Actualizaciones en vivo: La notificación listChanged se dispara cuando se agregan o eliminan habilidades (mediante el observador de archivos).
Descubrimiento: list_skills — escanea los directorios de habilidades configurados, con filtro de búsqueda opcional.
Aprendizaje dinámico: read_skill — obtiene el contenido de SKILL.md.
Persistencia: install_skill — copia una habilidad permanentemente a tu proyecto.
Configuración: manage_search_paths — agrega/elimina directorios de habilidades en tiempo de ejecución.
Solución de problemas: debug_info — diagnostica problemas de configuración y rutas.

🛠️ Instalación

Requisitos previos

Node.js >= 18

Opción A: Instalar desde npm (Recomendado)

npm install -g agent-skill-loader

Luego regístralo en .mcp.json:

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

Opción B: Compilar desde el código fuente

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

Luego regístralo en .mcp.json:

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

📂 Configuración

El servidor detecta automáticamente su espacio de trabajo y agrega rutas de habilidades desde:

Predeterminado: %USERPROFILE%\.claude\plugins\cache (Ubicación estándar)
Configuración dinámica: skill-paths.json (Ubicado en la raíz del proyecto)

Variables de entorno

Variable	Descripción
`MCP_SKILL_PATHS`	Matriz JSON o lista separada por punto y coma/comas de rutas de habilidades adicionales
`MCP_WORKSPACE_ROOT`	Sobrescribir la raíz del espacio de trabajo auto-detectada
`MCP_NO_WATCH`	Establecer a `1` para deshabilitar el observador de archivos (útil en CI)

Gestión dinámica de rutas

No necesitas editar manualmente los archivos de configuración. Usa la herramienta para gestionar rutas en tiempo de ejecución:

Agregar: manage_search_paths(operation="add", path="F:\\My\\Deep\\Skills")
Eliminar: manage_search_paths(operation="remove", path="...")
Listar: manage_search_paths(operation="list") crea/actualiza skill-paths.json.

🤖 Uso

MCP Prompts (Comandos de barra)

Si tu cliente admite MCP Prompts (Claude Desktop, Cursor, etc.), las habilidades aparecen automáticamente como comandos de barra. Selecciona una habilidad desde el menú de comandos de barra para inyectar su contenido directamente — no se necesitan llamadas a herramientas.

Herramientas

El agente tiene acceso a cinco herramientas:

list_skills(query?): Devuelve una lista JSON de habilidades disponibles. El query opcional filtra por subcadena de nombre/descripción (sin distinción de mayúsculas).
read_skill(skill_name): Devuelve las instrucciones de markdown para una habilidad.
install_skill(skill_name, target_path?): Copia la carpeta de la habilidad a .agent/skills/<name>. Por seguridad, target_path debe estar dentro del espacio de trabajo actual.
manage_search_paths(operation, path?): Agregar, eliminar o listar rutas de búsqueda de habilidades.
debug_info(): Devuelve información de diagnóstico (rutas, estado, advertencias).

Ejemplo de prompt de agente

"Necesito escribir una medida DAX pero no estoy seguro de las mejores prácticas."

El agente llamará automáticamente a list_skills, encontrará writing-dax-measures, llamará a read_skill y responderá con conocimiento experto. O el usuario puede invocar la habilidad directamente como un comando de barra.

🔧 Solución de problemas

Si las habilidades no se están descubriendo, usa debug_info() para ver:

search_paths: Qué directorios se están escaneando
path_status: Si cada ruta existe y es legible
warnings: Cualquier error encontrado durante el escaneo (permiso denegado, archivos vacíos, etc.)

Ejemplo de salida:

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

📦 Estructura del proyecto

src/index.ts: Lógica principal del servidor (herramientas + prompts + observador).
src/utils.ts: Escaneo de habilidades, extracción de descripciones, ayudantes de prompts, debounce.
build/: Salida de JavaScript compilado.
package.json: Dependencias (@modelcontextprotocol/sdk, chokidar, zod).

🤝 Contribuciones

Para agregar nuevas habilidades, agrega una carpeta con un archivo SKILL.md a uno de los directorios observados. El servidor las recoge automáticamente y envía una notificación listChanged — no se requiere reinicio.