WP Plugin Directory Guidelines: audite antes de enviar

ANÁLISE EDITORIAL

Um plugin pode funcionar bem em um site de teste e ainda ser recusado no diretório WordPress.org. O problema nem sempre está em um erro de PHP. Licença incompatível, recurso local travado por pagamento, coleta de dados sem consentimento, código executável carregado de fora, nome que invade uma marca e avisos administrativos intrusivos também entram na revisão. WP Plugin Directory Guidelines transforma essas frentes em uma inspeção organizada, com achados ligados às 18 diretrizes oficiais.

A Skill faz parte do repositório oficial WordPress/agent-skills, mantido por contribuidores do projeto WordPress. A curadoria fixou o commit d87ee6916e740c7960b6959220c0481a41b320c7. A API pública do GitHub mostrava 2.078 estrelas em 29 de agosto de 2026. Esse número comprova adoção do repositório, não a qualidade de um plugin analisado nem a chance de aprovação.

Ilustração editorial exclusiva: a capa mostra um pacote modular atravessando pontos abstratos de licença, consentimento, origem do código e inspeção antes de chegar a um catálogo. Não é captura de tela, interface real, relatório do Plugin Check, logotipo, selo de conformidade ou prova de aprovação.

O que a WP Plugin Directory Guidelines faz de verdade

O SKILL.md auditado orienta o agente a examinar o código-fonte, o arquivo principal do plugin e o readme.txt. A revisão percorre as 18 regras do diretório e pede atenção especial a licença, legibilidade do código, trialware, consentimento para dados externos, carregamento remoto de código, experiência administrativa e uso de marcas.

A instrução não executa um scanner nem envia o plugin ao WordPress.org. Ela fornece um roteiro de revisão. O agente deve registrar cada achado com a diretriz aplicável, o arquivo, o valor ou trecho observado, a consequência e uma correção proposta. Quando a licença ou o comportamento é ambíguo, a regra é não adivinhar.

As referências incluídas aprofundam três áreas. O checklist detalha sinais, perguntas, vereditos e correções para cada diretriz. O guia de GPL organiza licenças aceitas e incompatibilidades frequentes. O guia de nomes cobre cabeçalhos, slug, termos genéricos e marcas. A página oficial das diretrizes continua sendo a fonte normativa que deve ser consultada novamente no dia da submissão.

Para quem serve

Serve a desenvolvedores preparando a primeira submissão, mantenedores que receberam uma devolutiva da equipe de plugins, agências que precisam revisar um pacote de cliente e equipes que querem antecipar riscos antes de montar o ZIP final. Também ajuda em auditorias de plugins freemium, integrações SaaS e projetos que incluem bibliotecas, fontes ou imagens de terceiros.

A Skill é útil quando a pergunta é específica, por exemplo: o recurso gratuito funciona de ponta a ponta, a telemetria está realmente desligada até o opt-in, o JavaScript executado no site está dentro do pacote, o nome respeita a marca citada e as versões do cabeçalho e do readme.txt coincidem?

Ela não substitui aconselhamento jurídico, revisão de segurança, testes funcionais ou a decisão da equipe do diretório. A aprovação é contextual e as regras podem mudar. Use a saída como pré-auditoria documentada, não como certificado.

Compatibilidade e pré-requisitos

O frontmatter da Skill declara alvo em WordPress 7.0 ou superior e PHP 7.4 ou superior. O conteúdo é Markdown e pode ser usado por clientes compatíveis com Agent Skills. Para uma revisão útil, o agente precisa acessar uma cópia completa do plugin, incluindo código não minificado ou a origem pública indicada, arquivos de build, dependências, ativos, arquivo principal e readme.txt.

Antes de começar, registre nome, slug pretendido, versão, origem do pacote, repositório de desenvolvimento, serviços externos, bibliotecas incorporadas e canais de distribuição. Se houver uma versão no site do autor, compare-a com a versão destinada ao WordPress.org. Se houver código compactado, localize a fonte correspondente e as instruções de build, conforme os problemas comuns documentados pela equipe.

O pacote do Bastidores é somente documental. Não inclui WordPress, Plugin Check, PHP, Node.js, o plugin que será revisado ou qualquer automação de envio. Para uma checagem automatizada complementar, use o Plugin Check oficial em ambiente controlado e trate o resultado como uma camada, não como aprovação.

Instalação recomendada

Copie a pasta wp-plugin-directory-guidelines para o diretório de Skills aceito pelo cliente. Preserve o SKILL.md e os três arquivos em references. O README fixado também documenta instalação com npx skills add WordPress/agent-skills --skill wp-plugin-directory-guidelines.

Antes de executar qualquer comando, confira o pacote recebido, o commit e a licença. Instale primeiro em um projeto descartável ou em uma cópia do repositório. A instalação da Skill apenas disponibiliza instruções ao agente. Ela não instala o Plugin Check nem concede acesso ao WordPress.org.

Evite usar uma cópia global antiga sem saber sua origem. Se o diretório oficial atualizar uma regra, uma Skill desatualizada pode repetir um checklist correto para outro momento. Fixar o commit torna a auditoria reproduzível, mas não elimina a obrigação de consultar a documentação vigente.

Configuração antes do primeiro uso

Defina o escopo por escrito. Informe se a tarefa é uma revisão completa, uma resposta a uma devolutiva, uma análise de licença ou apenas uma checagem de nome. Diga se o agente pode somente ler ou também criar um relatório em caminho separado. Não permita alterações silenciosas no plugin durante a auditoria.

Monte uma ficha inicial com o caminho do plugin, versão, arquivo principal, readme.txt, lista de dependências, diretórios de ativos, URLs externas e serviços usados. Para cada arquivo de terceiro, registre origem, versão e licença. Um pacote sem licença comprovável deve ser tratado como pendência, mesmo que o código esteja disponível publicamente.

Separe os estados do relatório em PASS, WARNING, FAIL e não verificado. A Skill usa falha para violações objetivas, mas ausência de evidência não deve virar aprovação. Registre também o que não foi possível inspecionar.

Primeiro uso seguro

Comece por inventário, não por correção. Peça ao agente para listar arquivos, cabeçalhos, bibliotecas, código minificado, chamadas externas, enqueues remotos, telas administrativas, controles de licença, quotas e nomes usados. Depois, solicite um achado por item, sempre com caminho e diretriz.

Revise este plugin em modo somente leitura.
Use as 18 diretrizes do diretório WordPress.org.
Para cada achado, informe diretriz, arquivo, evidência, impacto e correção.
Marque como não verificado tudo que depender de fonte ausente.
Não altere código, não gere ZIP e não faça submissão.

Na primeira passagem, priorize as diretrizes 1, 4, 5, 7, 8 e 17. Elas concentram licença, fonte legível, trialware, consentimento, código remoto e marcas. Depois percorra as demais para evitar que uma revisão técnica ignore versão, readme, bibliotecas já fornecidas pelo WordPress ou experiência administrativa.

Como revisar um plugin

Licença: compare o cabeçalho do arquivo principal, o texto de licença e cada dependência. A diretriz oficial recomenda GPLv2 ou posterior, mas aceita licenças compatíveis. A lista de licenças da GNU ajuda em casos conhecidos. Se houver dúvida sobre combinação ou ativo, registre a incerteza e encaminhe para revisão especializada.

Legibilidade e build: procure PHP ofuscado, JavaScript apenas minificado e artefatos sem origem acessível. Código minificado pode existir quando a fonte correspondente e as instruções de construção estão documentadas. Não trate mapa de origem ausente como detalhe quando ninguém consegue localizar o código humano que gerou o arquivo distribuído.

Trialware e serviço: percorra cada condição de licença, expiração e quota. Um recurso local incluído no plugin não pode ser travado até pagamento. Uma integração SaaS real pode cobrar pelo serviço externo, desde que sua função esteja clara. Diferencie o custo da API de uma trava artificial aplicada a código local.

Dados e código remoto: identifique chamadas que saem no primeiro carregamento, na ativação ou em tarefas agendadas. Telemetria precisa de consentimento explícito e desligado por padrão. JavaScript e CSS executáveis devem estar no pacote, salvo exceções estreitas previstas pelas regras. Registre domínio, arquivo, linha, finalidade e condição de consentimento.

Nome e cabeçalhos: confirme que o nome no arquivo principal coincide com o readme.txt, que o slug é claro e que marcas aparecem na posição permitida. Os requisitos oficiais de cabeçalho são a referência para campos como nome, versão, licença e URI.

Empacotamento e versão: verifique que a versão é completa, que a tag estável corresponde ao cabeçalho e que bibliotecas já fornecidas pelo WordPress não foram duplicadas. Rode testes e Plugin Check em uma cópia. Só aplique correções depois de aprovar o plano e preservar um diff revisável.

Resultado esperado

O resultado esperado é um relatório reproduzível, não uma frase de “está tudo certo”. Cada linha deve permitir que outra pessoa encontre a evidência e repita a conclusão. Um resumo útil separa bloqueadores, avisos, itens não verificados e recomendações de baixo risco.

Para um FAIL, cite a diretriz, o caminho, o comportamento e a mudança necessária. Para um WARNING, explique por que o item merece revisão mesmo sem violação confirmada. Para um PASS, indique o que foi examinado. Para “não verificado”, diga qual arquivo, acesso ou decisão falta.

Depois da correção, execute a mesma auditoria novamente e compare o diff. A ausência de achados automáticos não garante aprovação. A equipe do WordPress.org pode interpretar contexto, solicitar esclarecimentos ou atualizar as regras.

Permissões, privacidade e riscos

A Skill precisa ler todo o pacote do plugin para encontrar dependências, endpoints e comportamento administrativo. Limite o acesso ao repositório em análise. Não entregue chaves, arquivos de produção, bancos de dados ou dumps de clientes. Quando URLs ou exemplos contiverem identificadores reais, masque-os no relatório.

Com acesso a shell, o agente pode rodar scanners, instalar dependências, modificar arquivos e gerar pacotes. Essas ações não fazem parte da leitura inicial. Exija autorização separada para instalar Plugin Check, executar scripts de build, aplicar correções, criar ZIP, conectar uma conta WordPress.org ou enviar qualquer submissão.

Revisões de licença têm risco jurídico. O checklist ajuda a identificar sinais, mas não decide autoria, compatibilidade complexa ou direitos sobre marcas. Quando a conclusão depender de interpretação, registre a questão e procure a fonte aplicável. Não transforme uma inferência do agente em parecer.

Erros comuns e como corrigir

Tratar Plugin Check como aprovação. Use-o como evidência complementar. Revisar só PHP. Inclua JavaScript, CSS, imagens, fontes, bibliotecas e readme. Confundir SaaS com trialware. Descreva onde a função acontece e por que o pagamento existe.

Aceitar licença pelo nome do repositório. Leia o arquivo aplicável ao commit e preserve o aviso. Marcar telemetria como anônima sem rastrear o payload. Verifique os campos enviados e o momento do consentimento. Olhar apenas o nome visível. Compare também slug, cabeçalho, readme e marcas.

Corrigir durante a auditoria. Primeiro gere relatório e peça aprovação. Esquecer o código-fonte dos artefatos. Documente repositório e build. Prometer aprovação. A revisão reduz surpresa, mas a decisão pertence à equipe do diretório.

Versão auditada, licença e download local

A origem foi fixada no commit d87ee6916e740c7960b6959220c0481a41b320c7. O diretório da Skill no commit auditado contém SKILL.md e três referências Markdown. Nenhum script ou binário é necessário para ler o roteiro.

O repositório usa GPL-2.0-or-later, que permite redistribuição e modificação sob seus termos. O ZIP próprio preserva LICENSE e ORIGEM.md. Ele não inclui o restante do repositório, executáveis, dependências ou dados.

SHA-256 do ZIP documental: 86bc682bb42571477dd9acdf6fe4e05cc9d06ec57d1a18126d072a08134f42c1. Compare o valor após baixar. Para usar conteúdo posterior, volte à origem oficial, fixe um novo commit e repita a auditoria.

Checklist antes de enviar ao diretório

• Fixe a versão do plugin e o commit da revisão.
• Confira licença do código, bibliotecas, imagens, fontes e demais ativos.
• Garanta fonte humana e instruções de build para arquivos compactados.
• Verifique se todas as funções locais incluídas operam sem pagamento.
• Documente serviços externos e mantenha telemetria em opt-in explícito.
• Inclua no pacote todo código executável usado no site, salvo exceções permitidas.
• Revise nome, slug, marcas, cabeçalho e readme.txt.
• Alinhe versão do cabeçalho, tag estável e pacote final.
• Rode Plugin Check e testes em uma cópia limpa.
• Releia as diretrizes oficiais no dia da submissão.
• Não envie nada sem revisão humana do ZIP final.

Limites da revisão

Uma pré-auditoria boa revela evidência, reduz retrabalho e torna as decisões explícitas. Ela não prevê todas as interpretações, não prova ausência de vulnerabilidades e não concede autorização de marca ou licença. Preserve o relatório, o commit, o ZIP revisado e as respostas recebidas para que cada correção tenha histórico.

Para uma visão mais ampla de desenvolvimento, consulte também a Skill WordPress Pro no catálogo do Bastidores. Ela cobre arquitetura e implementação. Esta página tem finalidade diferente: revisar conformidade de uma submissão ao diretório WordPress.org.

Referências primárias

A curadoria comparou o SKILL.md, as referências, o README e a licença no commit fixado com as diretrizes, os problemas comuns, os requisitos de cabeçalho e a página do Plugin Check. Todas essas fontes responderam antes da criação do rascunho. Consulte a origem novamente sempre que a revisão envolver uma nova versão do WordPress ou uma submissão real.