Agent Plugin Eval

Visão Geral

Audita repositórios que contêm Agent Plugins portáveis contra a especificação oficial Agent Plugins. Produz um scorecard de 0 a 100 com evidências citadas por file:line ou ponteiro JSON, um gate de conformidade (PASS/PARTIAL/FAIL) e a lista de blockers que impedem o release.

Avalia conformidade portável, não features de um cliente específico. Um manifesto nativo — .codex-plugin/plugin.json, .claude/settings.json, .cursor/mcp.json — não substitui o plugin.json obrigatório na raiz. Um plugin excelente para um cliente pode reprovar no padrão portável, e a skill reporta os dois fatos sem tirar média entre eles.

Quando Usar

• Auditar um repositório de plugin antes de publicar
• Verificar conformidade de plugin.json ou mcp.json
• Validar Agent Skills incluídos no pacote
• Avaliar configuração de MCP servers quanto a portabilidade e segurança
• Identificar blockers de release
• Comparar dois agent plugins lado a lado

Instalação

npx skills add https://github.com/fabricioctelles/skills -s agent-plugin-eval

Fronteira de segurança

Auditoria puramente estática. A skill não executa código do plugin, hooks, scripts de instalação, gerenciadores de pacote, MCP servers nem testes em rede sem autorização explícita do usuário. Valores suspeitos de credencial são redigidos no relatório e marcados como suspected — um acerto de heurística derruba a nota de segurança e exige revisão, mas sozinho não vira gate FAIL de credencial confirmada.

18 critérios em 4 eixos

Eixo	Critérios	Foco
1 — Conformidade portável	4	Um único plugin.json na raiz, schema canônico, modelo de metadados fechado, descoberta em locais fixos e coerência de versão
2 — Componentes e integração	6	Conformidade e qualidade dos Agent Skills, validade do mcp.json, portabilidade de servidores stdio, transporte remoto, isolamento de extensões
3 — Segurança e resiliência	4	Contenção de caminho após resolver symlinks, exposição mínima de segredos, independência entre componentes, instalação sem efeito colateral oculto
4 — Qualidade de produto	4	Coesão, documentação, utilidade prática e prontidão para release

Critérios têm peso 1x, 2x ou 3x, e os que não se aplicam entram como NA em vez de penalizar. O cálculo é determinístico, via scripts/score.py:

python3 scripts/score.py --gate partial 1:90:3 2:80:3 3:NA:2

Gates de conformidade

Gate	Quando	Teto da nota
PASS	Nenhuma violação normativa encontrada	sem teto
PARTIAL	Desvio não-fatal de manifesto, ou componente inválido/ignorado	59
FAIL	Falha fatal de manifesto ou raiz de pacote, escape da raiz, ou credencial embutida confirmada	39

A nota sem teto continua visível ao lado da nota final, para separar qualidade de design de bloqueio de conformidade.

Como Funciona

1. resolver a raiz do plugin (local, ou clone raso de URL Git)
2. carregar as regras vigentes (snapshot da 1.0.0, ou spec publicada)
3. inventariar todo caminho do pacote  <-- dotfiles, symlinks, ignorados pelo Git
4. varredura determinística (inspect_plugin.py) como pista, não veredito
5. revisar cada skill e cada entrada de mcpServers
6. pontuar com score.py e aplicar o gate

Cada achado da varredura é confirmado na fonte antes de entrar no relatório. Um cliente aceitar determinada construção não enfraquece um achado normativo.

Armadilhas que a skill trata

• O núcleo portável v1 contém exatamente Agent Skills e MCP servers. Hooks, commands, agents, apps e marketplaces são específicos de cliente, a menos que estejam num namespace de extensão válido
• skills/ ou mcp.json ausentes não são erro. Um caminho presente com o tipo errado de arquivo é componente inválido
• Uma skill inválida não pode ser reportada como se todo componente independente fosse inválido
• ${PLUGIN_ROOT} e ${PLUGIN_DATA} expandem apenas em args, valores de env e cwd do MCP — nunca em command, URLs ou headers

Fontes

• Agent Plugins — especificação oficial
• Agent Skills — especificação

📄 Documentação completa no GitHub

---

Integração com TypeSafe Jev

A skill suporta integração opcional com TypeSafe Jev — um motor de julgamento que fornece avaliações de probabilidade calibradas para critérios subjetivos de qualidade.

Quando usar Jev

Avaliação	Usar Jev?	Método
Conformidade Eixos 1-3	Não	Determinístico (inspect_plugin.py)
Qualidade Eixo 4 (produto)	Sim	Score (UX, docs, erros)
Qualidade Eixo 2 (design)	Sim	Score (schema, naming, API)
Classificação de gates	Sim	Noul (pass/fail)
Detecção de secrets	Sim	Noul (suspected/not_suspected)
Checklist de qualidade	Sim	Noul (present/missing)

Questões disponíveis

• 7 Score questions: coerência de UX, clareza de documentação, qualidade de error handling, robustez de validação, design de schema, consistência de naming, elegância de API
• 19 Noul questions: gates G1-G4, detecção de secrets (4), checklist de qualidade (7), validade de componentes (4)

Protocolo de descoberta

from typesafe import jev_available

if jev_available():
    from typesafe import Score, Noul
    # Usar Jev para critérios subjetivos
else:
    # Fallback para scoring heurístico

Quando Jev não está disponível, a skill usa:

• Quality scoring: checks heurísticos (existência de arquivo, tamanho, pattern matching)
• Gate classification: validação determinística de JSON/schema
• Secret detection: regex pattern matching (maior taxa de falsos positivos)

📄 Ver jev_questions.json | Ver jev-integration.md