Escrever e publicar habilidades de agente que sejam acionadas certo e passem na validação

## Limitar a descrição ao que a habilidade faz e quando usá-la Trate a descrição como metadados de roteamento, não como um procedimento compactado. Os agentes podem escolher uma habilidade pela descrição antes de ler o corpo completo; por isso, etapas de processo inseridas nela podem substituir ou contornar o fluxo de trabalho detalhado. Escreva as descrições como uma breve declaração de capacidade seguida das condições de acionamento: o que a habilidade faz e quando deve ser usada. Mantenha a descrição dentro do limite do esquema ativo, incluindo o máximo de 1,024 caracteres quando esse limite se aplicar. Nunca coloque etapas ordenadas, sequências de implementação ou procedimentos de solução de problemas na descrição; deixe todas as orientações práticas no corpo da habilidade. Teste as descrições com solicitações realistas para confirmar que elas são acionadas nos pedidos pretendidos, permanecem inativas em trabalhos não relacionados e conduzem o agente às instruções completas. ## Usar só campos de cabeçalho da especificação e referências válidas a outras habilidades Siga a especificação de habilidades ativa em vez de copiar campos de um repositório vizinho. Mantenha no nível superior apenas os campos definidos pela especificação, incluindo `name` e `description`; use `license` e `allowed-tools` somente de acordo com o contrato do repositório. Quando presente, `allowed-tools` deve ser uma lista delimitada por espaços. Coloque os campos específicos do repositório sob `metadata`. Restrinja os nomes a letras, números e hifens. Valide o tamanho das descrições e a redação dos acionadores. Mantenha metadados estruturados, como autor, versão semântica, domínio, acionadores, função, escopo, formato de saída e habilidades relacionadas, dentro das enumerações e dos formatos definidos pelo repositório. Cada entrada de habilidade relacionada deve apontar para um diretório de habilidade existente. Use de forma consistente o valor de licença aprovado pelo repositório; quando o repositório fixar a licença como MIT, escreva exatamente `license: MIT`. Não aceite valores de enumeração desconhecidos, referências quebradas ou campos personalizados no nível superior apenas porque o analisador de YAML os aceita. ## Manter curto o arquivo principal e levar os detalhes para arquivos de referência Mantenha o arquivo principal da habilidade compacto o suficiente para ser carregado como contexto de roteamento e operação. Uma primeira camada prática tem aproximadamente de 80 a 100 linhas e contém a função, as orientações de acionamento, um fluxo de trabalho central de cinco etapas, os comportamentos obrigatórios e proibidos e uma tabela de roteamento para referências mais detalhadas. Coloque o material técnico detalhado em arquivos de referência específicos de segunda camada, normalmente com 100 a 600 linhas cada. Cada referência deve abordar um tema, incluir exemplos funcionais completos com os tipos relevantes, explicar casos extremos e antipadrões e indicar quando as orientações devem ou não ser usadas. Carregue apenas as referências exigidas pela tarefa atual. Crie links cruzados para habilidades relacionadas quando for útil, mas não duplique todo o conteúdo delas. Considere a redução do uso de contexto como um resultado de projeto; uma estrutura de duas camadas bem roteada pode ter como objetivo uma redução de cerca de 50% sem omitir instruções necessárias. ## Usar nos exemplos os mecanismos próprios de cada framework As orientações específicas de um framework devem usar os mecanismos estabelecidos por ele. Se o framework oferece tratamento global de erros, middleware, injeção de dependência, ganchos de ciclo de vida ou outra abstração integrada, os exemplos devem usar esse mecanismo em vez de recriá-lo manualmente. Não imponha uma única arquitetura genérica a frameworks não relacionados apenas para obter consistência visual em todo o repositório. As convenções do framework para tratamento de erros, organização, testes e integração têm precedência. Mantenha os exemplos de referência completos e executáveis, com tipos quando a linguagem oferecer suporte a eles. Revise os exemplos de acordo com a versão do framework no escopo e rejeite padrões que dupliquem comportamentos integrados ou ocultem restrições específicas do framework. ## Terminar cada arquivo de habilidade com um único link para a documentação Todo arquivo de habilidade deve terminar com exatamente um link de retorno canônico para a documentação em sua última linha. Use a sintaxe de link do Markdown com o rótulo `Documentation` e a URL canônica, não uma URL simples, para que renderizadores rigorosos produzam um hiperlink real. Derive o caminho canônico de metadados estáveis, como `metadata.domain`, e do nome do diretório da habilidade. Aplique o domínio alternativo documentado quando não houver metadados. Ao adicionar ou renomear uma habilidade, atualize juntos o diretório, o domínio e o link de retorno; caso contrário, o link publicado pode levar a uma página inexistente. Considere explicitamente várias superfícies de publicação. Agregadores de arquivos brutos podem precisar do link de retorno para facilitar a descoberta, enquanto a compilação da documentação pode excluir o mesmo link para si própria das páginas geradas, dos espelhos e dos índices para modelos de linguagem. Preserve os dois comportamentos na etapa de sincronização e teste o destino renderizado. ## Verificar sobreposições e atualizar referências ao criar ou mudar uma habilidade Para uma nova habilidade: 1. Verifique se há responsabilidades sobrepostas entre as habilidades existentes. 2. Escreva a habilidade principal com metadados de capacidade e acionamento, deixando as etapas do processo no corpo. 3. Adicione referências específicas para o conteúdo aprofundado. 4. Adicione uma tabela de roteamento dos temas para as referências. 5. Acrescente o único link de retorno canônico para a documentação como última linha. 6. Teste solicitações que devem acionar e que não devem acionar a habilidade. 7. Atualize o guia de habilidades e os índices de domínio quando a taxonomia mudar. Antes de modificar uma habilidade, leia todo o corpo atual e as referências afetadas pela mudança. Preserve o formato da descrição baseado em capacidade e acionamento e a arquitetura de divulgação progressiva. Atualize as tabelas de roteamento, as referências a habilidades relacionadas, os índices de documentação e os testes de acionamento sempre que nomes, escopo, acionadores ou dependências mudarem. ## Sincronizar contagens e registro de alterações com um só arquivo de versão Use um único manifesto de versão como fonte oficial para a versão de publicação e para contagens calculadas, como as de habilidades, fluxos de trabalho e arquivos de referência. Execute a ferramenta de atualização do repositório para recalcular as contagens com base no sistema de arquivos e sincronizar a documentação gerada. Ofereça modos de verificação e de simulação para que a CI e os revisores detectem divergências sem fazer gravações. Adicione a nova versão ao início do registro de alterações usando uma estrutura estável de Added, Changed e Fixed e mantenha o link de comparação de versões. Atualize guias, árvores de decisão, tabelas de comandos e referências cruzadas para conteúdos novos ou modificados antes de gerar novamente a documentação agregada. Gere novamente os recursos para redes sociais que exibem contagens somente quando as contagens incorporadas mudarem; uma correção que altere apenas a versão não exige um novo recurso. Revise as diferenças geradas para evitar que a automação oculte mudanças não relacionadas. ## Rodar os validadores de habilidades e de Markdown antes de publicar Execute o validador de integridade das habilidades antes da publicação. Ele deve verificar a análise de YAML, os campos obrigatórios, o formato do nome, o tamanho da descrição e a cláusula de acionamento obrigatória `Use when`, a existência do diretório de referências, a estrutura das referências e a consistência das contagens. Ofereça verificações com escopo limitado a uma habilidade ou a uma família de validação, além de resultados legíveis por máquina para a CI. Execute um validador de Markdown separadamente. Verifique comentários HTML que quebrem tabelas, blocos de código não fechados, linhas separadoras de tabela ausentes e contagens de colunas inconsistentes. Valide todo o repositório após a investigação direcionada. Considere o código de saída 0 como sucesso e o código de saída 1 como falha de validação, analisando explicitamente os avisos. Nunca publique uma versão com erros de validação não resolvidos apenas porque uma verificação de escopo mais restrito foi aprovada. ## Registrar comandos e resultados antes de dizer que a publicação está pronta Após a sincronização e a validação, procure referências de versão desatualizadas, excluindo o histórico intencional do registro de alterações. Confirme manualmente que as descrições, os testes de acionamento, as tabelas de roteamento, as referências a habilidades relacionadas, os links de retorno canônicos, as contagens geradas e os recursos condicionais correspondem à publicação. Preserve as atribuições de terceiros, os avisos de licença e as referências de pesquisa quando padrões de comportamento ou disciplina de processo tiverem sido adaptados de outros trabalhos. Não perca a procedência durante a limpeza. Registre os comandos exatos de atualização e validação, seus resultados, os avisos analisados e qualquer etapa condicional omitida intencionalmente. Informe que a publicação está pronta somente depois que todos os validadores obrigatórios forem aprovados e a diferença final não contiver mudanças sem explicação.