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