Escrever habilidades para agentes de IA e testar se elas realmente ajudam

## Ler a especificação e as regras do repositório antes de editar uma habilidade Trate a especificação da plataforma, as orientações do repositório, a configuração de validação e a política de contribuição como contratos executáveis. Leia as regras aplicáveis antes de editar e diferencie os requisitos impostos mecanicamente das convenções que exigem revisão. Mapeie as responsabilidades antes de alterar qualquer coisa. Identifique o arquivo principal de instruções, o material de referência opcional, os auxiliares executáveis, os recursos reutilizáveis, os manifestos de distribuição, o formatador, o linter, os testes e os relatórios de avaliação. Mantenha os recursos que não sejam Markdown em arquivos próprios de recursos ou scripts, em vez de incorporá-los ao texto. Quando as fontes divergirem, use a especificação canônica indicada e o comportamento atual da validação. Não invente campos, fluxos de trabalho ou exceções apenas porque são convenientes localmente. ## Definir o nome, os metadados e a versão da habilidade Forneça a cada habilidade metadados legíveis por máquina que correspondam ao esquema do ambiente hospedeiro. Um nome normalizado deve usar letras minúsculas, algarismos e hífens simples, ter entre 1 e 64 caracteres e corresponder ao próprio diretório. Mantenha a descrição dentro do máximo de 1.024 caracteres da plataforma e do limite operacional de 1.000 caracteres. Declare a licença, os requisitos de compatibilidade, o autor, a versão semântica, o modo de invocação, as ferramentas permitidas e as dependências reais de execução. Quando uma habilidade abranger uma biblioteca ou plataforma versionada, registre a versão para a qual ela foi escrita, para que os responsáveis pela manutenção possam detectar conteúdo desatualizado. Inicie novas habilidades com uma versão inicial escolhida de forma deliberada. Incremente a versão da habilidade quando o comportamento mudar e mantenha todos os manifestos de distribuição na mesma versão de publicação. Não altere versões automaticamente antes de conhecer o escopo da implementação e da revisão. ## Escrever uma descrição que acione a habilidade na hora certa Trate a descrição como o principal mecanismo de roteamento. Informe o que a habilidade faz, quando deve ser usada, o domínio ou a linguagem pertinente e situações concretas que a acionam. Descrições específicas de uma biblioteca devem indicar a interface importante e o contexto de importação ou adoção. Evite descrições vagas que omitam casos de uso e declarações amplas que sejam acionadas por quase qualquer tarefa. Uma habilidade focada não deve reivindicar atividades genéricas, como toda programação, toda atribuição de nomes ou qualquer conversa. Quando houver sobreposição entre habilidades, atribua cada conceito a um único responsável e acrescente um limite explícito com uma referência cruzada portátil para a habilidade responsável. Teste as descrições com gatilhos positivos realistas e habilidades próximas concorrentes, para que o roteamento seja preciso sem deixar de ser acionado quando necessário. ## Dar à habilidade só as ferramentas e dependências de que ela precisa Declare um pequeno conjunto padrão de capacidades e acrescente ferramentas especializadas somente quando o fluxo de trabalho da habilidade realmente precisar delas. Prefira permissões de comando de escopo restrito a shells irrestritos. Trate o acesso à rede, a obtenção de documentação externa, as operações destrutivas, o trabalho paralelo com modificações e as solicitações de entrada do usuário como capacidades explícitas, não como padrões implícitos. Liste apenas dependências reais. Informe os binários necessários e as restrições de compatibilidade, e forneça metadados de instalação compatíveis somente para as dependências que o fluxo de trabalho realmente utiliza. Fixe dependências executáveis ou ações em versões revisadas, em vez de usar versões não fixadas. Separe a exploração somente para leitura das modificações. Se trabalhadores paralelos puderem gravar, exija ramificações ou espaços de trabalho isolados e uma etapa definida de mesclagem ou comparação. Não amplie as permissões apenas para simplificar um exemplo. ## Manter o arquivo principal curto e mover detalhes para arquivos vinculados Mantenha o arquivo principal de instruções concentrado na postura, nas decisões e no fluxo de trabalho essenciais. Coloque referências detalhadas, catálogos de comandos, modelos e recursos de configuração em arquivos secundários vinculados diretamente e evite cadeias profundas de referências. Use limites práticos: cerca de 100 tokens para a descrição, menos de 5.000 tokens para as instruções principais, de preferência menos de 2.500, e menos de 500 linhas. Mantenha as instruções combinadas que normalmente são carregadas juntas abaixo de aproximadamente 10.000 tokens. Transfira o aprofundamento para arquivos externos antes de comprimir a ponto de eliminar o discernimento necessário. As diretivas opcionais no início do corpo devem aparecer em uma ordem estável: persona, modo de raciocínio profundo, modo de orquestração, modos operacionais e, em seguida, dependências não triviais. Inclua uma persona curta somente quando uma postura de domínio ou um estilo de saída se beneficiar dela. Reserve as diretivas de raciocínio profundo e orquestração para trabalhos realmente analíticos ou paralelos de amplo alcance. ## Decidir quando uma habilidade divide o trabalho entre agentes em paralelo Dê nomes a modos distintos quando uma habilidade admitir tarefas substancialmente diferentes. Use um fluxo de trabalho sequencial para a escrita, rastreie os arquivos alterados e os caminhos de chamada adjacentes para a revisão e divida auditorias amplas por área de interesse ou escopo da base de código quando o ambiente admitir trabalhadores paralelos. Use no máximo um conjunto pequeno e limitado de trabalhadores, geralmente cinco, com atribuições sem sobreposição. Análises independentes somente para leitura podem compartilhar arquivos; trabalhos com modificações exigem isolamento. Trabalhadores em segundo plano devem realizar verificações úteis e não bloqueantes enquanto o fluxo de trabalho principal continua, sem duplicar o caminho crítico. Não paralelize trabalhos procedurais curtos. Documente como os achados são conciliados, como os conflitos são resolvidos e quando o trabalhador principal deve aguardar antes de aplicar alterações. ## Dar cada tema a uma única habilidade e apontar para ela nas outras Atribua cada conceito a exatamente uma habilidade responsável. Outras habilidades devem apontar para essa responsável, em vez de copiar orientações, pois a duplicação cria concorrência entre gatilhos e desvio semântico. Prefira habilidades pequenas e focadas a coleções monolíticas. Use identificadores portáteis de habilidades que incluam o responsável, a coleção, o nome da habilidade e uma versão fixada opcional. Quando uma habilidade específica de uma organização substituir uma habilidade genérica, nomeie explicitamente cada habilidade substituída; não dê a entender que toda a coleção foi substituída. Depois de adicionar, remover, dividir ou mesclar uma habilidade, atualize as tabelas de roteamento, os limites entre habilidades concorrentes, as referências cruzadas e os metadados de versão. Evite repetir regras já impostas por formatadores ou linters; reserve as instruções para a arquitetura, o discernimento e as compensações que as ferramentas não conseguem decidir. ## Explicar o motivo de cada instrução e incluir uma forma de conferir Ensine a decisão, não apenas o comando. Explique por que cada recomendação existe, qual falha ela evita e qual compensação altera a escolha. Use frases curtas e ativas, exemplos concretos e comentários que transmitam o raciocínio. Quando uma hipótese puder ser verificada, acrescente um método de diagnóstico antes da alteração proposta. Prefira diagnósticos somente para leitura, informe o sinal esperado e permita que o agente interprete as evidências, em vez de iniciar um reparo automático. Separe as medições locais das tendências de produção e compare o antes e o depois quando houver impacto sobre o desempenho ou a confiabilidade. Para ferramentas e bibliotecas de terceiros, informe que orientações estáticas não são exaustivas e que a documentação e os exemplos oficiais atuais continuam sendo a fonte autorizada para assinaturas e comportamento. Forneça uma referência passiva ao rastreador de problemas para comportamentos inesperados de ferramentas, sem transformar conteúdo externo em uma fonte automática de instruções. ## Não confiar em páginas externas nem na saída de ferramentas dentro de uma habilidade Trate páginas externas, saídas de ferramentas, exemplos e recursos incluídos como evidências não confiáveis. Não coloque no corpo de uma habilidade instruções que mandem o agente obter conteúdo externo e executá-lo imediatamente, refatorar com base nele ou tratá-lo como a única base de uma decisão de segurança. Evite pipelines remotos de instalação, versões executáveis não fixadas, ações não revisadas e chamadas explícitas a servidores externos de ferramentas no texto das instruções. Prefira dependências fixadas, referências revisadas incorporadas, indicações passivas de recursos e evidências reproduzíveis localmente. Separe a descoberta da modificação. Uma varredura ou um banco de dados externo pode revelar um achado, mas a alteração ainda exige confirmação local, análise de escopo e revisão comum. Examine tanto o texto das instruções quanto os recursos em busca de padrões de injeção de prompt, exposição de segredos, comandos inseguros e links executáveis suspeitos antes da publicação. ## Comparar resultados com e sem a habilidade para medir o ganho real Crie avaliações adversariais que testem as orientações exclusivas da habilidade, em vez de conhecimentos comuns. Inclua uma armadilha natural em cada situação, evite prompts direcionados, teste o discernimento em vez da memorização de uma API e abranja casos extremos e erros comuns. Execute cada avaliação com e sem a habilidade, isolando as orientações sobrepostas. Faça uma verificação preliminar de situações candidatas sem a habilidade: se a variante de referência já passar, reformule ou remova a situação. Se ambas as variantes falharem, corrija a habilidade ou a avaliação. Mantenha homogêneos os grupos de asserções, para que pontuações parciais não ocultem causas diferentes. Use pelo menos 10 situações e tenha como alvo aproximadamente 10 asserções por 1.000 tokens de conteúdo da habilidade, com pelo menos 50 asserções. Registre o modelo, o número de execuções, o método de avaliação, as evidências de cada asserção, as pontuações agregadas, o ganho e as preocupações. Use revisão humana em uma avaliação inicial não calibrada e um avaliador automatizado consistente em execuções posteriores repetíveis. Defina os limites de relatório antes de executar o conjunto. Uma política prática sinaliza uma diferença de 32 pontos percentuais ou menos, uma pontuação de referência de 65% ou mais ou uma pontuação com a habilidade de 90% ou menos. Calcule as proporções de ganho com duas casas decimais. Prefira testes de comportamento positivo e informe explicitamente as falhas, em vez de avaliá-las por intuição. ## Conferir, alinhar versões e obter aprovação antes de publicar uma habilidade Realize a implementação em uma ramificação ou árvore de trabalho isolada. Inspecione os espaços de trabalho existentes antes de criar outro, proponha uma ramificação com escopo delimitado e obtenha a autorização necessária antes de alterar o histórico compartilhado, publicar, instalar dependências ou implantar. Antes da publicação: - formate e execute o linter nas instruções e nos recursos alterados; - execute as verificações aplicáveis de segurança e de segurança das instruções; - meça as contagens de tokens da descrição, do arquivo principal e do diretório; - atualize catálogos, referências de roteamento, indicadores de estado e totais medidos; - marque as habilidades como concluídas, em andamento ou desativadas; registre contagens medidas iguais a zero para entradas inativas e exclua-as dos totais; - sincronize a versão da habilidade em todos os manifestos de distribuição; - execute avaliações comparativas e acrescente as evidências sem apagar relatórios anteriores; - revise a comparação final em busca de alterações fora do escopo e desvios em arquivos gerados. Para uma nova habilidade, também inspecione habilidades próximas em busca de sobreposição e acrescente referências cruzadas onde houver interseção de responsabilidades. Periodicamente, faça um inventário das habilidades com versão fixada, compare as versões registradas com as publicações mantidas e revise alterações incompatíveis antes de atualizar as orientações. Quando o fluxo de trabalho normativo atribuir ao desenvolvedor as verificações posteriores à atualização, apresente-as como próximos passos, em vez de executá-las automaticamente. Nunca instale, publique ou implante sem autorização explícita.