hackycy/init-agents-md

Inicializar AGENTS.md

Cria um guia de contribuidores para a raiz do repositório ou um diretório existente. A única fonte de formato de saída e seções recomendadas é references/agents-md-prompt.md; esta skill é responsável por aplicar com segurança essas instruções fixas ao escopo correto.

Entrada e Escopo

• Aceita zero ou um argumento de diretório; caminhos relativos são resolvidos a partir do diretório de trabalho atual. Sem argumento, usa a raiz do Git encontrada com git rev-parse --show-toplevel.
• O diretório explícito pode não estar em um repositório Git; sem argumento e sem raiz do Git encontrada, solicita que o usuário especifique um diretório e para. O caminho deve resolver para um diretório legível; caminhos ausentes, arquivos, diretórios ilegíveis ou múltiplos argumentos de diretório fazem a skill parar.
• O candidato de saída padrão é o AGENTS.md naquele diretório. Processa apenas um escopo por vez, não cria diretórios, não modifica outros arquivos, não faz staging, commit ou cria branches.
• O corpo segue o idioma principal da documentação local; se o sinal for insuficiente, usa inglês. Se o diretório selecionado não for a raiz do repositório, a saída adiciona ## Escopo no início, explicando o diretório relativo e as diretrizes pai aplicáveis, escrevendo apenas regras novas ou mais restritivas.

Primeiro Reconhecimento, Depois Geração

1. Antes de rascunhar, leia o alvo e o contexto necessário do projeto: estrutura de diretórios, manifest/lockfile, scripts, configurações de build/test/lint, CI, README/CONTRIBUTING e, quando Git estiver disponível, até 30 commits relevantes. Identifique limites de pacotes em monorepo, gerenciador de pacotes e idioma principal da documentação local.
2. Encontre todos os AGENTS.md relevantes: o arquivo alvo, arquivos ancestrais da raiz do repositório até o diretório pai do alvo, e arquivos aninhados na subárvore do alvo. Para diretórios não-Git, verifique a cadeia de ancestrais. A subárvore primeiro verifica subdiretórios imediatos; expande apenas se manifest, limites de pacotes ou guias existentes apontarem para níveis mais profundos; pula .git, dependências/vendor, saídas de build/coverage, cache e armazenamento de segredos ignorados.
3. Marque as correspondências como target, ancestor ou nested, e leia CLAUDE.md, CONTRIBUTING.md e outras guias relevantes como restrições. Guias aninhadas são apenas lidas, preservadas e, se necessário, referenciadas; não são mescladas ou modificadas.
4. Verifique apenas nomes e metadados de possíveis arquivos de segredos. Nunca leia ou escreva chaves, tokens, credenciais ou conteúdo de .env.
5. Cada comando e convenção deve ser verificável por scripts, configurações, arquivos existentes ou histórico. Diferencie regras observadas no repositório de recomendações genéricas padrão; seções, comandos ou afirmações sem evidência são omitidos diretamente.

Confirmação de Guias Correspondentes

Antes de gerar o rascunho, exiba todas as correspondências, seus respectivos escopos e o caminho de saída candidato, e verifique conflitos de capitalização (por exemplo, agents.md). Esta é uma barreira rígida:

• Se o candidato alvo já existir, leia-o e solicite que o usuário escolha merge, replace ou abort.
• Se o alvo não existir, mas guias ancestrais ou aninhadas forem encontradas, solicite que o usuário escolha explicitamente "Criar nova guia para este escopo" ou "Atualizar uma guia existente nomeada"; não adicione silenciosamente arquivos filhos. Se escolher outro arquivo existente, faça novo reconhecimento no diretório desse arquivo e depois escolha o modo.
• Se não houver correspondências, continue a rascunhar um novo arquivo para o alvo original.
• Pare e relate o motivo se o AGENTS.md selecionado for um link simbólico, diretório, arquivo especial ou arquivo comum não gravável.

Qualquer pergunta não respondida, escolha ambígua ou conflito com guias como CLAUDE.md mantém o espaço de trabalho inalterado.

Ler Instruções Fixas

Leia references/agents-md-prompt.md completamente antes de começar a rascunhar. Ele é o proprietário canônico dos títulos, requisitos de documentação, seções recomendadas, meta de contagem de palavras e estilo de expressão; não o modifique durante a execução normal, nem copie seu corpo nesta skill.

Mesclagem, Pré-visualização e Escrita

merge mescla com base na semântica de títulos Markdown: preserva fatos existentes e seções personalizadas, apenas adiciona conteúdo faltante com evidência. Liste todos os comandos, caminhos, prioridades ou conflitos de fato em uma tabela e deixe o usuário escolher item por item entre manter existente, usar evidência ou fornecer texto personalizado; não escreva enquanto houver conflitos não resolvidos. replace afeta apenas o único arquivo selecionado, sem gerar backup automaticamente.

Novos arquivos mostram o rascunho completo; atualizações mostram um diff unificado, com caminho, escopo, seções, contagem de palavras, lacunas de evidência e resumo do modo. Não crie ou modifique arquivos até que o usuário confirme explicitamente a escrita final; se forem solicitadas modificações, volte ao rascunho e pré-visualização. Antes de escrever, releia o alvo; se o conteúdo foi alterado externamente, siga novamente o fluxo de confirmação.

Validação e Conclusão

Antes de escrever, verifique títulos, hierarquia de títulos, links de escopo de guias aninhadas, caminhos/scripts referenciados, placeholders, valores sensíveis e espaçamento Markdown; a guia raiz é verificada conforme a meta de contagem de palavras das instruções fixas, e incrementos aninhados são verificados por aproximadamente 100–300 palavras. Corrija automaticamente apenas problemas mecânicos como espaços à direita, linhas em branco duplicadas, etc., e pré-visualize novamente; problemas semânticos ou factuais são deixados para o usuário decidir. Se o alvo estiver em Git, execute git diff --check; caso contrário, faça uma verificação de espaçamento equivalente; não execute build, teste ou lint completos por padrão para esta skill.

Condição de conclusão: o AGENTS.md confirmado existe no caminho selecionado, passa pela verificação estática, corresponde à pré-visualização aprovada; relatório final informa modo, escopo, comandos verificados, itens omitidos/incertos e resultado da validação. Se o usuário abortar ou a validação falhar, relate o motivo e mantenha o alvo inalterado.