Criando Habilidades para Agentes de IA: Mecânicas, Melhores Práticas e Transformação em um Plugin

O autor, desenvolvedor do repositório rpa-skills, detalha como criar skills para agentes de IA da maneira correta. Uma skill não é um único arquivo markdown, mas uma pasta com um arquivo SKILL.md obrigatório contendo um cabeçalho YAML (nome, descrição) e um corpo de instruções, juntamente com diretórios opcionais references/, scripts/, assets/ e README.md. O princípio da divulgação progressiva carrega apenas a descrição da skill para o sistema; o corpo é puxado após a ativação, então o corpo deve ser mantido em 500 linhas, com conteúdo pesado movido para references/. No campo de descrição, é importante especificar claramente o propósito e as condições de disparo, evitando palavras genéricas como DEVE para impedir que o modelo ative a skill de forma aleatória. O autor enfatiza a diferença entre skills e regras: regras (com alwaysApply: true) estão sempre ativas e são adequadas para estilo de código ou tratamento de erros, enquanto skills são melhores para procedimentos de múltiplas etapas (implantação, BDD, análise de bugs). As descrições e os corpos das skills devem ser escritos em inglês devido à tokenização: o cirílico usa em média o dobro de tokens do latim, economizando contexto. São fornecidas práticas da Anthropic: graus de liberdade (trilhos rígidos para tarefas críticas, campo aberto para criativas), operações determinísticas devem ser movidas para scripts, uma seção obrigatória para erros comuns (Gotchas), nomes na forma gerúndia (por exemplo, processando-pdfs) e evitar variabilidade excessiva—é melhor fornecer uma solução principal e uma alternativa. Para testar uma skill, execute um subagente com contexto limpo e verifique se a skill ativa automaticamente, onde cometeu erros e se o resultado corresponde às expectativas. Recomenda-se pelo menos três execuções em tarefas diferentes e em modelos diferentes, incluindo modelos pequenos que seguem instruções literalmente. Uma skill para o mercado é empacotada como um plugin—uma pasta com um manifesto plugin.json (para Claude Code em .claude-plugin/, para Codex em .codex-plugin/), especificando metadados, com o nome correspondendo ao nome do SKILL.md e a versão sincronizada. O plugin também pode incluir comandos de barra, subagentes, ganchos e servidores MCP.