Criar um repositório de habilidades de agentes de IA que avaliam a qualidade de sites

## Dividir o repositório em uma habilidade por tema de qualidade web Trate o repositório como uma coleção de capacidades de agente autocontidas, não como um único arquivo monolítico de instruções. Separe auditorias amplas de habilidades específicas para desempenho, acessibilidade, capacidade de descoberta, qualidade geral e métricas da experiência do usuário, para que o agente carregue somente a capacidade necessária para a tarefa. Mantenha na raiz a documentação de todo o repositório, as regras de contribuição, as informações de licença e as orientações para agentes. Cada diretório de habilidade é responsável pelo arquivo principal de instruções, pelos scripts de automação e pelas referências detalhadas. Não esconda orientações para usuários, auxiliares executáveis ou material de origem em diretórios sem relação com eles. Antes de alterar uma habilidade, identifique o contrato de ativação, os arquivos sob sua responsabilidade, as dependências, o caminho de validação e a relação com outras habilidades. ## Nomear pastas e arquivos e preencher o cabeçalho do SKILL.md Forneça a cada habilidade um arquivo `SKILL.md` com frontmatter YAML válido que contenha: - um `name` em kebab-case; - um `description` de uma frase que informe quando usar a habilidade e inclua expressões de ativação realistas; - metadados de licença quando exigidos; - metadados estáveis de autor e versão quando o repositório os acompanhar. Use de forma consistente as convenções exatas de nomenclatura: - os diretórios de habilidades usam kebab-case; - o arquivo principal de instruções chama-se exatamente `SKILL.md`; - os scripts usam nomes em kebab-case e uma extensão executável adequada; - os arquivos de referência seguem a convenção de letras maiúsculas documentada pelo repositório. Mantenha o pacote autocontido e garanta que todos os caminhos mencionados pela habilidade sejam resolvidos dentro da estrutura de repositório compatível. ## Manter o SKILL.md abaixo de 500 linhas e levar detalhes para referências Mantenha a habilidade principal com menos de 500 linhas. Coloque a ativação, o fluxo de trabalho central, as restrições críticas e a navegação em `SKILL.md`; transfira explicações detalhadas, exemplos extensos e material especializado para as referências. Escreva orientações específicas e executáveis. Cada orientação deve conter um título curto, uma instrução direta e todos os valores ou limites necessários para aplicá-la. Prefira instruções que expliquem o que inspecionar, qual decisão tomar e qual evidência comprova a conclusão. Use scripts para trabalho determinístico ou repetitivo quando a saída consumiria o contexto de raciocínio. Não duplique o mesmo procedimento na habilidade principal e em várias referências. ## Mostrar código de antes e depois e tabelas de limites bons e ruins Mostre o padrão problemático e o corrigido sempre que uma orientação reger um comportamento executável. Mantenha os exemplos pequenos o bastante para serem entendidos isoladamente e verifique se realmente funcionam. Por exemplo, uma orientação sobre estabilidade de imagens deve comparar uma imagem com informações insuficientes a outra que declare dimensões e metadados úteis de carregamento: Problema: um elemento de imagem apenas com `src="hero.jpg"`. Melhoria: o mesmo elemento com `width="1200"`, `height="600"`, `alt="Hero image"` e `loading="lazy"`. Apresente limites de qualidade comparáveis em uma tabela com faixas explícitas para os níveis bom, intermediário e ruim. Informe a unidade e os operadores de limite para que os leitores não precisem deduzir se um limite é inclusivo. ## Escrever scripts de shell que param em erros e devolvem JSON Os auxiliares de shell devem interromper imediatamente em caso de falha, ser legíveis por máquina e permitir uma limpeza segura: - declare o shell pretendido com uma linha shebang; - ative um comportamento de interrupção imediata em caso de falha, como `set -e`; - envie mensagens de progresso e estado para o erro padrão; - envie resultados legíveis por máquina, como JSON, para a saída padrão; - crie arquivos temporários com segurança e registre traps de limpeza; - mantenha-os autocontidos ou documente todas as dependências externas e os pré-requisitos. Mantenha os diagnósticos destinados a pessoas fora do fluxo legível por máquina. Teste os comportamentos de sucesso, falha, entrada malformada e limpeza antes de tratar um auxiliar como automação reutilizável. ## Dedicar cada referência a um só tema e ligá-la a partir da habilidade Dedique cada referência a um único tópico, inclua exemplos práticos e links para o material canônico. Mantenha cada referência com menos de 200 linhas quando possível, para que o agente possa carregá-la de forma independente sem incorporar contexto não relacionado. Vincule todas as referências a partir da habilidade principal ou de um índice mantido. Remova links obsoletos e orientações duplicadas, e mantenha a fonte canônica mais próxima como responsável pelos fatos mutáveis. Use as referências para aprofundar o conteúdo, não como depósito indiscriminado. Uma referência deve ajudar o agente a tomar ou executar uma decisão específica. ## Conferir cabeçalho, exemplos, links e scripts antes de publicar uma habilidade Antes de enviar ou publicar uma habilidade: 1. Analise e valide o frontmatter YAML. 2. Confirme que a descrição contenha expressões de ativação utilizáveis. 3. Execute ou verifique de outra forma todos os exemplos executáveis. 4. Confirme que todos os arquivos referenciados existam e que todos os links internos sejam resolvidos. 5. Execute os scripts por meio da interface documentada e verifique o comportamento dos canais de saída. 6. Valide o pacote de acordo com a especificação aplicável de habilidades de agente. Considere uma verificação de sintaxe bem-sucedida necessária, mas insuficiente. A descrição de ativação, os exemplos, as referências e os scripts devem corresponder ao comportamento prometido pela habilidade. ## Ordenar problemas de crítico a baixo e não prender as orientações a um framework Classifique as constatações de forma consistente: 1. **Crítico:** vulnerabilidades de segurança ou falha funcional completa. 2. **Alto:** falhas graves de desempenho ou grandes barreiras de acessibilidade. 3. **Médio:** oportunidades significativas de desempenho, capacidade de descoberta ou qualidade de busca. 4. **Baixo:** estilo do código e pequenas oportunidades de otimização. Mantenha as orientações para a Web independentes de frameworks. Mostre primeiro HTML, CSS e JavaScript padrão, coloque observações específicas de frameworks em seções separadas e prefira as APIs padrão da plataforma, exceto quando uma dependência de framework for essencial para a tarefa. Revise os problemas de correção e as barreiras de acesso de maior impacto antes de dedicar esforço a melhorias de estilo. ## Atualizar uma habilidade sem quebrar as frases que a ativam Preserve a compatibilidade com versões anteriores ao atualizar as descrições das habilidades e mantenha as expressões de ativação existentes em funcionamento. Atualize os metadados de versão junto com a implementação e documente alterações incompatíveis no registro de mudanças ou na descrição do commit exigida pelo repositório. Quando a estrutura mudar, atualize em conjunto a habilidade principal, as referências afetadas, os scripts, os exemplos e os links. Revise a diferença final para detectar ampliações acidentais do escopo, material gerado obsoleto e instruções duplicadas. Execute novamente a lista de validação específica após cada mudança de comportamento. Não declare que uma habilidade atualizada está pronta enquanto o caminho de ativação, os exemplos ou os recursos referenciados ainda não tiverem sido verificados.