Agent Plugins: o padrão aberto que faltav…

Quem constrói ferramentas para assistentes de programação conhece bem a dor da fragmentação. Você passa dias refinando um fluxo no Claude Code, depois precisa converter arquivos de configuração para o Cursor, reescrever esquemas para o Windsurf e ajustar comandos para o Kiro.

Cada cliente insistia em criar seu próprio formato de manifesto, espalhando configurações em arquivos como .claude/settings.json, .cursor/mcp.json ou estruturas proprietárias.

Essa bagunça começa a ter solução com a especificação aberta Agent Plugins (agent-plugins.org). O padrão define um formato único e portável para distribuir extensões de agentes, unindo duas camadas que antes viviam separadas: instruções em linguagem natural e capacidade real de execução.

Para garantir que pacotes desse tipo sejam confiáveis antes da instalação, publiquei a skill open-source agent-plugin-eval dentro do repositório fabricioctelles/skills.

O que a especificação resolve na prática

Até pouco tempo, você precisava escolher como distribuir uma extensão:

Ou empacotava instruções via Agent Skills (o formato aberto de arquivos SKILL.md mantido pelo agentskills.io), perfeito para guiar raciocínios e workflows;
Ou configurava servidores do Model Context Protocol (MCP), excelente para expor APIs, bancos de dados locais e ferramentas executáveis via stdio ou HTTP.

O padrão Agent Plugins resolve exatamente a união desses dois mundos em um único pacote instalável.

A estrutura é previsível e enxuta:

meu-plugin/
├── plugin.json        # Manifesto raiz com metadados e versão
├── mcp.json           # Configuração opcional de servidores MCP
└── skills/            # Diretório de Agent Skills
    ├── skill-a/
    │   └── SKILL.md
    └── skill-b/
        └── SKILL.md

Na raiz do projeto, o arquivo plugin.json declara o esquema canônico, nome, versão e metadados fechados. A pasta skills/ armazena as habilidades que os agentes carregam sob demanda. Já o arquivo mcp.json aponta para os servidores MCP que o agente pode acionar durante a sessão.

Tudo que for específico de um cliente proprietário precisa ficar isolado sob o campo extensions ou em pastas com domínios reversos (como io.cursor.* ou com.anthropic.*). Essa regra protege o núcleo do plugin contra poluição de fornecedores específicos.

Tip

A portabilidade só funciona quando o pacote não depende de variáveis ocultas no ambiente do usuário. O padrão define variáveis determinísticas como ${PLUGIN_ROOT} e ${PLUGIN_DATA} para resolver caminhos relativos de forma segura.

O perigo invisível ao baixar plugins de agentes

Quando você instala uma extensão comum no VS Code ou um pacote do npm, existe uma barreira mínima de isolamento. No mundo dos agentes autônomos, um plugin malicioso ou descuidado pode ter acesso direto ao terminal, ler variáveis de ambiente ou rodar scripts não supervisionados.

A especificação v1 foi desenhada com limites de segurança muito claros:

Contenção rigorosa de caminhos: nenhum comando, symlink ou diretório de trabalho (cwd) pode apontar para fora da pasta raiz do plugin;
Zero credenciais nos manifestos: expor tokens de API ou senhas em texto puro dentro do mcp.json invalida a conformidade;
Componentes independentes: a falha de um servidor MCP remoto ou uma skill com sintaxe inválida não deve quebrar a execução das outras ferramentas válidas do pacote.

Acompanhando a evolução de 19 ferramentas de desenvolvimento no agentify.ia.br, fica evidente que a segurança estática é o ponto que definirá quais plataformas serão adotadas em escala profissional.

Avaliando plugins com a skill agent-plugin-eval

Para auditar repositórios contra a especificação oficial de forma automatizada, criei a skill agent-plugin-eval.

Ela atua como um inspetor técnico estático para equipes e desenvolvedores. Antes de adicionar um plugin ao seu projeto, a skill inspeciona o repositório, aplica uma rubrica de 18 critérios e gera um placar transparente de 0 a 100 com indicação clara de bloqueios de release.

A avaliação é organizada em quatro eixos:

Eixo	O que é verificado
Conformidade Portável	Validação rigorosa do `plugin.json`, esquemas oficiais, nomes permitidos e fechamento de metadados
Componentes e Integração	Formato das Agent Skills em `skills/*/SKILL.md`, sintaxe do `mcp.json` e portabilidade dos comandos stdio
Segurança e Resiliência	Detecção de vazamento de credenciais, auditoria de symlinks e proteção contra escapes de diretório
Qualidade de Produto	Clareza de documentação, licença, coesão prática das ferramentas e higiene de dependências

Auditoria estática: segurança em primeiro lugar

A primeira diretriz da skill é não confiar no pacote avaliado. A análise é estritamente estática: ela nunca executa binários incluídos, não roda scripts de instalação e não sobe servidores MCP em segundo plano.

Qualquer suspeita de credencial encontrada no manifesto é automaticamente redigida no relatório final para evitar exposição acidental.

Portões de aprovação e notas com teto

Uma nota numérica alta em design ou documentação não pode esconder uma falha grave de segurança. A skill aplica portões de conformidade que limitam a pontuação final:

PASS (Aprovado): o plugin respeita todas as regras normativas. A nota final varia livremente de 0 a 100 com base na qualidade do conteúdo;
PARTIAL (Parcial): problemas não críticos, como uma skill secundária quebrada ou campo opcional fora do esquema. A nota final fica limitada ao teto de 59 pontos (Conceito C);
FAIL (Reprovado): erros graves, como manifesto raiz ausente, tentativa de escape de diretório ou credencial exposta. A nota fica travada no teto máximo de 39 pontos (Conceito D ou F).

# Executando a validação via terminal com os scripts auxiliares da skill
python3 scripts/inspect_plugin.py ./caminho-do-plugin --json
python3 scripts/score.py --gate pass 1:95:3 2:90:3 7:85:2

A ferramenta também conta com um modo de comparação lado a lado. Isso permite analisar dois plugins concorrentes e escolher a opção com melhor engenharia e menor risco.

Como instalar a skill no seu ambiente

A skill agent-plugin-eval faz parte da coleção aberta de ferramentas agênticas que mantenho no projeto Agentic Skills e no skilldev.pro.

Você pode adicionar a skill ao seu repositório local com um comando:

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

Ou copiar a pasta diretamente para o diretório de configuração do seu assistente habitual:

Cursor: .cursor/skills/agent-plugin-eval/
Claude Code: .claude/skills/agent-plugin-eval/
Kiro: .kiro/skills/agent-plugin-eval/

Com a skill carregada, basta apontar o comando no chat:

1
"Avalie o repositório de plugin em ./meu-plugin usando agent-plugin-eval. Aponte bloqueios de conformidade e a nota final."

Padronizar para destravar a colaboração

A área de inteligência artificial viveu ciclos de padrões proprietários em quase todas as camadas, dos formatos de modelos às interfaces de chat. No desenvolvimento agêntico, depender de manifestos fechados é uma barreira desnecessária para quem cria valor.

Ao unificar Agent Skills e MCP em um pacote comum, a especificação Agent Plugins cria as bases para um mercado aberto de componentes interoperáveis. Ferramentas como a agent-plugin-eval ajudam a garantir que essa abertura venha acompanhada de rigor técnico, segurança e portabilidade real.