Criar e manter uma biblioteca de habilidades que funcione com qualquer IA

## Organizar as pastas para que os detalhes de cada habilidade carreguem só no uso Forneça a cada habilidade um diretório próprio com um arquivo principal de instruções, os metadados obrigatórios e diretórios opcionais de referências e scripts. Mantenha exemplos completos, material de pesquisa, templates canônicos e documentação de toda a coleção em locais claramente separados. Mantenha um mapa de habilidades na raiz para que um usuário ou agente possa descobrir a coleção sem carregar o corpo de todas as habilidades. Trate nomes e descrições como o índice de inicialização. Carregue instruções detalhadas, referências e scripts somente quando uma habilidade for ativada. Essa estrutura preserva a atenção para a tarefa atual e mantém o material mais profundo disponível quando necessário. ## Manter curto o arquivo principal de cada habilidade e útil em qualquer ferramenta Mantenha o arquivo principal de instruções de uma habilidade abaixo de 500 linhas e transfira o material detalhado para as referências. Exija metadados YAML com os campos name e description, escreva description na terceira pessoa, use nomes de diretório em letras minúsculas separados por hífens e questione o valor informativo de cada parágrafo. Considere que o público é avançado, a menos que a habilidade ensine explicitamente os fundamentos. Escreva orientações independentes de plataforma. Abstraia ferramentas específicas de fornecedores, exceto quando uma restrição de plataforma for essencial, e crie exemplos portáteis em vez de apresentar pseudocódigo conceitual como código pronto para produção. ## Escrever quando usar cada habilidade e quando não usar Inclua seções para condições de ativação, conceitos centrais, orientação prática, exemplos, diretrizes, armadilhas, integração e referências. Toda seção de ativação deve declarar gatilhos positivos e um limite de não ativação que encaminhe trabalhos adjacentes para a habilidade correta. Dê peso especial às armadilhas obtidas pela experiência, pois elas registram modos de falha que orientações genéricas costumam deixar passar. Nas orientações de integração, mencione outras habilidades por nomes estáveis em texto simples quando links puderem falhar entre diferentes layouts de instalação. ## Ao mudar uma habilidade, atualizar as listas e a fonte dos seus números Ao adicionar ou alterar uma habilidade, atualize em conjunto a visão geral da coleção, os manifestos de distribuição e o índice do corpus. Relacione a habilidade a seus cenários de ativação, mecanismos de comportamento reutilizáveis e alegações de apoio, para que descoberta, empacotamento e avaliação descrevam o mesmo artefato. Registre a procedência de alegações numéricas, de benchmark, voláteis ou relacionadas ao desempenho de um fornecedor. Atualize os registros de mecanismos e alegações sempre que uma habilidade introduzir uma mudança de comportamento reutilizável ou uma alegação sensível a evidências; não deixe essas relações implícitas no texto. ## Rodar verificações automáticas antes de pedir o julgamento de uma IA Antes de aceitar uma alteração, execute as verificações declaradas pelo repositório para análise de metadados, schema e estrutura estrita do corpus, layouts de instalação compatíveis entre plataformas, integridade do corpo das habilidades, limites de ativação e benchmarks adversariais. Trate essas verificações como controles de revisão, não como diagnósticos opcionais. Valide primeiro, de modo determinístico, a estrutura, a sincronização de manifestos, a aritmética das rubricas, o estado de recuperação e o formato dos registros. Use julgamento baseado em modelo somente depois que essas verificações passarem e não use um modelo para justificar uma falha estrutural reproduzível. ## Usar os comandos de instalação e teste próprios de cada projeto de exemplo Não invente um sistema de build de nível superior quando o repositório não tiver um. Identifique o runtime e o gerenciador de pacotes declarados por cada exemplo ou subprojeto e use seus próprios comandos de setup, build, test, lint, format e type-check. Mantenha ambientes e dependências limitados a esse subprojeto. Execute o menor comando pertinente durante as iterações e conclua o conjunto de controles documentado pelo subprojeto antes da revisão. Diferencie compilação, testes unitários, testes assíncronos, linting, formatação e verificação estática de tipos, em vez de tratar o sucesso de um único comando como prova de que todos os controles passaram. ## Avançar cada pesquisa em etapas fixas com a ferramenta prevista Inicialize cada execução de pesquisa pela ferramenta de ciclo de vida fornecida, para que ela crie de forma consistente o arquivo de estado, a entrada da fila, o log da thread, a estrutura de avaliação das fontes e o template de proposta de mecanismos. Avance por recuperação, avaliação, proposta, revisão de novidade, validação da execução, prontidão para revisão e encerramento usando transições aceitas; nunca edite manualmente o estado da execução. Valide as execuções ativas de forma independente dos controles gerais do repositório. Promova um mecanismo proposto somente depois que a execução estiver pronta, o revisor obrigatório estiver registrado e a verificação de prontidão passar. Adicione a procedência de uma alegação antes que uma alegação numérica, de benchmark ou volátil entre em uma habilidade. ## Não usar IA paga na pesquisa automática até haver um orçamento Disponibilize comandos determinísticos para descoberta, avanço de uma etapa, processamento diário e relatório de status, seja o ciclo iniciado manualmente ou por um agendador específico da plataforma. Mantenha a recuperação utilizável sem chamadas a modelos pagos e não invoque modelos pagos em ciclos não supervisionados até que exista um controle orçamentário explícito. Trate filas, logs de runtime, snapshots, relatórios de status, revisões estacionadas, fluxos de eventos, falhas e diretórios comuns de execução como estado operacional, não como código-fonte. Nunca os inclua em um commit, exceto em uma execução seed designada deliberadamente. ## Distribuir habilidades relacionadas em um só pacote, sem cópias Quando um host armazenar em cache separadamente o código-fonte de cada plugin, distribua uma coleção de habilidades relacionadas em um único pacote, em vez de apontar vários pacotes para a mesma árvore de código-fonte. Isso evita caches redundantes e preserva um único limite coerente de versão e manifesto. Na inicialização, exponha somente os metadados necessários para descoberta. Adie o carregamento do corpo completo das habilidades e dos recursos de apoio até a ativação, para que a abrangência do pacote não se torne uma sobrecarga permanente de contexto. ## Dar menos material à IA e pedir autorização a uma pessoa antes de enviar alterações ao repositório compartilhado (push) Prefira a qualidade do contexto à quantidade: a atenção limitada e a perda de informação em posições intermediárias significam que mais material pode reduzir o desempenho. Use subagentes para isolar a atenção em trabalhos delimitados, não apenas para imitar funções organizacionais. Mantenha exemplos conceituais portáteis, como pseudocódigo independente de linguagem ou amplamente legível. Coloque evidências determinísticas antes do julgamento do modelo e mantenha a publicação remota sob controle humano. Os agentes podem preparar alterações e passar por todos os controles locais, mas devem obter aprovação humana explícita antes de executar push ou merge.