Agent Skill Loader

Servidor MCP para carregar dinamicamente habilidades do Claude Code em agentes de IA.

Documentação

Agent Skill Loader 🧠

Agent Skill Loader é um servidor Model Context Protocol (MCP) que atua como uma ponte entre sua biblioteca estática de Skills do Claude Code e agentes de IA dinâmicos (como Claude Desktop, Cursor ou qualquer cliente MCP).

Ele expõe skills tanto como MCP Prompts (comandos de barra, sem necessidade de chamadas de ferramenta) quanto como MCP Tools (para uso programático). As skills são descobertas automaticamente em diretórios configurados e permanecem ativas — adicione um novo SKILL.md e o cliente é notificado automaticamente.

🚀 Recursos

MCP Prompts: Skills aparecem como comandos de barra nos clientes. Nenhuma chamada de ferramenta é necessária para injetá-las.
Atualizações ao vivo: a notificação listChanged é disparada quando skills são adicionadas ou removidas (via file watcher).
Descoberta: list_skills — verifica os diretórios de skills configurados, com filtro de busca opcional.
Aprendizado dinâmico: read_skill — busca o conteúdo de SKILL.md.
Persistência: install_skill — copia uma skill permanentemente para o seu projeto.
Configuração: manage_search_paths — adiciona/remove diretórios de skills em tempo de execução.
Solução de problemas: debug_info — diagnostica problemas de configuração e caminhos.

🛠️ Instalação

Pré-requisitos

Node.js >= 18

Opção A: Instalar via npm (Recomendado)

npm install -g agent-skill-loader

Em seguida, registre em .mcp.json:

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

Opção B: Compilar a partir do código-fonte

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

Em seguida, registre em .mcp.json:

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

📂 Configuração

O servidor detecta automaticamente seu workspace e agrega os caminhos de skills de:

Padrão: %USERPROFILE%\.claude\plugins\cache (Local padrão)
Config dinâmica: skill-paths.json (Localizado na raiz do projeto)

Variáveis de Ambiente

Variável	Descrição
`MCP_SKILL_PATHS`	Array JSON ou lista separada por ponto e vírgula/vírgula de caminhos adicionais de skills
`MCP_WORKSPACE_ROOT`	Substitui a raiz do workspace detectada automaticamente
`MCP_NO_WATCH`	Defina como `1` para desativar o file watcher (útil em CI)

Gerenciamento Dinâmico de Caminhos

Você não precisa editar manualmente os arquivos de configuração. Use a ferramenta para gerenciar caminhos em tempo de execução:

Adicionar: manage_search_paths(operation="add", path="F:\\My\\Deep\\Skills")
Remover: manage_search_paths(operation="remove", path="...")
Listar: manage_search_paths(operation="list") cria/atualiza skill-paths.json.

🤖 Uso

MCP Prompts (Comandos de Barra)

Se o seu cliente suporta MCP Prompts (Claude Desktop, Cursor, etc.), as skills aparecem automaticamente como comandos de barra. Selecione uma skill no menu de comandos de barra para injetar seu conteúdo diretamente — sem necessidade de chamadas de ferramenta.

Ferramentas

O agente tem acesso a cinco ferramentas:

list_skills(query?): Retorna uma lista JSON de skills disponíveis. O query opcional filtra por substring de nome/descrição (sem diferenciar maiúsculas de minúsculas).
read_skill(skill_name): Retorna as instruções markdown de uma skill.
install_skill(skill_name, target_path?): Copia a pasta da skill para .agent/skills/<name>. Por segurança, target_path deve estar dentro do workspace atual.
manage_search_paths(operation, path?): Adiciona, remove ou lista caminhos de busca de skills.
debug_info(): Retorna informações de diagnóstico (caminhos, status, avisos).

Exemplo de Prompt de Agente

"Preciso escrever uma medida DAX, mas não tenho certeza sobre as melhores práticas."

O agente chamará automaticamente list_skills, encontrará writing-dax-measures, chamará read_skill e responderá com conhecimento especializado. Ou o usuário pode invocar a skill diretamente como um comando de barra.

🔧 Solução de Problemas

Se as skills não estão sendo descobertas, use debug_info() para ver:

search_paths: Quais diretórios estão sendo verificados
path_status: Se cada caminho existe e é legível
warnings: Quaisquer erros encontrados durante a verificação (permissão negada, arquivos vazios, etc.)

Exemplo de saída:

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

📦 Estrutura do Projeto

src/index.ts: Lógica principal do servidor (ferramentas + prompts + watcher).
src/utils.ts: Verificação de skills, extração de descrição, helpers de prompt, debounce.
build/: Saída JavaScript compilada.
package.json: Dependências (@modelcontextprotocol/sdk, chokidar, zod).

🤝 Contribuindo

Para adicionar novas skills, adicione uma pasta com um arquivo SKILL.md em um dos diretórios monitorados. O servidor as detecta automaticamente e envia uma notificação listChanged — sem necessidade de reiniciar.