Skip to main content
Glama

Python MCP FastMCP uv Licença


Visão geral

Quem acumula dezenas ou centenas de skills paga por isso em toda sessão: cada cliente (Claude Code, Gemini CLI, Cursor...) carrega a descrição de todas elas no contexto, use ou não.

Este projeto troca esse custo fixo por uma busca. As skills saem das pastas dos clientes e vão para uma fonte única; o agente passa a enxergar nativamente só um orquestrador e as skills que você fixar, e busca o resto quando precisa.

Related MCP server: skill-router-mcp

Arquitetura e fluxo

São duas peças: a meta-skill diz ao agente quando e como buscar; o servidor MCP executa a busca e entrega o conteúdo.

flowchart LR
    subgraph Clientes["Clientes de IA"]
        CC["Claude Code"]
        GC["Gemini CLI"]
        CU["Cursor"]
        OT["Codex / opencode / Antigravity"]
    end

    subgraph Nativo["Carregado em toda sessão"]
        ORQ["skill-orchestrator"]
        PIN["skills fixadas (--pin)"]
    end

    subgraph Router["Servidor MCP: skills-router"]
        SRV["server.py (FastMCP)"]
        IDX["indexer.py"]
    end

    subgraph Runtime["~/.ai-skills"]
        SK[("skills/")]
        DR[("drafts/")]
        IX[("index.json")]
    end

    Clientes --> ORQ
    Clientes --> PIN
    ORQ -->|"search / get"| SRV
    SRV --> IDX
    IDX --> IX
    IDX --> SK
    SRV -->|"propose_skill_draft"| DR
    DR -->|"promote_draft (aprovado)"| SK
    PIN -.->|"symlink"| SK
    ORQ -.->|"symlink"| SK

O que acontece numa tarefa comum:

sequenceDiagram
    actor U as Você
    participant A as Agente
    participant R as skills-router
    participant F as ~/.ai-skills

    U->>A: "Crie uma landing page para um SaaS"
    A->>R: search_installed_skills("landing page saas")
    R->>F: lê index.json (reindexa se algo mudou)
    R-->>A: nome, descrição, tags, score
    Note over A: Decide: reaproveitar, combinar ou apontar lacuna
    A->>R: get_skill_content("landing-page-design")
    R->>F: lê só o SKILL.md escolhido
    R-->>A: conteúdo completo + arquivos de apoio
    A-->>U: executa a tarefa seguindo a skill

Início rápido

Requer uv e Python 3.10+.

git clone https://github.com/DyoneNunes/mcp-manage-router-skill.git
cd mcp-manage-router-skill

uv run skills-router init --dry-run   # mostra o que seria feito, sem alterar nada
uv run skills-router init             # executa

Depois, reinicie os clientes para carregarem o servidor MCP e a nova lista de skills.

IMPORTANT

Oinit move as skills que já existem nas pastas dos seus clientes. Nada é apagado: os originais vão para ~/.ai-skills/backups/<data>/ com um manifesto, e skills-router restore desfaz tudo. Rode o --dry-run antes.

Para manter algumas skills nativas (aparecendo no menu / do cliente), fixe-as:

uv run skills-router init --pin minha-skill --pin outra-skill
  1. Cria ~/.ai-skills/skills e ~/.ai-skills/drafts.

  2. Instala a meta-skill em ~/.ai-skills/skills/skill-orchestrator/SKILL.md.

  3. Detecta os clientes instalados e importa as skills que eles já têm para a fonte única. Skills idênticas em vários clientes são importadas uma vez só.

  4. Move os originais para ~/.ai-skills/backups/<data>/, com manifesto.

  5. Deixa na pasta de skills de cada cliente apenas symlinks para o orquestrador e para as skills fixadas.

  6. Registra o servidor MCP skills-router na config global de cada cliente, com cópia de segurança do arquivo antes de editar.

  7. Instala as skills incluídas que você ainda não tiver.

  8. Gera o index.json inicial.

Itens que não são skills (pastas sem SKILL.md, diretórios ocultos) nunca são movidos. Se dois clientes tiverem skills homônimas com conteúdo diferente, a primeira é mantida e a outra vai para ~/.ai-skills/conflicts/ para você decidir.

Opção

Efeito

--dry-run

Só relata; não altera nada.

--pin NOME

Mantém a skill nativa nos clientes (repetível).

--expose all

A pasta do cliente vira symlink para ~/.ai-skills/skills inteira. Unifica, mas não economiza contexto.

--clients claude,cursor

Restringe os clientes tratados.

--server-command "..."

Define o comando usado pelos clientes para subir o servidor.

Cliente

Pasta de skills

Config MCP

Claude Code

~/.claude/skills

claude mcp add --scope user (ou ~/.claude.json)

Gemini CLI

~/.gemini/skills

~/.gemini/settings.json

Cursor

~/.cursor/skills

~/.cursor/mcp.json

Codex CLI

~/.codex/skills

~/.codex/config.toml

opencode

~/.config/opencode/skills

~/.config/opencode/opencode.json

Antigravity

~/.gemini/config/skills

~/.gemini/config/mcp_config.json

~/.agents (compartilhado)

~/.agents/skills

não se aplica

TIP

Prefere instalar como ferramenta global? Useuv tool install git+https://github.com/DyoneNunes/mcp-manage-router-skill e rode skills-router init de qualquer lugar.

Tools do servidor MCP

Tool

O que faz

search_installed_skills(query, limit=5)

Busca por relevância no índice. Devolve só name, description, tags, path e score.

get_skill_content(skill_name)

Devolve o SKILL.md completo da skill escolhida e a lista de arquivos de apoio.

rebuild_index()

Força a reindexação do diretório oficial.

propose_skill_draft(name, description, content)

Salva um rascunho somente em drafts/<name>/SKILL.md.

promote_draft(skill_name)

Move o rascunho para skills/ e reindexa.

A busca é por palavras-chave, não semântica. Como a maioria das skills é descrita em inglês, consultas em inglês costumam achar mais.

Meta-skill skill-orchestrator

Distribuída em templates/skill-orchestrator/SKILL.md e instalada pelo init. Ela impõe três regras ao agente:

  1. Gatilho. Em tarefas de desenvolvimento, arquitetura ou automação, buscar primeiro.

  2. Gatekeeping. Reaproveitar uma skill existente; se nenhuma cobre sozinha, combinar duas ou três; só então apontar a lacuna e sugerir uma skill externa ou nova.

  3. Human-in-the-loop. Propor skill nova apenas para tarefas com mais de três passos específicos e claramente reutilizáveis, pedindo confirmação antes do rascunho e de novo antes da promoção.

WARNING

O servidor não tem como verificar que um humano aprovou opromote_draft. A garantia vem das regras da meta-skill e do pedido de permissão do próprio cliente. Para promover você mesmo, use skills-router promote NOME no terminal.

Skills incluídas

Além do orquestrador, o pacote traz skills prontas em templates/. O init as copia para ~/.ai-skills/skills apenas se você ainda não tiver uma skill com o mesmo nome, então uma versão sua nunca é sobrescrita. Elas não são fixadas: ficam disponíveis pela busca, e você expõe com skills-router pin NOME se quiser.

Skill

O que faz

license-designer

Escolhe, redige e aplica a licença de um repositório: entrevista sobre o que permitir e proibir, detecta contradições como "MIT mas proibido vender", gera o LICENSE com o texto oficial e sincroniza manifestos e README.

Referência

skills-router status            # runtime, total indexado, fixadas e links por cliente
skills-router search fastapi postgres
skills-router pin NOME          # expõe uma skill nativamente
skills-router unpin NOME
skills-router drafts            # rascunhos em quarentena
skills-router promote NOME      # promoção feita por você, pelo terminal
skills-router reindex
skills-router restore           # desfaz o init a partir do último backup
skills-router serve             # sobe o servidor MCP em stdio
~/.ai-skills/
├── skills/        fonte única de verdade (uma pasta por skill, com SKILL.md)
├── drafts/        quarentena de rascunhos aguardando aprovação humana
├── index.json     cache leve: name, description, tags e path de cada skill
├── config.json    preferências desta máquina (skills fixadas, clientes)
├── backups/       originais movidos pelo init + manifesto para o restore
└── conflicts/     versões divergentes de skills com o mesmo nome

Defina AI_SKILLS_HOME para usar outro diretório. Pacotes que agrupam sub-skills em <pacote>/skills/<sub>/SKILL.md também são indexados.

uv sync
AI_SKILLS_HOME=/tmp/ai-skills-teste uv run skills-router status
uv run skills-router serve

Para testar o instalador sem tocar nas suas pastas, aponte HOME para um diretório temporário:

export FAKE=$(mktemp -d)
HOME=$FAKE uv run skills-router init --dry-run

Para inspecionar as tools sem um agente:

npx @modelcontextprotocol/inspector uv run skills-router serve

Privacidade

O repositório não guarda nada sobre quem o usa:

  • Caminhos saem de $HOME ou de AI_SKILLS_HOME.

  • Preferências (skills fixadas, clientes) ficam em ~/.ai-skills/config.json.

  • Autoria dos rascunhos é lida em tempo de execução do git config --global user.name ou do usuário do sistema.

  • index.json, rascunhos e backups nunca são versionados.

Licença

MIT + Commons Clause v1.0 © 2026 Dyone Andrade — contato@dyonedev.com.br

O código é aberto e gratuito, mas não pode ser vendido.

Pode

Não pode

Usar gratuitamente, em casa ou dentro da sua empresa

Vender o software, no todo ou em parte

Estudar, copiar e modificar

Cobrar por produto ou serviço cujo valor venha substancialmente dele (hospedagem, consultoria ou suporte pagos)

Redistribuir gratuitamente, mantendo a licença e o copyright

Remover ou alterar o aviso de licença

Por causa da restrição de venda, esta não é uma licença "open source" na definição da OSI; o termo correto é source-available. Para uso comercial fora desses termos, fale com o autor.

Available Tools

5 tools
get_skill_contentGet Skill ContentA

Lê o SKILL.md completo de UMA skill escolhida (use após search_installed_skills).

Inputs: skill_name (required). Returns: object

promote_draftPromote DraftA

Move drafts/<skill_name> para skills/ e reindexa. Exige aprovação humana explícita.

Inputs: skill_name (required). Returns: object

propose_skill_draftPropose Skill DraftA

Salva um RASCUNHO de skill em drafts//SKILL.md (nunca em skills/).

Só chame depois de o humano confirmar explicitamente que quer o rascunho. content é o corpo em Markdown; um frontmatter enviado junto é mesclado.

Inputs: name (required), content (required), description (required). Returns: object

rebuild_indexRebuild IndexB

Força a reindexação completa do diretório oficial de skills.

Inputs: no named parameters. Returns: object

search_installed_skillsSearch Installed SkillsA

Busca skills instaladas por relevância e devolve só metadados resumidos + score.

Não carrega nenhum SKILL.md. Use palavras-chave da stack/tarefa (os metadados costumam estar em inglês) e faça mais de uma busca se a tarefa cruzar domínios.

Inputs: query (required), limit. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool targets a clearly distinct action: search (discover), get content (read), rebuild (maintenance), propose draft (create), promote draft (publish). The descriptions even specify sequencing (use search before get, propose before promote), leaving no room for misselection.

    Naming Consistency5/5

    All five tools follow a consistent snake_case verb_noun pattern: search_installed_skills, get_skill_content, rebuild_index, propose_skill_draft, promote_draft. No mixed conventions.

    Tool Count5/5

    Five tools map cleanly onto the discover/read/maintain/draft/publish lifecycle of a skills router. Well within the ideal 3-15 range with no filler.

    Completeness4/5

    The core discovery and draft-promotion lifecycle is covered, but there is no discard/delete draft, edit-existing-skill, or list-drafts operation, so agents may hit dead ends when managing or reverting drafts.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables coding agents to search, recommend, and validate a stack of reusable skills from a local catalog, producing deterministic plans without modifying the project.
      1
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables read-only access to a local-first catalog of portable agent skills, exposing tools to discover ranked matches, inspect stored artifacts, traverse declared relationships, and view configuration.
      5
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI coding agents to discover relevant reusable skills and external servers through read-only search, with concise paginated results and detail lookup before anything is installed.
      1
      MIT