Skill Master MCP

Versao planejada: 00.03

Este repositorio e a base independente do MCP skill_master. Ele nao pertence ao LinkBiz e deve evoluir como um projeto pessoal, preferencialmente publicado em um GitHub particular.

Objetivo

Criar um MCP capaz de catalogar skills locais e remotas, recomendar as melhores skills para um prompt e manter atualizacoes automaticas para varios computadores e usuarios.

Decisao da versao 00.03

A versao 00.03 consolida:

• distribuicao publica por npmjs.org
• distribuicao privada por GitHub Packages
• manifesto remoto de versao e canal
• launcher local com verificacao de atualizacao
• atualizacao por git pull --ff-only quando o diretorio estiver limpo
• fallback seguro quando houver alteracoes locais
• arquitetura preparada para MCP remoto no futuro

Compatibilidade atual

O projeto agora possui fluxo operacional para:

• Windows: scripts/install-skill-master.ps1, scripts/update-skill-master.ps1, scripts/skill-master-launcher.ps1
• Linux: scripts/install-skill-master.sh, scripts/update-skill-master.sh, scripts/skill-master-launcher.sh
• clientes AI: Codex, Claude Desktop, Claude Code, Gemini CLI, Gemini Code Assist e clientes MCP genericos via stdio

Requisitos praticos:

• git para o modo clone + launcher
• node 18+
• npm
• acesso ao repositorio GitHub configurado no fluxo privado

Instalacao rapida

Windows

npm install -g @fprad0/skill-master-mcp

Linux / macOS

npm install -g @fprad0/skill-master-mcp

Se a ideia for apenas testar sem install global:

npx -y @fprad0/skill-master-mcp@latest

Instalacao via pacote privado

O projeto tambem pode ser distribuido como pacote privado via GitHub Packages.

Nome do pacote:

@fprad0/skill-master-mcp

Fluxo resumido:

1. autenticar o npm no registry privado;
2. configurar o cliente MCP para executar npx -y @fprad0/skill-master-mcp@latest;
3. reiniciar o cliente.

Atalhos operacionais:

• Windows: powershell -ExecutionPolicy Bypass -File .\scripts\configure-private-registry.ps1 -Validate
• Linux: bash ./scripts/configure-private-registry.sh --validate

Bootstrap direto pelo pacote, para maquinas que ja conseguem resolver o escopo @fprad0 no GitHub Packages:

• PowerShell: $env:GITHUB_PACKAGES_TOKEN='SEU_TOKEN'; npx -y -p @fprad0/skill-master-mcp skill-master-configure-private-registry --validate
• Bash: GITHUB_PACKAGES_TOKEN='SEU_TOKEN' npx -y -p @fprad0/skill-master-mcp skill-master-configure-private-registry --validate

Por padrao, o configurador grava o .npmrc usando ${GITHUB_PACKAGES_TOKEN} em vez de persistir o token literal. Para ambientes que exigem token gravado no arquivo, use --store-token de forma consciente.

Exemplo de .npmrc:

@fprad0:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}

Leia:

• Guia de instalacao via pacote privado

Instalacao via npm publico

O pacote publico ja esta disponivel em npmjs.org.

Comandos principais:

npm install -g @fprad0/skill-master-mcp

npx -y @fprad0/skill-master-mcp@latest

Fluxo atual:

• instalacao publica simples por npm install -g @fprad0/skill-master-mcp
• execucao sem install global por npx -y @fprad0/skill-master-mcp@latest
• validacao rapida da versao publicada por npm view @fprad0/skill-master-mcp version --registry=https://registry.npmjs.org
• esta linha de release publica o HUD Reborn v1.0.1, com DNA cyberpunk pixel art mais artistico e registro MCP multi-cliente com Node absoluto

Comandos globais principais:

skill-master-activation
skill-master-doctor
skill-master-eval-activation
skill-master-install-global-skills
skill-master-mcp
skill-master-menu
skill-master-register-clients
skill-master-success-skills
skill-master-update
skill-master-configure-private-registry

O skill-master-mcp deve continuar reservado para clientes MCP via stdio. Para operacao humana, status local e checks, use:

skill-master-menu

O menu agora possui modo visual interativo para terminal com TTY e tambem aceita execucao direta por acao:

skill-master-menu --run status
skill-master-menu --run doctor
skill-master-menu --run check
skill-master-menu --run update --yes
skill-master-menu --run install-global-skills
skill-master-menu --run install-project-skills
skill-master-menu --run bootstrap-global
skill-master-menu --run register-clients
skill-master-menu --run notifications
skill-master-menu --run study-skills
skill-master-menu --run approval-package
skill-master-menu --run activation-status
skill-master-menu --run recommend-prompt
skill-master-menu --run notion-summary

O menu visual usa prompts para ficar mais legivel no terminal e manter compatibilidade com Node 18+.

Quando o menu detectar que o MCP ainda nao esta globalmente pronto neste computador, ele mostra um alerta forte e um aviso sutil explicando que a instalacao global e o registro dos clientes sao necessarios para o skill_master parecer parte do sistema em Codex, Claude, Gemini e Antigravity.

Em instalacoes globais via npm, o menu tambem separa acoes operacionais de acoes de desenvolvimento. Acoes como check e build dependem do clone completo do repositorio; quando o pacote estiver instalado globalmente, use:

skill-master-menu --run doctor
skill-master-menu --run status
skill-master-menu --run bootstrap-global --yes

Para instalar as skills globais embutidas de discernimento, conhecimento amplo, engenharia e governanca moral:

skill-master-install-global-skills

No estado atual do pacote, esse bundle global tambem inclui cobertura para frontend, backend, CLI, terminal, GitHub, Windows/Linux, clientes MCP, design, Figma, Playwright, idiomas e raciocinio tecnico, usando uma combinacao de skills locais aprovadas e skills oficiais empacotadas em docs/skill-candidates/v0.0.10 e docs/skill-candidates/v0.0.11.

O bundle tambem inclui uma camada senior master de otimizacao e hardening por linguagem em docs/skill-candidates/v0.0.12, cobrindo TypeScript, Python, JavaScript, Go, SQL, JSON, Ruby, React, HTML, CSS e C#. Essas skills orientam escrita, organizacao, reducao de complexidade, performance, seguranca, testes e validacao real antes de declarar uma mudanca pronta.

O pacote v1.0.1 preserva esse bundle granular e adiciona a passada visual Reborn do menu, com HUD operacional mais estavel, estados de execucao mais claros e um DNA-CORE mais artistico em cyberpunk pixel art.

Para instalar o mesmo bundle como skills locais de um projeto, rode o comando dentro da pasta do projeto:

skill-master-install-project-skills --sync-package-json

Por padrao ele copia as skills para:

• .agents/skills
• .codex/skills
• .claude/skills
• .gemini/skills

O comando tambem grava .skill-master/catalog.json e, quando existe package.json, adiciona metadados em skillMaster e o script skill-master:install-project-skills. Isso permite que o projeto fique catalogado e que outro notebook reinstale as skills locais com:

npm run skill-master:install-project-skills

Para projetos npm que precisam materializar o lock depois de alterar dependencias ou scripts, rode:

npm install --package-lock-only

Para fazer o bootstrap global completo em um passo:

skill-master-bootstrap-global

Para registrar o MCP nos clientes principais, use o registrador. Ele grava command com o Node.js absoluto e args com o caminho absoluto de bin/skill-master.mjs, evitando falhas de PATH em Windows, Linux, macOS e apps desktop que nao herdam o terminal:

skill-master-register-clients --apply-codex
skill-master-register-clients --apply-claude
skill-master-register-clients --apply-claude-code --claude-code-scope user
skill-master-register-clients --apply-gemini
skill-master-register-clients --apply-antigravity

Atalho para gerar snippets e aplicar nos clientes principais:

skill-master-register-clients --apply-all

Isso configura o servidor MCP skill_master em Codex, Claude Desktop, Claude Code, Gemini e Antigravity quando os clientes locais estiverem disponiveis. Claude Code e registrado via claude mcp add; reinicie o cliente depois do registro.

Se um cliente ja tiver uma configuracao antiga por skill-master-mcp, npx ou launcher local e nao estiver iniciando, force a migracao para o modo robusto:

skill-master-register-clients --apply-all --force
skill-master-menu --run doctor

No Codex, o bloco recomendado fica no formato:

[mcp_servers.skill_master]
command = "/caminho/absoluto/para/node"
args = ["/caminho/absoluto/para/bin/skill-master.mjs"]
startup_timeout_sec = 120

[mcp_servers.skill_master.env]
SKILL_MASTER_UPDATE_CHANNEL = "stable"

O menu tambem mostra notificacoes de skills aprendidas pendentes e links externos para estudo. As acoes de ativacao sao:

• skill-master-menu --run activate-learned-local: instala uma skill aprovada em .codex/skills do workspace atual.
• skill-master-menu --run activate-learned-global: instala uma skill aprovada em ${CODEX_HOME:-~/.codex}/skills.
• skill-master-menu --run mark-study: registra uma skill candidata como material para estudo.
• skill-master-menu --run reject-skill: rejeita uma skill candidata preservando historico.

Para modo de ativacao e recomendacao local:

skill-master-activation --status
skill-master-activation --set-mode balanced
skill-master-activation --route-prompt "skill-master, recomende skills para este prompt"
skill-master-activation --notion-summary

Para rodar as avaliacoes de ativacao antes de release:

npm run eval:activation

Para atualizar a instalacao global via npm sem iniciar o servidor MCP:

skill-master-update

Esse comando executa o equivalente a:

npm install -g @fprad0/skill-master-mcp@latest --registry=https://registry.npmjs.org

Use skill-master-update antes de abrir ou depois de fechar o cliente MCP. Evite atualizar o pacote enquanto skill-master-mcp esta rodando em stdio, porque o cliente pode manter o processo antigo carregado ate ser reiniciado.

Leia:

• Guia de publicacao no npm publico

Registro no Codex

• Windows registra o MCP usando powershell.exe
• Linux registra o MCP usando /usr/bin/env + bash

Os dois caminhos configuram:

• SKILL_MASTER_CONFIG
• SKILL_MASTER_CACHE
• SKILL_MASTER_MANIFEST_URL
• SKILL_MASTER_UPDATE_CHANNEL
• SKILL_MASTER_RELEASE_BRANCH

Compatibilidade com Claude e Gemini

A versao 00.03 documenta compatibilidade operacional ja preparada para:

• Claude Desktop
• Claude Code
• Gemini CLI
• Gemini Code Assist
• Codex
• clientes MCP genericos

Leia:

• Compatibilidade MCP 00.02
• Exemplos de configuracao

Rede segura de skills

O skill_master pode aprender com as skills ja existentes em cada maquina instalada, mas o compartilhamento entre computadores segue um fluxo seguro:

• catalogo local automatico
• deduplicacao por nome e hash
• pacote local de contribuicao
• revisao de risco e privacidade
• aprovacao humana antes de qualquer distribuicao

Ferramentas MCP principais:

• skill_master_refresh_catalog
• skill_master_prompt_router
• skill_master_activation_check
• skill_master_recommend
• skill_master_moral_discernment
• skill_master_domain_router
• skill_master_bootstrap_global
• skill_master_install_global_skills
• skill_master_prepare_skill_contribution
• skill_master_review_skill_contribution
• skill_master_prepare_success_skill
• skill_master_review_success_skill
• skill_master_list_unapproved_success_skills
• skill_master_prepare_success_skill_approval_package
• skill_master_activate_success_skill

O pacote de contribuicao nao envia arquivos automaticamente, nao executa skills desconhecidas e nao inclui caminhos completos ou corpo bruto por padrao.

O fluxo de aprendizado por implementacoes bem-sucedidas cria rascunhos locais em staging, gera pacote de aprovacao humana e permite ativacao explicita em escopo local ou global. Ele exige evidencias, revisa risco/duplicidade e mantem candidatos externos como nao aprovados ate revisao humana. Nenhuma skill aprendida e publicada automaticamente.

Leia:

• Rede segura de skills
• Aprendizado de implementacoes bem-sucedidas

Modos de ativacao em prompts

Clientes e agentes podem usar skill_master_prompt_router como camada principal antes de decidir se devem acionar recomendacoes de skills, aplicar persona ou bloquear uma acao sensivel.

Modos suportados:

• manual: ativa apenas com mencao direta ao Skill Master ou gate bloqueante.
• balanced: modo recomendado; ativa por mencao direta, tarefa tecnica com skill relevante, Notion, aprendizado, validacao, MCP ou publicacao.
• always-on-assisted: avalia quase todo prompt, mas retorna executionMode: no-op quando nao houver ganho claro.

Exemplo de chamada conceitual:

{
  "prompt": "skill-master, veja se existe uma skill para validar este deploy",
  "activationMode": "balanced",
  "riskTolerance": "normal"
}

Saida esperada:

{
  "shouldActivate": true,
  "personaOverlay": "Dev Senior Master",
  "executionMode": "assist",
  "safetyGates": [],
  "learningOpportunity": false,
  "notionUpdateNeeded": false
}

Use skill_master_activation_check quando precisar apenas de uma decisao menor e retrocompativel de ativacao/recomendacao.

Restricoes explicitas como sem publicar, nao publicar ou nao publique sao tratadas como execucao local. O router deve registrar publication_explicitly_disabled e nao pode transformar essa frase em autorizacao ou intencao de release.

Ativacao explicita:

• skill-master
• skill_master
• skill-master-mcp

Se qualquer alias aparecer no prompt, o retorno esperado e should_activate: true, mode: explicit_mention e confidence: high.

Ativacao inferida:

• quando o prompt nao menciona o MCP diretamente;
• mas o catalogo local, workspace, plugin ou web contem skills relevantes para a tarefa;
• a tool retorna mode: inferred_skill_opportunity, motivos e as skills recomendadas.

Uso recomendado para clientes:

1. chamar skill_master_activation_check com o prompt do usuario;
2. se should_activate for true, apresentar ou aplicar as skills recomendadas conforme as regras do cliente;
3. para skills web ou nao confiaveis, exigir revisao humana antes de instalar ou executar qualquer conteudo.

Exemplo:

Usuario: skill-master, veja se existe alguma skill para revisar este deploy.
Cliente: chama skill_master_activation_check.
Cliente: se ativar, chama skill_master_recommend ou segue as recomendacoes retornadas.

Diagnostico importante:

• skill_master_list_sources mostra configPath, workspace e se workspaceRoots esta configurado.
• Se workspaceRoots estiver vazio, skills em .codex/skills do projeto nao serao catalogadas ate atualizar sources.json e reiniciar o processo MCP.

Atualizacao automatica via npm

Para instalacoes feitas por npm install -g, o caminho seguro de auto-update e executar skill-master-update fora do processo MCP.

Uso manual:

skill-master-update

Uso em agendamento Linux/macOS:

skill-master-update

Uso em agendamento Windows:

skill-master-update

Validacao sem aplicar update:

skill-master-update --dry-run

Regra operacional:

• nao atualizar dentro do processo skill-master-mcp em stdio
• atualizar antes de iniciar o cliente MCP ou em janela agendada
• reiniciar Codex, Claude, Gemini ou outro cliente MCP depois da atualizacao
• para desenvolvimento com clone, continuar usando o launcher por manifesto e git pull --ff-only

Arquivos principais

• Plano geral
• Pesquisa de alternativas de atualizacao
• Arquitetura de atualizacao automatica
• Rede segura de skills
• Operacao multi-computador
• Prompt tasks de execucao

Regra de independencia

O skill_master nao deve importar codigo, paths, tokens, configuracoes ou convencoes especificas do LinkBiz. Ele pode ler skills locais do computador do usuario, mas sempre como fonte configuravel e nao como acoplamento fixo.