Skill Auditor — Depreciação de Capacidade e Avaliação de Adequação do Agente
Visão Geral
Uma skill é um ativo em depreciação. 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 errado, chamadas de ferramentas quebradas, gatilhos 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:
- Uma skill está degradando? — regressão de capacidade entre versões de modelo.
- Uma nova skill é realmente boa? — eficácia vs custo.
- Uma skill se adapta a ESTE usuário? — precisão de gatilho + 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 alterações na versão do modelo (bump/check) e emite o painel de recomendar/eliminar. ConsulteUSAGE.mdpara o conjunto completo de comandos.scripts/regress.py— dados os resultados de reprodução do golden set, calcula a matriz de taxa de aprovação, sinaliza degradação (limiar + direção) e sinalizaFINGERPRINT-DRIFTquando um ativo foi editado em vez disso.scripts/baseline.py— cria uma lista de verificação de reprodução e mescla os vereditos registrados embaseline-results.json(por ativo;--replacepara uma substituição completa). Casos golden provisórios são ignorados, a menos que--allow-draftseja usado.scripts/fingerprint.py— CLI de relatório independente; um wrapper simples 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 para trás; nunca copia dados pessoais.
Princípio central: Sem medição sem uma linha de base. Degradação = queda significativa na taxa de aprovação sob uma impressão digital inalterada — 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 / recomendar / 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 substituição entre hosts. - Resultados de linha de base + golden sets 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.
Portanto, no WorkBuddy você avalia skills; no harness do DeepSeek você avalia plugins — mesmos comandos, adaptador diferente. Adicionar um novo host é uma entrada em hosts.json (tipo + raiz + nomes de arquivos de manifesto), sem alteração de código.
Quando Usar
- Antes de implantar uma nova skill ou plugin ("做个 skill，按评测流程走").
- Após um aumento de versão do 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 / aposentar uma skill.
- Ao recomendar uma skill ou plugin a um usuário (adequação + evidências).
Quando NÃO usar: tarefas únicas sem skill reutilizável; documentos puramente narrativos.
Conceito Central: A Impressão Digital de Versão (Fingerprint)
A fingerprint é a linha da matriz de depreciação.
fingerprint = hash(conteúdo dos arquivos da superfície de capacidade + caminho relativo) # escopo v2-ability-surface
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, templates - 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 criar o hash faz com que a fingerprint se mova e produza um falso FINGERPRINT-DRIFT ("o ativo foi editado") quando nada funcional mudou. Os plugins pioram isso — um plugin instalado pode carregar 16 MB de saída empacotada mais um README de 57 KB.
Regras:
- Fingerprint inalterada ⇒ a linha persiste; uma queda na taxa de aprovação é regressão do modelo.
- Fingerprint alterada ⇒ a mudança é responsabilidade da própria skill, não do modelo. Linhas antigas e novas coexistem, portanto as edições da skill nunca são atribuídas erroneamente à deriva do modelo.
Execute python scripts/console.py scan para calcular fingerprints e armazená-las no registro. fingerprint.py é um wrapper de relatório independente; não toca no registro.
Superfície de Capacidade (por que os plugins precisam de um segundo eixo)
A fingerprint diz "os arquivos mudaram". Ela não pode dizer "ainda oferece a mesma coisa".
scan também registra, portanto, 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 imprime explicitamente:
[caps] 1 ativo com superfície de capacidade alterada ("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 por não registrar suas ferramentas / dar 404 em suas rotas / não executar seus hooks — não por "responder pior". Um golden set de prompts mede a coisa errada para um plugin. O diff de superfície captura "v1.1.0 removed um ponto de entrada" sem precisar iniciar o host.
Limitação conhecida (não a ignore): 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 capturado.
Evidência de Tempo de Execução (o terceiro eixo e o que ele não pode fazer)
Existem duas coisas muito diferentes chamadas "uma sonda de tempo de execução". 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 | O perfil desktop do DSH é exclusivo do Electron — dsh --profile desktop --dump-config é recusado; nenhuma entrada headless → engenharia reversa do IPC ou dirigir a UI | uma leitura de arquivo, ~10 ms |
| captura | 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 ao vocabulário de falha (fail|error|ENOENT|unavailable|timeout|…).
Captura real, nesta máquina:
@wxg-prc-cpg/browser-skill-dsh-plugin 2 indícios de falha
bsk probe failed (spawn bsk ENOENT); ferramentas do navegador relatarão guia de instalação…
Arquivos presentes, manifesto válido, caps=4 — toda verificação estática passa. O plugin é carregado e suas ferramentas são registradas, mas elas não podem funcionar: a CLI bsk para a qual ele faz shell não está no PATH. Nenhuma quantidade de hash de arquivo 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ências; falhas de nível info são capturadas por correspondência de palavras-chave, portanto, tanto erros de omissão 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 seleção verde.
Implementado vs Apenas Metodologia (não confunda esta linha)
A metodologia abaixo é mais ampla do 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 |
| Golden scaffold + ingestão de linha de base (mesclagem por ativo, proteção de rascunho) | implementado (baseline.py) |
Matriz de taxa de aprovação, limiar ≥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 faça 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 tempo de execução 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 de gatilho, reconciliação de ambiente, linha de base de estilo | apenas metodologia — sem código |
| Reproduções K≥3, validação cruzada de juiz LLM | não implementado; os vereditos atuais são autoavaliação K=1 |
Coluna 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 executa a auditoria, não como algo que a ferramenta fará por eles.
Julgamento 1 — Degradação de Capacidade
Quatro etapas:
- Construa o golden set a partir do histórico, não manualmente. Explorem sessões passadas: usuário adotou sem resistência → replay positivo; usuário resistiu / pediu reescrita → negativo. 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 golden set, K≥3 (casos de pontuação de juiz LLM: 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 consistentemente direcional → relatar degradação; abaixo do limiar → "vigilância 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 gatilho.
- 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?
Dividido 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 = elevação_da_taxa_de_sucesso × frequência_da_tarefa − custo_marginalUma skill que eleva o sucesso em 30% mas aciona 3×/ano com +50k tokens cada é um passivo, não um ativo. - Modo sombra pós-implantação. Nova skill é executada silenciosamente: produz sugestões, mas não autoexecuta; registra "o que teria acontecido". Observe a taxa de adoção (aceito vs sobrescrito). A taxa de adoção é o juiz final de "bom", mais honesta do que qualquer métrica offline. Limite: skills de operação de gravação (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 negativos líquidos → sugerir reescrita ou aposentadoria. Este é o lado do consumidor da tabela de depreciação.
Julgamento 3 — Isso se Adapta a ESTE Usuário?
"Se adapta a você" = gatilhos precisos + suposições válidas + estilo corresponde. Tudo automatizável:
- Precisão do gatilho (mais afeta a sensação, mais ignorado). Amostra de histórico de positivos (deve acionar) e negativos (semelhante, não deve — "corrija 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 rótulo manual 10–20, depois semiautomático, custo LLM zero.
- Reconciliação de ambiente (instalado ≠ executa). Os metadados da skill declaram deps: 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", "produz saída em japonês", "precisa de contexto de 200k" — suposições invisíveis são a razão nº 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; juiz LLM compara formato, idioma, verbosidade. Usado apenas para desempatar skills com pontuação igual.
Fluxo de Trabalho Incorporado (para "criar uma nova skill")
Quando o usuário pede para criar uma skill, execute o protocolo em linha antes de entregar:
- Reconciliação de ambiente — o ambiente do usuário satisfaz as deps declaradas da skill + suposições de capacidade?
- Replay do gatilho — reproduza 10–20 casos amostrados; relate precisão/revocação.
- Ablação — em um pequeno lote de tarefas, meça a elevação vs custo.
- Entre em monitoramento — em caso de aprovação, registre a fingerprint + golden set; o console residente reexecuta a cada aumento de modelo.
Sugestão Baseada em Necessidade (quando nenhuma skill corresponde)
Este é o comportamento de "prateleira vazia": um usuário (especialmente um com zero skills/plugins) pede algo que nenhuma skill instalada cobre. Não diga apenas "não posso" — identifique a lacuna e ofereça-se para preenchê-la.
- Detecte a necessidade da conversa: tipo de tarefa + domínio (por exemplo, "relatório financeiro trimestral" → finanças/análise; "remover o tom de IA" → humanizador; "construir 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, 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 autoinstale — o usuário escolhe.
- Na instalação, configure a skill (reconciliação de ambiente + replay de gatilho + linha de base) a menos que o usuário opte por não participar.