rfdiosuao/AgentSkill

README do Repositório Craft

Transforme um repositório em uma página de destino clara e confiável. Baseie cada afirmação, comando, badge e link no projeto real; o polimento visual nunca deve superar a precisão.

Escolha o modo de operação

• Use o modo auditoria quando o usuário solicitar apenas feedback. Inspecione e relate; não edite ou publique.
• Use o modo construção quando o usuário solicitar a criação ou melhoria do README. Edite o repositório e valide o resultado.
• Use o modo publicação somente quando o usuário solicitar commit, push, abertura de pull request ou atualização das configurações do repositório. Siga o fluxo de trabalho Git normal do repositório.

1. Inspecione o projeto real

Antes de rascunhar, inspecione:

• Documentos existentes como README*, contribuição, segurança, licença, changelog e implantação.
• Manifestos de pacotes, pontos de entrada, arquivos de ambiente de exemplo, comandos de teste, capturas de tela, logotipos e URLs públicas.
• Remote Git, branch padrão, tags de release, workflows de CI e configuração de hospedagem.
• Instruções em nível de repositório, como AGENTS.md ou CONTRIBUTING.md.

Derive o nome do produto, proposta de valor em uma frase, público-alvo, plataformas suportadas, comandos de instalação, comandos de execução e história de implantação a partir de evidências. Se um fato material não puder ser verificado, omita-o ou rotule-o claramente como planejado.

2. Execute uma verificação de escopo público e segurança

Trate o trabalho do README como uma revisão de release. Antes de expor detalhes:

• Pesquise arquivos rastreados e alterações em staging em busca de chaves de API, chaves privadas, tokens, senhas, cookies, nomes de host internos, IPs privados e caminhos pessoais.
• Nunca cole segredos de configuração local, histórico de chat, histórico de shell ou arquivos de implantação.
• Vincule a .env.example; nunca reproduza valores de .env.
• Confirme que capturas de tela, QR codes, nomes e links de contato são intencionalmente públicos.
• Preserve licenças, marcas registradas, atribuições e avisos de ativos de terceiros.

Pare e sinalize um bloqueador concreto se a publicação expor material sensível.

3. Projete a história antes da decoração

Escreva o README para esta sequência:

1. Reconhecer — nome, logotipo, promessa concisa.
2. Confiar — um pequeno conjunto de badges verdadeiros e um visual real do produto.
3. Entender — o que faz, para quem é e sua principal diferença.
4. Experimentar — o caminho mais curto verificado do clone ao resultado funcional.
5. Adotar — configuração, implantação, arquitetura, limitações e suporte.
6. Participar — contribuição, segurança, licença, patrocinadores e comunidade.

Leia references/readme-patterns.md antes de reconstruir um layout de README ou selecionar badges.

4. Construa um cabeçalho compacto com marca

Use esta ordem quando o projeto tiver os ativos para suportá-la:

1. Logotipo vinculado com texto alternativo descritivo e tamanho de exibição moderado.
2. Nome do projeto e proposta de valor em uma linha.
3. Quatro a oito badges significativos.
4. Links primários, como demonstração ao vivo, documentação, rastreador de problemas ou download.
5. Navegação opcional dentro da página para um README longo.
6. Uma imagem hero forte, captura de tela do produto ou demonstração curta.

Prefira ativos de propriedade do repositório sob um caminho estável docs/, .github/ ou assets/. Reutilize um logotipo existente antes de gerar um novo. Se o usuário solicitar um novo visual e uma skill de geração de imagem estiver disponível, use-a e, em seguida, otimize o resultado para exibição no repositório.

Não use badges de build falsos, métricas de placeholder, paredes gigantes de badges, contadores decorativos ou ativos com hotlink que o projeto não controla.

5. Selecione apenas seções úteis

Um projeto compacto normalmente precisa de:

• O que é e por que existe.
• Destaques de recursos baseados em comportamento implementado.
• Quickstart com comandos copiáveis e testados.
• Configuração usando placeholders seguros.
• Capturas de tela ou demonstração quando a prova visual ajuda materialmente.
• Notas de implantação ou produção quando o projeto é implantável.
• Links para contribuição, segurança, licença e agradecimentos quando esses arquivos existem.

Adicione arquitetura, referência de API, compatibilidade, roadmap, FAQ ou solução de problemas apenas quando o projeto os justificar. Não crie seções de boilerplate vazias.

Para projetos chineses, escreva chinês natural primeiro e mantenha os identificadores técnicos em sua forma original. Adicione uma versão em inglês apenas quando solicitado ou quando o repositório já mantiver uma.

6. Adicione patrocínio sem atrapalhar a história do produto

Quando o usuário fornecer e autorizar uma imagem de patrocinador ou QR code:

• Copie-o para um caminho de ativo estável de propriedade do repositório.
• Use um título claro como 支持项目 ou Patrocinador próximo à parte inferior do README.
• Adicione texto alternativo, uma largura razoável e uma frase explicando o que o suporte financia.
• Nunca altere, decodifique ou regenere um QR code de pagamento, a menos que explicitamente solicitado.

Não deixe o patrocínio superar o quickstart, a documentação ou as informações de segurança.

7. Verifique o README como documentação executável

Execute os comandos de build, teste, lint ou smoke relevantes do projeto quando prático. Em seguida, execute o verificador incluído:

python3 craft-repository-readme/scripts/validate_readme.py \
  --repo-root . \
  --readme README.md

Adicione flags estritas quando os elementos correspondentes forem necessários:

python3 craft-repository-readme/scripts/validate_readme.py \
  --repo-root . \
  --readme README.md \
  --require-logo --require-badges --require-hero --require-sponsor

Verifique também manualmente:

• Cada comando de instalação e execução corresponde ao repositório.
• Links de imagens e documentos relativos resolvem com caminhos sensíveis a maiúsculas/minúsculas do GitHub.
• Links externos usam os domínios canônicos pretendidos.
• Âncoras de cabeçalho e links do sumário funcionam.
• Imagens têm texto alternativo descritivo e dimensões razoáveis.
• O README renderiza bem tanto em desktop quanto em telas estreitas.
• Nenhum segredo, placeholder, caminho absoluto local ou afirmação não verificada permanece.

8. Publique deliberadamente

Quando a publicação estiver no escopo:

• Revise git diff e mantenha alterações não relacionadas fora do commit.
• Faça commit com uma mensagem focada e envie através do fluxo de trabalho normal do repositório.
• Prefira um pull request quando as proteções de branch ou práticas de colaboração exigirem um.
• Atualize a descrição do GitHub, homepage, tópicos e visualização social apenas quando o usuário solicitou alterações nas configurações do repositório e os valores são verificados.
• Reabra o README renderizado no GitHub após a publicação e verifique imagens, badges, links e layout móvel.

Critérios de conclusão

• A primeira tela comunica nome, propósito, sinais de confiança e a próxima ação principal.
• Todas as afirmações e comandos proeminentes são verificados em relação ao repositório.
• Logotipo, hero, badges e conteúdo de patrocínio são intencionais, não ornamentais.
• Links e ativos locais resolvem.
• Nenhum segredo ou detalhe de ambiente privado é exposto.
• A validação passa e a etapa de publicação solicitada está completa.