Roadmap/skill-discovery-algorithm.md

Algoritmo de descoberta e compartilhamento de skills

Este documento ignora transporte, protocolo e rede social. A pergunta aqui e:

Como deveria funcionar um bom sistema de descoberta, recomendacao, compartilhamento e confianca para skills?

A resposta curta: um bom sistema nao e uma lista ordenada por popularidade. Ele e um pipeline de decisao que combina intencao do usuario, compatibilidade tecnica, qualidade observada, risco, confianca social/organizacional e politica local.

1. O que o sistema precisa resolver

Um usuario nao quer “achar skills”. Ele quer:

Entao discovery de skills tem quatro problemas separados:

  1. Recuperacao: achar skills candidatas para uma intencao.
  2. Ranking: ordenar candidatas pelo melhor tradeoff entre utilidade e confianca.
  3. Admissao: decidir se uma skill pode ser instalada/executada naquele ambiente.
  4. Distribuicao de confianca: permitir que pessoas, times e comunidades compartilhem curadoria sem transformar isso em “instale porque e popular”.

2. Objeto central: o manifesto da skill

Toda skill precisa ter um manifesto estruturado. Sem isso, discovery vira busca textual fragil.

Campos essenciais:

O manifesto nao concede permissao. Ele apenas declara o que a skill pede. A plataforma decide se aceita.

3. Pipeline basico

O algoritmo pode ser pensado assim:

query/contexto do usuario
  -> entender intencao
  -> descobrir fontes provaveis
  -> consultar fontes externas
  -> resolver candidatos encontrados
  -> filtrar compatibilidade
  -> calcular utilidade
  -> calcular confianca
  -> calcular risco
  -> aplicar politica local
  -> ranquear
  -> explicar recomendacao
  -> instalar/executar com sandbox
  -> coletar feedback local

Esse pipeline e mais importante do que qualquer tecnologia de registry.

4. Descoberta federada: onde procurar

O usuario nao esta olhando uma lista local de skills. Na pratica, a plataforma precisa descobrir skills em fontes distribuidas, mais parecido com busca na web do que com uma app store fechada.

Fontes possiveis:

O algoritmo nao deve assumir uma fonte canonica. Ele deve tratar discovery como um problema de coleta, normalizacao e verificacao de candidatos.

Para cada fonte, o sistema precisa de um adaptador:

Depois da coleta, cada candidato precisa ser resolvido para algo verificavel:

  1. validar schema do manifesto
  2. normalizar categorias, runtimes e capabilities
  3. calcular hashes dos artefatos
  4. extrair texto indexavel
  5. rodar checks estaticos basicos
  6. atribuir uma classe inicial de risco
  7. registrar origem e versao

Skills sem manifesto bom podem existir, mas devem perder ranking e exigir mais cautela.

5. Geracao de candidatos

Discovery bom nao depende de uma lista local. Ele mistura fontes externas, curadorias e contexto local para montar um conjunto pequeno de candidatos plausiveis.

5.1 Planejamento da busca

Antes de sair procurando, a plataforma transforma o pedido do usuario em uma estrategia:

Exemplo:

Pedido: "preciso converter PDF escaneado em Markdown"
Busca externa: "codex skill pdf markdown ocr", "agent skill pdf ocr markdown"
Categorias: documents, pdf, ocr, markdown
Capabilities maximas: read-file, write-workspace, optional-network-read
Fontes preferidas: skills ja usadas, listas confiaveis, repositorios conhecidos

5.2 Consulta de fontes

Cada fonte devolve evidencias, nao necessariamente uma skill pronta:

O sistema deve coletar mais candidatos do que pretende mostrar. Depois ele deduplica, resolve versoes e descarta o que nao passa no minimo de qualidade.

5.3 Cache local e matching por contexto

O sistema tambem deve olhar para o ambiente atual:

Exemplo: se o workspace tem .pptx, skills de apresentacao sobem. Se tem pyproject.toml, skills Python sobem. Se ha um PR aberto, skills GitHub sobem.

O cache local serve para acelerar e personalizar, mas nao e a fonte de verdade. Ele guarda:

5.4 Curadoria e descoberta social

Listas humanas sao essenciais:

Curadoria nao deve substituir ranking. Ela deve entrar como sinal ponderado.

5.5 Deduplicacao e resolucao

Fontes diferentes podem apontar para a mesma skill. Antes de ranquear, o sistema precisa agrupar candidatos por identidade:

Depois, escolhe a versao mais apropriada pela politica local: estavel, assinada, auditada, recente o suficiente e compativel com o runtime.

6. Filtro de compatibilidade

Antes de ranquear, descarte ou rebaixe skills que nao podem funcionar.

Verificacoes tipicas:

Uma skill perfeita para a tarefa, mas impossivel de executar, nao deve aparecer como recomendacao principal.

7. Score de utilidade

Utilidade responde: “essa skill provavelmente ajuda neste caso?”

Sinais bons:

Um score simples:

utility =
  0.25 * task_fit +
  0.20 * manifest_fit +
  0.20 * context_match +
  0.15 * historical_success +
  0.10 * documentation_quality +
  0.10 * maintenance_health

Os pesos devem ser ajustaveis. Para uma primeira versao, pesos manuais sao suficientes.

8. Score de confianca

Confianca responde: “quem esta dizendo que isso e bom, e por que eu deveria ligar?”

Sinais positivos:

Sinais negativos:

Confianca deve ser contextual. Uma pessoa pode confiar numa skill para ler Markdown, mas nao para enviar emails ou acessar secrets.

8.1 Web of trust e vouches

Web of trust nao e popularidade. O ponto nao e “muita gente gostou”; e “pessoas relevantes para mim estao colocando reputacao em jogo por esta skill”.

Sinais de web of trust:

Esses sinais devem ser ponderados por proximidade e contexto:

trust =
  direct_peer_vouches +
  followed_people_vouches +
  trusted_curator_vouches +
  organization_approval +
  auditor_attestations +
  local_success_history -
  trusted_negative_reports -
  suspicious_recommendation_patterns

Exemplo: uma skill de Nostr recomendada por tres pessoas que o usuario segue no Nostr pode subir bastante no ranking. Mas isso nao deve liberar automaticamente capabilities sensiveis. O vouch aumenta confianca; a politica local ainda decide o que pode executar.

Vouches tambem precisam ter escopo. “Usei e gostei” vale menos que:

Eu usei `github-pr-review-helper@2.1.0` em tres PRs.
Nao pediu secrets.
So leu comentarios e escreveu no workspace.
Funcionou no Codex.

9. Score de risco

Risco responde: “qual o tamanho do estrago se essa skill se comportar mal?”

Uma taxonomia pratica:

O risco base vem das capabilities declaradas. Depois ele e ajustado por comportamento observado e auditoria.

Risco deve medir blast radius, nao reputacao. Um publisher desconhecido nao torna automaticamente a skill mais destrutiva; ele reduz a confianca. Misturar os dois deixa o algoritmo confuso.

Exemplo de risco intrinseco:

risk =
  capability_risk +
  dependency_risk +
  artifact_uncertainty +
  behavior_anomaly

Depois, a decisao combina risco com confianca:

decision_pressure =
  intrinsic_risk -
  trust_mitigation

O ponto importante: risco alto nao significa “nunca instalar”. Significa exigir mais evidencia, mais sandbox e mais confirmacao. Web of trust ajuda a reduzir incerteza, mas nao apaga o risco operacional de uma skill com shell, rede de escrita ou acesso a secrets.

10. Score final

Ranking nao deve ser “maior utilidade vence”. Deve ser utilidade ponderada por confianca e penalizada por risco.

Uma formula inicial:

final_score =
  utility_score
  * trust_multiplier
  * compatibility_multiplier
  - risk_penalty
  - policy_penalty

Onde:

O trust_multiplier deve incluir web of trust: peers diretos, pessoas seguidas, curadores, organizacoes e auditores. O peso de um vouch deve cair com distancia social e subir quando vem acompanhado de contexto verificavel, versao exata e ausencia de conflito de interesse.

Para casos sensiveis, use thresholds:

se risk >= R4 e trust < threshold:
  nao recomendar instalacao direta
  mostrar como "requer revisao"

se risk >= R4 e trust >= threshold:
  permitir recomendacao, mas manter sandbox e confirmacao explicita

11. Politica local

Politica local e a parte que impede o sistema de virar uma democracia de popularidade.

Exemplos:

Politica deve ser declarativa e auditavel.

12. Explicabilidade

Toda recomendacao deveria conseguir responder:

Exemplo de explicacao boa:

Recomendada porque foi encontrada em uma fonte confiavel para tarefas de PDF, o manifesto declara entrada PDF e saida Markdown, suporta este runtime, ja foi usada 12 vezes localmente com sucesso e pede apenas leitura do arquivo e escrita no workspace.

Exemplo ruim:

Popular no catalogo.

Popularidade sozinha e um sinal fraco.

13. Compartilhamento

Compartilhar skill nao deveria significar “manda um zip e confia”.

Modelos melhores:

O compartilhamento ideal inclui:

Exemplo:

Usei `markdown-converter@1.4.2` para converter PDFs escaneados.
Funcionou bem com contratos longos.
Capabilities: read-file, write-workspace, optional-ocr.
Nao requer rede.

14. Atualizacoes

Atualizacao e uma das maiores fontes de risco.

O sistema deve comparar versoes:

Regras praticas:

15. Feedback loop

O sistema melhora quando aprende com uso real, mas privacidade precisa ser default.

Feedback local:

Feedback compartilhavel, se opt-in:

O historico local deve pesar muito. Se uma skill funciona repetidamente para Breno, isso importa mais do que popularidade global.

16. Anti-gaming

Qualquer sistema de ranking sera atacado.

Defesas basicas:

O objetivo nao e impedir todo ataque. E evitar que ataques baratos funcionem.

17. UX recomendada

Uma boa interface teria tres modos:

17.1 Sugestao durante a tarefa

Quando o usuario pede algo, a plataforma sugere:

Skill sugerida: markdown-converter
Motivo: esta tarefa envolve PDF -> Markdown.
Risco: baixo, leitura de arquivo e escrita no workspace.
Acao: usar uma vez / instalar / ver detalhes

17.2 Busca federada

Busca que consulta fontes externas e permite filtros:

17.3 Tela de decisao

Antes de instalar/executar:

18. MVP recomendado

Eu faria o MVP assim:

  1. Definir manifesto local de skill.
  2. Criar adaptadores de descoberta para web, repositorios, listas curadas e cache local.
  3. Implementar resolucao de candidatos para manifestos versionados e hasheados.
  4. Implementar capabilities e classes de risco.
  5. Implementar score simples: utilidade, confianca, risco.
  6. Permitir listas curadas locais: favoritos, aprovadas, bloqueadas.
  7. Mostrar explicacao curta para cada recomendacao.
  8. Registrar feedback local de uso.
  9. Travar instalacao/execucao por politica local.

Nao precisa comecar com marketplace ou reputacao global. Primeiro o sistema precisa descobrir candidatos em fontes reais, resolver manifestos corretamente e recomendar bem para uma pessoa em uma maquina.

19. Pseudocodigo

def recommend_skills(query, workspace, user_profile, policy):
    intent = parse_intent(query, workspace)
    search_plan = plan_discovery(intent, workspace, user_profile, policy)

    evidence = collect_from_sources(
        web_search(search_plan),
        repo_scan(search_plan),
        curated_lists(search_plan, user_profile),
        protocol_events(search_plan),
        local_cache(search_plan, user_profile),
    )

    candidates = resolve_candidates(evidence)
    candidates = deduplicate(candidates)

    scored = []

    for skill in candidates:
        compatibility = check_compatibility(skill, workspace)
        if compatibility.blocked:
            continue

        utility = score_utility(skill, intent, workspace)
        trust_signals = collect_trust_signals(skill, evidence, user_profile)
        trust = score_trust(skill, trust_signals, user_profile)
        risk = score_intrinsic_risk(skill)
        policy_result = evaluate_policy(skill, risk, trust, policy)

        if policy_result.blocked:
            continue

        final = (
            utility
            * trust.multiplier
            * compatibility.multiplier
            - risk.penalty
            - policy_result.penalty
        )

        scored.append({
            "skill": skill,
            "score": final,
            "utility": utility,
            "trust": trust,
            "risk": risk,
            "explanation": explain(skill, utility, trust, risk, policy_result),
        })

    return sorted(scored, key=lambda item: item["score"], reverse=True)

20. Opiniao direta

O melhor sistema de descoberta de skills parece mais com um package manager com ranking contextual e policy engine do que com uma app store.

App store otimiza por popularidade, reviews e conversao. Skills precisam otimizar por:

Minha regra de ouro:

Recomende pela utilidade, permita pela politica, limite pelo sandbox e aprenda com o uso local.