Organizar uma biblioteca de habilidades de IA para pesquisa e publicar só o que foi revisado

## Colocar cada habilidade em uma única etapa do processo de pesquisa Defina a missão da biblioteca antes de escolher suas pastas. Uma coleção voltada à pesquisa deve apoiar o caminho desde a pergunta e a revisão da literatura até a idealização, a preparação de dados, a experimentação, o treinamento, a avaliação, a implantação e a comunicação. Use categorias numeradas ou estáveis de outra forma que reflitam esse ciclo de vida. Mantenha uma habilidade central de orquestração que encaminhe o trabalho para habilidades especializadas sem duplicar suas orientações detalhadas. Para cada habilidade proposta: - Identifique a etapa do ciclo de vida e uma categoria responsável. - Declare o problema do usuário que ela resolve e as condições para usá-la. - Nomeie alternativas próximas e explique quando elas são mais adequadas. - Evite a sobreposição de escopo que faça a mesma tarefa parecer ter dois responsáveis. Trate a taxonomia como um contrato de navegação. Atualize o catálogo, as contagens, as descrições e o roteiro sempre que a responsabilidade ou o inventário mudar. ## Reunir todos os arquivos de uma habilidade em uma só pasta Dê a cada habilidade seu próprio diretório com um guia principal obrigatório. Adicione somente as pastas de apoio de que a habilidade precisa: - `references/` para documentação oficial detalhada, notas de API, tutoriais, padrões de problemas e histórico de versões. - `scripts/` para operações auxiliares repetíveis. - `templates/` para pontos de partida reutilizáveis. - `examples/` para implementações completas e representativas. - `assets/` para materiais que não sejam código e que sejam usados pelo guia. O guia principal é o ponto de entrada, não uma enciclopédia. Ele deve explicar o caminho operacional e vincular diretamente referências detalhadas que estejam um nível abaixo. Não crie cadeias em que uma referência encaminhe o leitor a outra para descobrir instruções obrigatórias. Mantenha dentro do pacote todos os arquivos necessários para executar a habilidade, para que a validação, a criação do arquivo compactado e a sincronização com o registro operem sobre um limite claro. ## Começar o guia principal com campos fixos como nome e versão Todo guia principal começa com um cabeçalho YAML válido que usa um contrato de campos fixo: - `name`: um identificador único em kebab-case, de preferência um gerúndio que descreva a atividade. - `description`: um texto em terceira pessoa que indique tanto o que a habilidade faz quanto quando deve ser usada. - `version`: uma versão semântica atualizada sempre que o comportamento ou a orientação mudar. - `author`: um valor de responsabilidade usado pela classificação da origem no registro. - `license`: a licença de distribuição. - `tags`: termos em estilo de título, enquanto siglas estabelecidas permanecem em maiúsculas. - `dependencies`: pacotes opcionais com restrições explícitas de versão. Não coloque valores escalares entre aspas, a menos que a sintaxe YAML exija. Mantenha as descrições abaixo do limite de caracteres configurado e evite identificadores vagos como helper, tools ou utilities. Valide o descritor por meio da análise sintática, não por inspeção visual. Trate campos obrigatórios ausentes, versões inválidas, nomes duplicados e dependências malformadas como erros bloqueadores. ## Manter o guia principal curto e levar os detalhes para arquivos de referência Estabeleça de 200 a 500 linhas como objetivo para o guia principal. Se a orientação essencial ultrapassar 500 linhas, transfira os detalhes avançados para arquivos de referência diretos, em vez de eliminar decisões necessárias ao comprimir o texto ou permitir que o ponto de entrada cresça sem limites. O guia deve conter: - Uma finalidade concisa e condições claras de acionamento. - Uma comparação com alternativas relevantes. - Dois ou três fluxos de trabalho completos para casos de uso complexos. - Listas de verificação prontas para copiar quando a sequência for importante. - Exemplos concretos de entrada e saída. - Ciclos de feedback que validem, corrijam e repitam trabalhos críticos para a qualidade. - Uma seção de problemas comuns com soluções específicas. Pressuponha um leitor competente. Explique escolhas específicas do domínio e modos de falha, não conceitos básicos já implícitos na tarefa. Dê um identificador de linguagem a todo exemplo de código delimitado. Crie referências substanciais com base em fontes confiáveis e um objetivo explícito de cobertura, como aproximadamente 300 KB, quando o domínio justificar. Não infle documentos para atingir uma métrica de tamanho; a completude, a rastreabilidade e a utilidade prática continuam sendo o objetivo. ## Adicionar ou melhorar habilidades seguindo sempre os mesmos passos Para uma nova habilidade: 1. Selecione um item aprovado do roteiro e a categoria responsável. 2. Crie a estrutura padrão do pacote. 3. Escreva e valide o descritor antes de ampliar o corpo. 4. Crie os principais fluxos de trabalho e orientações para decisões. 5. Adicione referências diretas, recursos auxiliares, modelos e exemplos conforme necessário. 6. Teste a habilidade em tarefas reais representativas. 7. Atualize o catálogo, as estatísticas e o roteiro na mesma alteração. Para uma habilidade existente, preserve o contrato do descritor, incremente a versão, mantenha o guia principal dentro do limite, adicione fluxos de trabalho ou soluções de problemas ausentes e execute novamente casos de uso representativos. Use uma ramificação de funcionalidade e uma solicitação de revisão bem delimitada. Inclua o pacote inteiro e suas alterações de catálogo no mesmo commit para que o repositório nunca anuncie uma habilidade incompleta. ## Verificar as habilidades com checagens automáticas e tarefas reais Execute verificações mecânicas antes da revisão: - Confirme que o arquivo principal existe e que seu cabeçalho pode ser analisado. - Compare o número de linhas do guia principal com o objetivo de 200 a 500. - Verifique se todo bloco de código declara uma linguagem. - Meça a cobertura das referências em relação ao objetivo escolhido. - Confira se os arquivos referenciados existem exatamente um nível abaixo do guia principal. - Confirme que nomes, etiquetas, versões e dependências seguem seus esquemas. Em seguida, faça a validação comportamental: - Execute cada fluxo de trabalho principal com entradas realistas. - Verifique as saídas e as etapas de recuperação declaradas. - Provoque pelo menos uma falha comum. - Confirme que uma alternativa seja recomendada quando a habilidade não for a ferramenta certa. - Repita depois de qualquer edição substancial. Uma pasta de referências grande não compensa um fluxo de trabalho vago, e uma visão geral refinada não compensa exemplos inutilizáveis. ## Enviar automaticamente ao registro as habilidades alteradas após a aprovação Após uma alteração aprovada na ramificação padrão, detecte quais pacotes de habilidades de nível superior mudaram. Para cada pacote alterado: 1. Exija o guia principal e analise seu descritor. 2. Classifique a origem conforme a política de responsabilidade declarada. 3. Arquive o pacote completo, excluindo arquivos ocultos do sistema operacional e do controle de versão. 4. Envie o arquivo para o espaço de nomes correspondente do registro. 5. Crie ou atualize a entrada correspondente no registro. 6. Informe pacotes ignorados ou que falharam sem tratá-los silenciosamente como sincronizados. Armazene os valores do endpoint e da autenticação somente no repositório de segredos da plataforma de automação. Ofereça um acionamento manual para recuperação e testes, mas garanta que a mesma lógica de validação e empacotamento seja executada nos modos automático e manual. Verifique o fluxo de trabalho com uma alteração versionada inofensiva, inspecione a execução da automação, confirme a entrada no registro e o arquivo e evite usar edições não revisadas apenas para acionar a esteira. ## Publicar um pacote novo só quando o número da versão muda Oriente a publicação do pacote por uma alteração de versão no descritor do pacote da ramificação padrão. Uma alteração somente no arquivo de bloqueio não deve publicar uma nova versão. Use o comando de versão do gerenciador de pacotes para que o descritor e o arquivo de bloqueio avancem juntos. Selecione uma versão de correção, secundária ou principal conforme a compatibilidade e suprima etiquetas automáticas do controle de versão somente quando o processo de publicação do repositório exigir um commit separado. Autentique-se por meio de um publicador confiável configurado, em vez de um token de registro de longa duração. Anexe a procedência da compilação ou uma certificação equivalente da cadeia de suprimentos a todo artefato publicado. Antes da publicação, verifique: - A identidade do publicador confiável corresponde exatamente aos nomes do repositório e do fluxo de trabalho. - As variáveis de ambiente não substituem a autenticação confiável por um token obsoleto. - Uma instalação limpa é concluída com sucesso a partir do arquivo de bloqueio incluído no commit. - A nova versão é diferente da revisão anterior. - O conteúdo do pacote corresponde à fonte revisada. Se a publicação for ignorada ou a autenticação falhar, corrija a verificação de versão ou a identidade confiável; não contorne a procedência. ## Melhorar as habilidades existentes em vez de criar mais Avalie a biblioteca pelo conhecimento especializado executável, não pelo número de diretórios. Uma habilidade útil condensa práticas confiáveis em um formato que um agente possa seguir e verificar e que permita a recuperação. Antes de integrar, confirme: - O escopo se encaixa em uma categoria e não duplica um responsável existente. - As regras de descritor, nomenclatura e versão passam na verificação. - O guia principal permanece focado e todos os detalhes obrigatórios continuam acessíveis. - Fluxos de trabalho, listas de verificação, exemplos, alternativas e soluções de problemas estão presentes onde necessário. - Tarefas reais validam a orientação. - O catálogo, o roteiro, a automação de arquivamento e os dados de publicação do pacote permanecem consistentes. Prefira aprimorar uma habilidade existente a adicionar outra quase duplicada. Prefira um fluxo de trabalho completo com um ciclo de feedback funcional a muitos exemplos superficiais. Quando uma métrica entrar em conflito com clareza ou correção, preserve a orientação útil para decisões e documente por que a métrica não era um indicador substituto adequado.