@fprad0/skill-master-mcp 0.0.12 → 1.0.0

package/docs/architecture/REDE_SEGURA_DE_SKILLS.md

@@ -1,148 +1,148 @@
-# Rede Segura de Skills do Skill Master
-
-## Objetivo
-
-Permitir que o `skill_master` fique cada vez melhor em varios computadores sem transformar o MCP em um coletor automatico de arquivos privados ou em um canal de execucao de conteudo desconhecido.
-
-O modelo correto e:
-
-1. cada instalacao aprende com as skills locais da propria maquina;
-2. a instalacao compara essas skills com um indice aprovado;
-3. o usuario gera um pacote local de contribuicao;
-4. o pacote e revisado antes de qualquer compartilhamento;
-5. somente skills aprovadas por revisao humana entram no indice compartilhado.
-
-## Principios de seguranca
-
-- Nenhuma skill desconhecida e executada automaticamente.
-- Nenhum arquivo e enviado automaticamente.
-- Caminhos absolutos da maquina nao entram no pacote de contribuicao.
-- O corpo completo da skill nao entra no pacote por padrao.
-- Previews de corpo, quando ativados, sao limitados e passam por redacao basica de segredos.
-- Skills vindas da web continuam marcadas como nao confiaveis.
-- Workspace e plugin entram em contribuicao apenas por opt-in.
-- Candidatos com sinais de risco exigem revisao humana de seguranca.
-
-## Arquitetura
-
-```mermaid
-flowchart TD
-  A["Notebook com skill_master"] --> B["Atualiza catalogo local"]
-  B --> C["Compara com network/approved-skills.json"]
-  C --> D["Gera contribution draft local"]
-  D --> E["Revisa duplicidade, privacidade e risco"]
-  E --> F{"Aprovado por humano?"}
-  F -- "Nao" --> G["Descarta ou corrige"]
-  F -- "Sim" --> H["Atualiza indice aprovado via PR/release"]
-  H --> I["Outros notebooks recebem pelo update normal"]
-```
-
-## Ferramentas MCP
-
-### `skill_master_refresh_catalog`
-
-Atualiza o catalogo local a partir das fontes configuradas em `sources.json`.
-
-Use quando:
-
-- instalar o MCP em uma maquina nova;
-- adicionar novas skills locais;
-- mudar fontes em `sources.json`;
-- preparar uma contribuicao.
-
-### `skill_master_prepare_skill_contribution`
-
-Cria um pacote JSON local com skills novas que ainda nao estao no indice aprovado.
-
-Parametros importantes:
-
-- `refresh_first`: atualiza o catalogo antes de preparar o pacote.
-- `include_body_preview`: inclui um preview curto e redigido do conteudo. Padrao: `false`.
-- `include_workspace`: permite incluir skills de workspace. Padrao: `false`.
-- `include_plugin`: permite incluir skills de plugin. Padrao: `false`.
-- `machine_label`: rotulo opcional da maquina, sem dados sensiveis.
-- `max_candidates`: limite de candidatos.
-- `output_dir`: pasta local para salvar o JSON.
-
-Resultado:
-
-- cria um arquivo `skill-contribution-*.json`;
-- informa quantos candidatos foram encontrados;
-- informa quantos foram ignorados por nome/hash conhecido;
-- informa quantos possuem flags de risco;
-- nao faz upload.
-
-### `skill_master_review_skill_contribution`
-
-Revisa um pacote JSON criado pela ferramenta anterior.
-
-Ela verifica:
-
-- schema do arquivo;
-- candidatos duplicados por hash;
-- candidatos duplicados por nome normalizado;
-- inclusao indevida de caminhos completos;
-- inclusao indevida de corpos completos;
-- flags de risco como comandos destrutivos, downloads pipeados para shell ou segredos aparentes.
-
-Resultado esperado:
-
-- `safe-to-review`: pode seguir para revisao humana comum;
-- `needs-human-security-review`: requer revisao de seguranca;
-- `invalid`: arquivo invalido ou schema nao suportado.
-
-## Indice aprovado
-
-Arquivo:
-
-```text
-network/approved-skills.json
-```
-
-Formato:
-
-```json
-{
-  "generatedAt": "2026-06-25T00:00:00.000Z",
-  "policyVersion": "safe-skill-network-v1",
-  "skills": [
-    {
-      "name": "example-skill",
-      "description": "Descricao aprovada.",
-      "contentHash": "sha256...",
-      "sourceKind": "network",
-      "approvedAt": "2026-06-25T00:00:00.000Z",
-      "approvedBy": "reviewer"
-    }
-  ]
-}
-```
-
-O indice nao precisa armazenar o corpo inteiro da skill. Ele funciona como uma lista de conhecimento aprovado para deduplicacao e governanca.
-
-## Fluxo recomendado
-
-1. No notebook novo, rode `skill_master_refresh_catalog`.
-2. Rode `skill_master_prepare_skill_contribution`.
-3. Revise o JSON local gerado.
-4. Rode `skill_master_review_skill_contribution` no arquivo gerado.
-5. Se estiver seguro, abra um PR atualizando o indice aprovado ou adicionando a skill em um pacote de distribuicao.
-6. Publique uma release/canal `stable`.
-7. Outros notebooks recebem a melhoria pelo fluxo normal de update.
-
-## O que nao fazer
-
-- Nao sincronizar skills desconhecidas automaticamente entre maquinas.
-- Nao copiar arquivos inteiros de skills sem revisao.
-- Nao aceitar scripts de instalacao embutidos em skills sem analise.
-- Nao transformar uma skill local em trusted apenas porque ela existe em uma maquina.
-- Nao publicar contribuicoes com caminhos absolutos do computador.
-- Nao publicar segredos, tokens, URLs privadas ou dados internos de clientes.
-
-## Proximas evolucoes
-
-- Adicionar aprovacao por assinatura de pacote.
-- Criar workflow de GitHub para validar `skill-contribution-*.json`.
-- Criar comando para promover candidatos aprovados ao indice.
-- Criar canal `beta` para skills experimentais.
-- Adicionar score de risco mais granular.
+# Rede Segura de Skills do Skill Master
+
+## Objetivo
+
+Permitir que o `skill_master` fique cada vez melhor em varios computadores sem transformar o MCP em um coletor automatico de arquivos privados ou em um canal de execucao de conteudo desconhecido.
+
+O modelo correto e:
+
+1. cada instalacao aprende com as skills locais da propria maquina;
+2. a instalacao compara essas skills com um indice aprovado;
+3. o usuario gera um pacote local de contribuicao;
+4. o pacote e revisado antes de qualquer compartilhamento;
+5. somente skills aprovadas por revisao humana entram no indice compartilhado.
+
+## Principios de seguranca
+
+- Nenhuma skill desconhecida e executada automaticamente.
+- Nenhum arquivo e enviado automaticamente.
+- Caminhos absolutos da maquina nao entram no pacote de contribuicao.
+- O corpo completo da skill nao entra no pacote por padrao.
+- Previews de corpo, quando ativados, sao limitados e passam por redacao basica de segredos.
+- Skills vindas da web continuam marcadas como nao confiaveis.
+- Workspace e plugin entram em contribuicao apenas por opt-in.
+- Candidatos com sinais de risco exigem revisao humana de seguranca.
+
+## Arquitetura
+
+```mermaid
+flowchart TD
+  A["Notebook com skill_master"] --> B["Atualiza catalogo local"]
+  B --> C["Compara com network/approved-skills.json"]
+  C --> D["Gera contribution draft local"]
+  D --> E["Revisa duplicidade, privacidade e risco"]
+  E --> F{"Aprovado por humano?"}
+  F -- "Nao" --> G["Descarta ou corrige"]
+  F -- "Sim" --> H["Atualiza indice aprovado via PR/release"]
+  H --> I["Outros notebooks recebem pelo update normal"]
+```
+
+## Ferramentas MCP
+
+### `skill_master_refresh_catalog`
+
+Atualiza o catalogo local a partir das fontes configuradas em `sources.json`.
+
+Use quando:
+
+- instalar o MCP em uma maquina nova;
+- adicionar novas skills locais;
+- mudar fontes em `sources.json`;
+- preparar uma contribuicao.
+
+### `skill_master_prepare_skill_contribution`
+
+Cria um pacote JSON local com skills novas que ainda nao estao no indice aprovado.
+
+Parametros importantes:
+
+- `refresh_first`: atualiza o catalogo antes de preparar o pacote.
+- `include_body_preview`: inclui um preview curto e redigido do conteudo. Padrao: `false`.
+- `include_workspace`: permite incluir skills de workspace. Padrao: `false`.
+- `include_plugin`: permite incluir skills de plugin. Padrao: `false`.
+- `machine_label`: rotulo opcional da maquina, sem dados sensiveis.
+- `max_candidates`: limite de candidatos.
+- `output_dir`: pasta local para salvar o JSON.
+
+Resultado:
+
+- cria um arquivo `skill-contribution-*.json`;
+- informa quantos candidatos foram encontrados;
+- informa quantos foram ignorados por nome/hash conhecido;
+- informa quantos possuem flags de risco;
+- nao faz upload.
+
+### `skill_master_review_skill_contribution`
+
+Revisa um pacote JSON criado pela ferramenta anterior.
+
+Ela verifica:
+
+- schema do arquivo;
+- candidatos duplicados por hash;
+- candidatos duplicados por nome normalizado;
+- inclusao indevida de caminhos completos;
+- inclusao indevida de corpos completos;
+- flags de risco como comandos destrutivos, downloads pipeados para shell ou segredos aparentes.
+
+Resultado esperado:
+
+- `safe-to-review`: pode seguir para revisao humana comum;
+- `needs-human-security-review`: requer revisao de seguranca;
+- `invalid`: arquivo invalido ou schema nao suportado.
+
+## Indice aprovado
+
+Arquivo:
+
+```text
+network/approved-skills.json
+```
+
+Formato:
+
+```json
+{
+  "generatedAt": "2026-06-25T00:00:00.000Z",
+  "policyVersion": "safe-skill-network-v1",
+  "skills": [
+    {
+      "name": "example-skill",
+      "description": "Descricao aprovada.",
+      "contentHash": "sha256...",
+      "sourceKind": "network",
+      "approvedAt": "2026-06-25T00:00:00.000Z",
+      "approvedBy": "reviewer"
+    }
+  ]
+}
+```
+
+O indice nao precisa armazenar o corpo inteiro da skill. Ele funciona como uma lista de conhecimento aprovado para deduplicacao e governanca.
+
+## Fluxo recomendado
+
+1. No notebook novo, rode `skill_master_refresh_catalog`.
+2. Rode `skill_master_prepare_skill_contribution`.
+3. Revise o JSON local gerado.
+4. Rode `skill_master_review_skill_contribution` no arquivo gerado.
+5. Se estiver seguro, abra um PR atualizando o indice aprovado ou adicionando a skill em um pacote de distribuicao.
+6. Publique uma release/canal `stable`.
+7. Outros notebooks recebem a melhoria pelo fluxo normal de update.
+
+## O que nao fazer
+
+- Nao sincronizar skills desconhecidas automaticamente entre maquinas.
+- Nao copiar arquivos inteiros de skills sem revisao.
+- Nao aceitar scripts de instalacao embutidos em skills sem analise.
+- Nao transformar uma skill local em trusted apenas porque ela existe em uma maquina.
+- Nao publicar contribuicoes com caminhos absolutos do computador.
+- Nao publicar segredos, tokens, URLs privadas ou dados internos de clientes.
+
+## Proximas evolucoes
+
+- Adicionar aprovacao por assinatura de pacote.
+- Criar workflow de GitHub para validar `skill-contribution-*.json`.
+- Criar comando para promover candidatos aprovados ao indice.
+- Criar canal `beta` para skills experimentais.
+- Adicionar score de risco mais granular.