Skill Auditor — Depreciação de Capacidade e Avaliação de Adequação do Agente
Visão Geral
Uma skill é um ativo depreciável. Novas versões de modelo são lançadas a cada poucos meses. Uma skill que funcionava no trimestre passado pode regredir silenciosamente — formato de saída incorreto, chamadas de ferramenta quebradas, acionadores perdidos — e ninguém informa ao usuário que seu agente ficou mais burro.
Esta skill é a metodologia de avaliação. Ela responde a três perguntas:
- A skill está degradando? — regressão de capacidade entre versões de modelo.
- Uma nova skill é realmente boa? — eficácia versus custo.
- A skill se adapta a ESTE usuário? — precisão do acionador + ambiente + estilo.
Ela fornece cinco pontos de entrada executáveis:
scripts/console.py— o console residente (camada de dados): mantémregistry.<host>.jsonpor host, detecta mudanças de versão de modelo (bump/check) e emite o painel de recomendar/eliminar. ConsulteUSAGE.mdpara o conjunto completo de comandos.scripts/regress.py— com base nos resultados de replay do conjunto dourado, calcula a matriz de taxa de aprovação, sinaliza degradação (limiar + direção) e sinalizaFINGERPRINT-DRIFTquando um ativo foi editado.scripts/baseline.py— estrutura uma lista de verificação de replay e mescla os vereditos registrados embaseline-results.json(por ativo;--replacepara substituição completa). Casos dourados em rascunho são ignorados, a menos que--allow-draftseja usado.scripts/fingerprint.py— CLI de relatório independente; um invólucro leve sobre o mesmo código de hash usado porscan. Ele escreve apenasfingerprint-report.*; não escreve o registro.scripts/install.py— instala esta skill em todos os hosts de agente na máquina (~/.workbuddy-ai/skills,~/.claude/skills,~/.agents/skills,~/.dsh/skills,~/.codex/skills). Verifica após a instalação; nunca deixa um diretório vazio; nunca copia dados pessoais.
Princípio fundamental: Não há medição sem uma linha de base. Degradação = queda significativa na taxa de aprovação sob um fingerprint inalterado — nunca "parece mais burro".
Arquitetura Multi-Host (skills vs plugins)
Um mecanismo central, adaptadores por host. A mesma lógica de fingerprint / linha de base / regressão / recomendação / sugestão de necessidade é executada em todos os lugares; um adaptador só sabe onde os ativos residem e como ler seu manifesto.
| host | tipo | raiz padrão | manifesto |
|---|---|---|---|
| workbuddy | skill | raiz de skills que contém esta skill | SKILL.md |
| claude-code | skill | ~/.claude/skills | SKILL.md |
| deepseek | 插件 | ~/.dsh/profiles/desktop (lê deps do package.json) | package.json / plugin.json |
| genérico | ativo | passar --root | plugin.json / manifest.json / SKILL.md / package.json |
- Cada host mantém seu próprio registro:
registry.<host>.json— sem sobrescrita entre hosts. - Resultados de linha de base + conjuntos dourados são compartilhados, indexados pelo nome do ativo.
- Execute com
--host <nome> --root <caminho>; adicione hosts personalizados emhosts.json. console.py hostsmostra cada perfil, sua raiz resolvida e a contagem de ativos detectados.
Assim, no WorkBuddy você avalia skills; no harness DeepSeek você avalia plugins — mesmos comandos, adaptador diferente. Adicionar um novo host é uma entrada em hosts.json (tipo + raiz + nomes de manifesto), sem alteração de código.
Quando Usar
- Antes de implantar uma nova skill ou plugin ("criar uma skill, seguindo o fluxo de avaliação").
- Após um aumento de versão de modelo, para verificar se as skills existentes regrediram.
- Quando uma skill "parece estranha" — confirme com dados, não com intuição.
- Ao decidir se deve manter, reescrever ou aposentar uma skill.
- Ao recomendar uma skill ou plugin a um usuário (adequação + evidências).
Quando NÃO usar: tarefas pontuais sem skill reutilizável; documentos puramente narrativos.
Conceito Central: O Fingerprint de Versão
O fingerprint é a linha da matriz de depreciação.
fingerprint = hash(conteúdo dos arquivos da superfície de capacidade + caminho relativo) # calibre v2-superfície-de-capacidade
O que conta como superfície de capacidade (os arquivos cuja alteração realmente muda o comportamento):
- incluídos:
SKILL.md,scripts/*,lib/*,dist/*,package.json,plugin.json,cordis.patch.yml, modelos - excluídos:
README*,CHANGELOG*,LICENSE*, imagens/áudio/fontes,*.map, arquivos de bloqueio,node_modules/,test*/,docs/
Por que excluir: uma edição de README não altera a capacidade, mas hasheá-lo faz o fingerprint se mover e produz um FINGERPRINT-DRIFT falso ("o ativo foi editado") quando nada funcional mudou. Plugins pioram isso — um plugin instalado pode carregar 16 MB de saída empacotada mais um README de 57 KB.
Regras:
- Fingerprint inalterado ⇒ a linha persiste; uma queda na taxa de aprovação é regressão do modelo.
- Fingerprint alterado ⇒ a mudança é responsabilidade da própria skill, não do modelo. Linhas antigas e novas coexistem, portanto edições de skill nunca são atribuídas erroneamente à deriva do modelo.
Execute python scripts/console.py scan para calcular fingerprints e armazená-los no registro. fingerprint.py é um invólucro de relatório independente; ele não toca no registro.
Superfície de Capacidade (por que plugins precisam de um segundo eixo)
O fingerprint diz "os arquivos mudaram?". Ele não pode dizer "ainda oferece a mesma coisa?".
scan também registra uma superfície de capacidade por ativo e a compara com a varredura anterior:
| Tipo de ativo | O que a superfície registra |
|---|---|
| plugin | patch (dsh.bundle.patch), main/module, bin, exports, deps, skills, mcp, hooks, insert (linhas cordis), scripts |
| skill | tools (contagem de ferramentas permitidas), scripts |
Quando muda, scan o imprime explicitamente:
[caps] 1 ativo teve sua superfície de capacidade alterada (isto é "o que ele oferece externamente mudou", não relacionado à taxa de aprovação):
plug-a +bin
Por que isso é importante para plugins: um plugin degrada ao não registrar suas ferramentas / 404 em suas rotas / não executar seus hooks — não por "responder pior". Um conjunto dourado de prompts mede a coisa errada para um plugin. O diff de superfície captura "v1.1.0 removeu um ponto de entrada" sem precisar iniciar o host.
Limite conhecido (não tente escondê-lo): a superfície é a capacidade declarada, não a capacidade observada. Para um plugin cujo manifesto mente (declara um patch que falha ao carregar), isso não pode ser detectado.
Evidência de Runtime (o terceiro eixo, e o que ela não pode fazer)
Existem duas coisas muito diferentes chamadas "sonda de runtime". Não as confunda:
| Sonda Ativa | Evidência Passiva — implementada | |
|---|---|---|
| o que faz | inicia o host, pergunta "quais ferramentas você realmente registrou" | lê o log que o host já escreve |
| custo | perfil desktop do DSH é exclusivo para Electron — dsh --profile desktop --dump-config é recusado; sem entrada headless → engenharia reversa de IPC ou manipular a UI | uma leitura de arquivo, ~10 ms |
| detecta | tudo, incluindo um plugin cujo manifesto mente | qualquer coisa que o plugin registrou |
| status | não construída | console.py probe / skill_audit_probe |
probe lê ~/.dsh/logs/*.log (configurável por host via "logs" em hosts.json), analisa
<iso> [nível] [fonte] mensagem, atribui linhas cuja fonte é igual ao nome de um ativo instalado e
sinaliza linhas que correspondem a vocabulário de falha (fail|error|ENOENT|unavailable|timeout|…).
Exemplo real, nesta máquina:
@wxg-prc-cpg/browser-skill-dsh-plugin 2 indícios de falha
falha de sonda bsk (spawn bsk ENOENT); ferramentas do navegador relatarão orientação de instalação…
Arquivos presentes, manifesto válido, caps=4 — todas as verificações estáticas passam. O plugin está carregado e suas ferramentas
estão registradas, mas elas não podem funcionar: o CLI bsk que ele chama não está no PATH. Nenhuma quantidade de
hash de arquivos encontra isso.
Pontos cegos (declare-os, nunca os esconda): um plugin que não registra nada é invisível; a rotação de logs
apaga falhas antigas; um plugin que ninguém usou não tem evidência; falhas de nível info são detectadas por correspondência
palavra-chave, portanto tanto erros quanto falsos positivos são possíveis. Ausência de evidência não é evidência de
saúde — probe imprime essa frase em vez de uma marca de verificação verde.
Implementado vs Apenas Metodologia (não confunda esta linha)
A metodologia abaixo é mais ampla que o código. Os usuários devem saber qual metade estão segurando:
| Área | Status |
|---|---|
Fingerprint sobre a superfície de capacidade, scan/status, diff de capacidade | implementado |
| Estrutura dourada + ingestão de linha de base (mesclagem por ativo, proteção de rascunho) | implementado (baseline.py) |
Matriz de taxa de aprovação, limiar de ≥20pp + direção, FINGERPRINT-DRIFT | implementado (regress.py) |
Detecção de mudança de modelo (bump/check), carimbos por host | implementado — mas a fonte do evento é manual; um check agendado permanece verde até que alguém execute bump |
| Painel de recomendar/eliminar, sugestão de necessidade, rascunhos minerados do histórico | implementado (heurístico; sugestões não são evidências) |
| Evidência de runtime a partir de logs do host | implementado (passivo; apenas o que o plugin registrou) |
| Ablação, taxa de adoção em modo sombra, valor líquido / telemetria de tokens | apenas metodologia — sem código |
| Precisão/revocação do acionador, reconciliação de ambiente, linha de base de estilo | apenas metodologia — sem código |
| Replays K≥3, validação cruzada com LLM como juiz | não implementado; os vereditos atuais são autoavaliação K=1 |
Coluna de risco | proxy de superfície de manutenção — não valor |
Se uma afirmação neste arquivo não puder ser rastreada até uma linha marcada como "implementado", trate-a como um conselho para o humano que realiza a auditoria, não como algo que a ferramenta fará por você.
Julgamento 1 — Degradação de Capacidade
Quatro etapas:
- Construa o conjunto dourado a partir do histórico, não manualmente. Minere sessões passadas: o usuário adotou sem resistência → replay positivo; o usuário resistiu / pediu reescrita → negativo. O replay É regressão. O próprio histórico de uso do usuário é o corpus — nenhum conjunto de teste inventado.
- Execute ambos os modelos no mesmo conjunto dourado, K≥3 (casos de pontuação com LLM como juiz: K≥5, porque o juiz é ruidoso). Registre a taxa de aprovação por (fingerprint, versão do modelo).
- Regra de decisão: queda ≥20pp E direcionalmente consistente → reporte degradação; abaixo do limiar → "observação de volatilidade". Isso transforma "esta saída está estranha" em um critério reproduzível.
- Atribua, não apenas sinalize. Inspecione artefatos intermediários:
- Erro de chamada de ferramenta / formato alterado → corrija a descrição da ferramenta.
- Estrutura de saída correta, conteúdo errado → reescreva as instruções.
- Deveria ter acionado, mas não acionou → corrija a descrição do acionador.
- Todos os intermediários corretos, apenas o final errado → regressão interna do modelo; marque a skill como "dependente de modelo único", aguarde a correção do modelo.
A linha "7 degradados, 2 recomendados para reescrita" é o subconjunto atribuível da saída da etapa 4 — é isso que torna o relatório acionável.
Julgamento 2 — Uma Nova Skill é Boa?
Divida em dois eixos mensuráveis: eficácia (melhores resultados) e economia (menor custo).
- Ablação pré-implantação. Mesmo lote de tarefas, dois braços: A sem skill, B com skill. Registre taxa de sucesso, contagem de correções humanas, custo de tokens.
benefício líquido = aumento_na_taxa_de_sucesso × frequência_da_tarefa − custo_marginalUma skill que aumenta o sucesso em 30% mas é acionada 3×/ano com +50k tokens cada é um passivo, não um ativo. - Modo sombra pós-implantação. Nova skill executa em silêncio: produz sugestões, mas não executa automaticamente; registre "o que teria acontecido". Observe a taxa de adoção (aceitas vs. substituídas). A taxa de adoção é o juiz final de "bom", mais honesta do que qualquer métrica offline. Limite: skills de operações de escrita (excluir arquivo, enviar e-mail) só podem simular/anotar em modo sombra, nunca realmente executar.
- Cartão de valor líquido. Um painel por skill: contagem de chamadas, taxa de sucesso, taxa de adoção, tokens médios, benefício líquido acumulado. 90 dias líquido negativo → sugerir reescrita ou aposentadoria. Este é o lado do consumidor na tabela de depreciação.
Julgamento 3 — Ela se Adapta a ESTE Usuário?
"Se adapta a você" = acionadores precisos + suposições válidas + estilo correspondente. Tudo automatizável:
- Precisão do acionador (mais afeta a sensação, mais ignorado). Amostre positivos do histórico (deveria acionar) e negativos (semelhantes, não deveriam — "corrigir este bug" vs. "explique o que é um bug"). Replay → precisão/revocação. Baixa precisão = irritante (aciona demais); baixa revocação = instalação desperdiçada. Primeiro, rotule manualmente 10–20, depois semiautomático, custo zero de LLM.
- Reconciliação de ambiente (instalado ≠ executa). Metadados da skill declaram dependências: quais ferramentas / MCP / permissões / hábitos de caminho / idioma, além de suposições implícitas de capacidade do modelo (contexto longo, execução de código, multimodal). Reconcilie com o ambiente real do usuário; faltando → bandeira vermelha. "Assume macOS", "saída em japonês", "precisa de contexto de 200k" — suposições invisíveis são a razão #1 para uma skill não ser usada. Isso também realimenta o Julgamento 1: uma suposição de capacidade falha = degradação silenciosa.
- Linha de base de estilo (menor peso). Use a saída histórica do usuário + USER.md como referência; LLM como juiz compara formato, idioma, verbosidade. Usado apenas para desempatar skills com pontuações iguais.
Fluxo de Trabalho Incorporado (para "criar uma nova skill")
Quando o usuário pedir para criar uma skill, execute o protocolo inline antes de entregar:
- Reconciliação de ambiente — o ambiente do usuário satisfaz as dependências declaradas + suposições de capacidade da skill?
- Replay do acionador — reproduza 10–20 casos amostrados; reporte precisão/revocação.
- Ablação — em um pequeno lote de tarefas, meça o aumento vs. custo.
- Iniciar monitoramento — em caso de aprovação, registre fingerprint + conjunto dourado; o console residente reexecuta em cada aumento de modelo.
Sugestão Baseada em Necessidade (quando nenhuma skill corresponde)
Este é o comportamento de "prateleira vazia": um usuário (especialmente com zero skills/plugins) pergunta por algo que nenhuma skill instalada cobre. Não diga apenas "não consigo" — mostre a lacuna e ofereça-se para preenchê-la.
- Detecte a necessidade a partir da conversa: tipo de tarefa + domínio (ex.: "relatório financeiro trimestral" → finanças/análise; "remover o tom de IA" → humanizador; "criar um painel" → frontend/gráfico).
- Verifique o registro primeiro —
python scripts/console.py suggest --need "<necessidade>". Ele retorna:✓ Você já tem uma skill/plugin disponível: <nome>→ use-o, não instale nada; ou💡 Sugestão de novo: [install:<slug>] <título>→ sem cobertura, recomende a categoria.
- Se não coberto, pesquise no marketplace por candidatos reais (skills/plugins/experts) e apresente um cartão com evidências: o que faz, por que se adapta a esta necessidade, fonte. Nunca instale automaticamente — o usuário escolhe.
- Em caso de …