Crie skills e plugins de agente que carregam e disparam corretamente

## Leia a documentação oficial e adapte uma skill de referência Antes de escrever qualquer coisa, leia a documentação oficial atual do sistema de plugins e skills que você está mirando: o formato de plugin, o formato de skill e as boas práticas de autoria publicadas. A documentação do fornecedor muda mais rápido do que qualquer texto de terceiros, então trate-a como a fonte da verdade e trate os guias da comunidade como comentários sobre ela. Em seguida, escolha uma skill de referência no nível de complexidade de que você precisa e adapte-a, em vez de projetar uma estrutura do zero: - Básico: frontmatter mínimo e um bloco curto de orientação, nada mais. - Intermediário: um pacote de linguagem, um diretório de referências e documentos específicos por idioma. - Avançado: scripts, arquivos de workflow, templates, auxiliares de extração e múltiplos pontos de entrada. Ler dois ou três plugins de produção de outras equipes costuma ser mais rápido do que inventar um layout. Se o ambiente oferecer um agente auxiliar que conheça a documentação para perguntas sobre plugins e skills, encaminhe essas perguntas para lá em vez de responder de memória. ## Mantenha uma única fonte de metadados mesmo quando vários runtimes carregam o plugin Quando mais de um runtime de agente puder carregar seu plugin, escolha um único formato de metadados como canônico e não acrescente cópias paralelas por runtime. Metadados duplicados divergem, e essa divergência é descoberta pelos usuários, não pelo CI. Na prática: - Mantenha o manifesto do marketplace e o manifesto por plugin em sua única localização canônica. - Não crie diretórios de manifesto específicos por runtime nem diretórios de metadados de plugin paralelos para um segundo runtime. - Mantenha todos os componentes na raiz do plugin, usando os caminhos padrão que ambos os runtimes já entendem: o diretório de skills, o arquivo de hooks, o arquivo de configuração MCP e o arquivo de configuração do aplicativo. - Se um plugin precisar de configuração MCP, coloque-a no arquivo de configuração MCP dedicado na raiz do plugin, em vez de embutir um objeto dentro do manifesto do plugin. Execute a verificação de carregabilidade para cada runtime suportado antes de submeter. Quando um runtime falhar, corrija a fonte canônica para que o outro runtime consiga carregá-la por compatibilidade — nunca adicionando uma segunda cópia dos mesmos metadados. ## Coloque os diretórios de componentes na raiz do plugin, não no de metadados Um diretório de plugin contém um diretório de metadados do plugin que guarda apenas o manifesto do plugin (nome, versão, descrição, autor), além de diretórios opcionais para comandos de barra, agentes autônomos, skills e hooks de eventos, mais um README que documenta o plugin. Cada skill vive em seu próprio diretório dentro do diretório de skills, com um documento de ponto de entrada que carrega o frontmatter e subdiretórios opcionais para referências, workflows e scripts. A regra que mais derruba as pessoas: os diretórios de componentes — skills, comandos, agentes e hooks — precisam ficar na raiz do plugin, e não dentro do diretório de metadados do plugin. Só o manifesto do plugin pertence a ele. Tanto os carregadores quanto os revisores dependem disso, e um diretório de componente fora do lugar geralmente se manifesta como um plugin que silenciosamente não expõe nada. ## Escolha um nome claro em kebab-case e preencha o frontmatter O frontmatter no ponto de entrada de uma skill precisa, no mínimo, de um nome e uma descrição. Uma lista opcional de ferramentas permitidas restringe a skill às ferramentas de que ela realmente precisa, o que vale a pena configurar sempre que a skill for estreita. - O nome usa kebab-case e permanece dentro do limite de comprimento, comumente 64 caracteres. - A descrição é escrita em terceira pessoa e informa tanto o que a skill faz quanto quando usá-la. - Prefira a forma de gerúndio para os nomes — um nome que começa por verbo, como "analyzing-contracts" ou "processing-pdfs", lê-se melhor do que um nome de agente substantivo, como "contract-analyzer" ou "pdf-processor". - Evite nomes vagos como helper, utils, tools ou misc, que correspondem a tudo e não significam nada. - Evite palavras reservadas, incluindo nomes de fornecedores e produtos, que o runtime pode tratar de forma especial. ## Diga na descrição o que a skill faz e quando usá-la Sua skill compete com uma centena de outras pela atenção, e a descrição costuma ser o único texto que o agente lê ao decidir se a carrega. Uma descrição vaga significa que a skill fica sem uso ou, pior, dispara na situação errada. - Voz em terceira pessoa: "Analisa X", não "Eu ajudo com X". - Inclua a situação que dispara a skill, não apenas o assunto: "Use ao auditar contratos inteligentes" carrega muito mais sinal de roteamento do que "Ferramenta de contratos inteligentes". - Seja específico sobre a capacidade: "Detecta vulnerabilidades de reentrância" supera "Ajuda com segurança". Escreva a descrição como se ela fosse a regra de roteamento que de fato é, e releia-a perguntando se uma skill concorrente venceria a mesma solicitação. ## Evite caminhos absolutos e declare as dependências dentro do script Nunca fixe caminhos absolutos no código. Use a variável de diretório-base que o runtime fornece e use barras normais mesmo no Windows, para que a mesma skill funcione em qualquer máquina. Quando uma skill distribui scripts que possuem dependências: 1. Declare as dependências em linha no cabeçalho do script, usando o bloco padrão de metadados em linha daquela linguagem, incluindo a versão mínima da linguagem. Isso permite que o executor resolva tudo sem uma etapa de instalação separada. 2. Invoque o script por meio de um executor que respeite esses metadados em linha, para que a resolução de dependências seja automática em vez de um pré-requisito documentado. 3. Mantenha um arquivo de projeto no diretório de scripts para o ferramental de desenvolvimento, como linters e formatadores. 4. Documente as dependências de nível de sistema que o gerenciador de pacotes da linguagem não consegue instalar — ferramentas de PDF e OCR, por exemplo — nos arquivos de workflow, com comandos de instalação específicos por plataforma. ## Mantenha rápidos os hooks que rodam antes de cada comando Hooks que rodam antes de cada comando ficam no caminho crítico, então seu custo é pago em toda e qualquer invocação. Aqui o desempenho é uma questão de correção, não um luxo. - Prefira um shell mais um filtro JSON leve a um interpretador completo. A inicialização do interpretador e do parser adiciona uma latência que os usuários sentem em cada comando. - Falhe rápido logo no início: saia com sucesso e imediatamente para comandos que claramente não correspondem, de modo que a esmagadora maioria das invocações seja praticamente gratuita. - Prefira expressões regulares à análise completa de árvore sintática. Aceite falsos positivos raros quando o ganho de desempenho for significativo e o agente puder simplesmente reformular o comando. - Antecipe os formatos de falso positivo: comandos de diagnóstico que apenas localizam um interpretador, comandos de busca que mencionam o nome dele como termo de pesquisa e nomes de arquivo contendo esse nome não devem disparar a interceptação. - Documente esses compromissos na descrição da alteração, para que os revisores percebam que as escolhas foram deliberadas e não descuidadas. ## Ensine quando e por que consultar em vez de colar especificações inteiras Uma skill deve fornecer orientação que o modelo ainda não tenha. Colar uma especificação inteira dentro de uma skill queima contexto e não acrescenta nada que o modelo não pudesse consultar. - Não cole especificações inteiras nem referências de API. Ensine, em vez disso, quando e como consultar as coisas. - Explique o porquê, não apenas o quê: inclua compromissos, critérios de decisão e os julgamentos que um recém-chegado erraria. - Documente os antipadrões junto com a razão pela qual estão errados, em vez de uma lista seca de proibições. Um bom exemplo do padrão: uma skill para um formato binário complexo de depuração não embute a especificação do formato. Ela ensina quais ferramentas de inspeção usar, como consultá-las e qual ferramenta é apropriada para qual pergunta. ## Ajuste a rigidez ao risco da tarefa e diga quando não usar a skill O quanto uma skill deve ser rígida depende de quão frágil é a tarefa. - Rígida para tarefas frágeis: auditorias de segurança, implementações criptográficas e verificações de conformidade precisam de procedimentos passo a passo rígidos e obrigatórios. - Flexível para tarefas variáveis: exploração de código, documentação e refatoração devem oferecer opções e deixar espaço para julgamento. Todo ponto de entrada de skill precisa conter duas seções. Uma seção "Quando Usar", listando os cenários específicos em que a skill se aplica, e uma seção "Quando NÃO Usar", nomeando os casos em que outra abordagem é melhor. A seção negativa é a que as pessoas pulam, e é justamente ela que impede a skill de disparar no lugar errado. Skills de auditoria e de segurança precisam de uma terceira seção, "Racionalizações a Rejeitar", listando os atalhos e desculpas comuns que levam a achados perdidos — porque, sob pressão de tempo, são exatamente essas racionalizações que aparecem. ## Mantenha curto o arquivo principal e ligue os detalhes a um só nível Mantenha o ponto de entrada da skill abaixo de aproximadamente 500 linhas e divida o restante em um diretório de referências e um diretório de workflows. Coloque o início rápido primeiro e os detalhes atrás de links, para que quem só precisa do caminho comum nunca carregue o resto. Mantenha os links com apenas um nível de profundidade: o ponto de entrada aponta para arquivos, e esses arquivos não encadeiam links para outros arquivos. A profundidade de diretórios em si não é problema — um diretório de referências com subpastas por tema é perfeitamente razoável. O problema é a indireção encadeada, não as pastas aninhadas. Um formato típico é uma seção de Início Rápido com as instruções centrais, uma seção de Uso Avançado apontando para um documento de referência com padrões detalhados e uma seção de referência de API apontando para outro documento com a documentação completa dos métodos. ## Passe nas checagens automáticas e humanas e suba a versão antes da revisão Separe o que a automação valida do que um revisor humano precisa julgar, e resolva ambos antes de abrir uma revisão. Verificações automatizadas: frontmatter válido com nome e descrição; nome em kebab-case dentro do limite de comprimento; todo arquivo referenciado realmente existe; nenhum caminho fixo para o diretório home; a verificação de carregabilidade passa para cada runtime suportado. Verificações do revisor: a descrição dispara corretamente e está escrita em terceira pessoa; tanto a seção "Quando Usar" quanto a "Quando NÃO Usar" estão presentes; os exemplos são concretos, mostrando a entrada e a saída resultante; o documento explica o porquê e não apenas o quê. Documentação: o plugin tem um README; ele foi adicionado à tabela do README raiz; está registrado no manifesto do marketplace no nível do repositório, e não no diretório de metadados do próprio plugin; e uma entrada de propriedade nomeia os mantenedores no arquivo de code owners. Atualizações de versão para um plugin existente: incremente a versão tanto no manifesto do plugin quanto na entrada do marketplace no nível do repositório, e mantenha os dois números idênticos. Muitos clientes só puxam uma atualização quando o número da versão aumenta, então um incremento esquecido significa que ninguém recebe a correção.