devetai/better-skill-gen

Better Skill Generator (better-skill-gen)

Este skill atua como um Meta-Skill: recebe uma ideia, problema ou fluxo de trabalho do usuário, juntamente com o usuário finaliza o design e, em seguida, gera um diretório de Skill completo para cada provedor selecionado:

Provedor	Diretório (escopo do projeto)	Características
Codex e Antigravity	.agents/skills/<skill-name>/ (uma versão compartilhada)	Apenas name, description; Codex possui adicionalmente agents/openai.yaml para políticas de invocação do skill
Claude Code	.claude/skills/<skill-name>/	Possui vários campos de frontmatter estendidos; veja references/frontmatter-spec.md

Este arquivo é compartilhado entre Codex e Antigravity. Todos os caminhos scripts/..., references/... neste arquivo são relativos ao diretório que contém este SKILL.md. "Executar comando" significa usar a ferramenta de execução de comandos shell do provedor em uso (por exemplo, run_command no Antigravity).

---

1. Princípios Fundamentais de Design

1. Arquitetura de Divulgação Progressiva em 3 Níveis:
   • Nível 1: Metadados (Sempre carregados na inicialização): name, description no YAML Frontmatter. Consome pouquíssimos tokens; mantenha description abaixo de 1.536 caracteres.
   • Nível 2: Instruções (Carregadas apenas quando o Skill é ativado): Corpo do arquivo SKILL.md, obrigatoriamente abaixo de 500 linhas. Contém apenas Fluxo de Trabalho, Princípios Fundamentais e Restrições.
   • Nível 3: Recursos (Carregados apenas quando realmente necessários): templates/ (modelos de resultado), examples/ (exemplos de texto padrão-ouro), references/ (especificações técnicas), scripts/ (código bash/python para tarefas pesadas que não consomem contexto).
2. Classificação do Propósito do Skill:
   • Reference Skills: Convenções de código, conhecimento do sistema, padrões de design, para o agente aplicar como conhecimento de base.
   • Task Skills: Processos passo a passo para executar ações. Tarefas com efeitos colaterais (deploy, commit, exclusão de dados) só devem ser executadas quando o usuário as invocar diretamente. A versão .agents/skills/ faz ambas as coisas: cria agents/openai.yaml com policy.allow_implicit_invocation: false (para Codex) e insere a frase "Usar apenas quando o usuário solicitar diretamente" na description (para Antigravity, que não possui campo equivalente). Detalhes em references/providers.md seção 3.
3. Funcionalidades Específicas de Cada Provedor: Claude Code possui subagente, variáveis de parâmetro e injeção de comandos shell no SKILL.md (veja references/frontmatter-spec.md). Use-os apenas na versão para Claude Code; para outros provedores, converta conforme references/providers.md seção 3.
4. Verifique, Não Confie (Autoverificação):
   • Todo skill gerado deve vir acompanhado de scripts/validate.sh com código de saída padrão (0 = sucesso, 1 = falha).
   • Cumprir 100% as regras de linting conforme o padrão markdownlint.
5. Zero Poluição do Espaço de Trabalho:
   • Todos os arquivos de configuração, recursos e scripts devem estar apenas no diretório empacotado do skill, dentro do diretório de cada provedor.
   • Toda documentação de exemplo deve estar apenas em examples/ do skill. Não gerar ou copiar arquivos de exemplo para outros diretórios de negócio do projeto (como src/, raiz do projeto).
   • Arquivos temporários durante testes devem ser gravados no diretório temporário do sistema operacional (ou em um diretório temporário especificado nas instruções do usuário) e limpos imediatamente após a conclusão.
6. Pergunte ao usuário com opções estruturadas:
   • Todas as escolhas apresentadas ao usuário (escopo, provedor, pontos pouco claros na ideia, direção de design) devem ser feitas na forma de opções. Se a sessão tiver uma ferramenta de perguntar ao usuário no formato de seleção de resposta, use essa ferramenta. Caso contrário, liste as opções numeradas, pause e aguarde a resposta do usuário.
   • Ordem de apresentação: (1) o que o skill a ser criado faz, (2) o que a pergunta está perguntando e por que ela surgiu, (3) as opções, cada uma com uma frase descrevendo prós e contras, (4) a opção recomendada, colocada no início da lista e marcada com (recomendado).
   • Faça no máximo 4 perguntas por vez, priorizando as perguntas importantes primeiro. Sempre permita que o usuário responda de forma diferente das opções fornecidas.
   • Não escolha pelo usuário sem receber uma resposta.
7. Uma versão para cada provedor, de acordo com o padrão desse provedor:
   • Recursos compartilhados (template.md, examples/, references/, scripts/) são copiados integralmente. Apenas SKILL.md (e agents/openai.yaml do Codex) são escritos separadamente: uma versão para Claude Code e uma versão compartilhada para Codex e Antigravity.
   • A versão para Codex/Antigravity deve funcionar corretamente em ambos os provedores: usar apenas campos de frontmatter do padrão aberto, não usar variáveis ou ferramentas que apenas Claude Code entende, e não chamar o agente em execução de "Claude". Claude só deve ser mencionado quando for o assunto do skill.

---

2. Entradas Necessárias (Inputs)

• Obrigatório: Descrição da ideia ou objetivo de negócio do skill a ser criado.
• Opcional: Restrições específicas, ferramentas a serem usadas, tipo de tarefa ou referência.
• Obrigatório perguntar (a cada novo skill): Escopo e provedor (seção 2.1), juntamente com quaisquer pontos pouco claros na ideia (seção 2.2). Apenas pule perguntas que o usuário já respondeu claramente na solicitação.
• Não decidir por conta própria sobre pontos pouco claros: Se a ideia for vaga, analise e proponha (seção 2.2), não preencha e gere arquivos. Apenas pontos com convenções óbvias (por exemplo, nome kebab-case derivado da ideia) podem ser definidos automaticamente, e devem ser mencionados no resumo do design.

2.1. Perguntar sobre Escopo e Provedor

Antes de gerar qualquer arquivo, faça 2 perguntas na mesma rodada, de acordo com o princípio 6:

1. Escopo (pode escolher vários): três opções conforme tabela abaixo, project-shared é o recomendado.
2. Provedor (pode escolher vários): Codex, Claude Code, Antigravity. Se o skill puder ser usado em todos os provedores, recomende todos os três. Se o skill só fizer sentido para um provedor (por exemplo, verificar arquivos de configuração do Claude Code), recomende apenas esse provedor e explique o motivo.

Escopo	Significado	Diretório Raiz	Variável ao executar script
project-shared	Apenas para o projeto atual, compartilhado por toda a equipe (commit no git)	Raiz do projeto	SCOPE=project (padrão)
project-personal	Apenas para o projeto atual, apenas para este usuário (sem commit)	Raiz do projeto	SCOPE=project, em seguida, adicione os diretórios criados a .git/info/exclude
user-global	Todos os projetos deste usuário	$HOME	SCOPE=user

Regras:

• Se o usuário escolher vários escopos, implemente cada escopo sequencialmente.
• Se o diretório do projeto não for um repositório git, remova a opção project-personal.
• Inclua o escopo e o provedor selecionados no relatório de entrega, juntamente com a lista de caminhos criados.
• Se o skill tiver conteúdo específico do projeto e o usuário escolher user-global: emita um aviso de uma linha antes de criar.

2.2. Análise da Ideia e Proposta

Depois de obter escopo e provedor, analise a ideia antes de escrever qualquer arquivo:

1. Resumo do que foi entendido: o que o skill resolve, quem usa, quando é ativado, qual é a saída.
2. Identificar pontos de design, cada um indicando se o usuário já disse ou se o agente está supondo:
   • Tipo de skill: Tarefa ou Referência; tem efeitos colaterais ou não.
   • Modo de ativação: automático via description, apenas quando o usuário invoca diretamente, ou ambos; frases de ativação e casos em que não deve ser usado.
   • Entradas, parâmetros e como lidar com a falta deles.
   • Saídas: formato, local de armazenamento, se precisa de template.md e critérios de verificação em scripts/validate.sh.
   • Modo de execução: apenas instruções ou precisa de script; ferramentas necessárias.
   • Partes a serem separadas em references/, para que SKILL.md fique abaixo de 500 linhas.
3. Propor direção otimizada: para cada ponto com múltiplas abordagens, apresente 2 a 3 opções com prós e contras, e escolha uma opção recomendada. Exemplo: "verificar com script scripts/check.sh (rápido, preciso, mas precisa de bash)" vs. "agente ler e avaliar por conta própria (flexível, mas consome tokens e pode perder detalhes)".
4. Perguntar ao usuário: agrupe todos os pontos pouco claros e pontos com múltiplas abordagens em perguntas, de acordo com o princípio 6.
5. Finalizar o design: após receber as respostas, escreva um resumo do design (nome do skill, tipo, modo de ativação, lista de arquivos a serem criados, provedor, escopo, valores definidos automaticamente pelo agente). Se as respostas gerarem novos pontos pouco claros, pergunte novamente antes de gerar arquivos.

2.3. Pesquisa sobre o Provedor

Antes de escrever a versão para um provedor, leia references/providers.md:

• Se a Data de verificação for mais antiga que 30 dias, o skill precisar de funcionalidades ainda não presentes no arquivo, ou as informações no arquivo contradizerem a realidade: consulte a documentação oficial na seção 6 desse arquivo, corrija o arquivo, atualize a data de verificação e, em seguida, copie o arquivo para os outros provedores usando scripts/sync-skill.sh better-skill-gen.
• Antigravity no escopo de projeto compartilhado usa .agents/skills/ com Codex (seção 5). Não criar .agent/skills/.
• Não adivinhe especificações do provedor. Pontos que não puderem ser pesquisados devem ser claramente comunicados ao usuário e perguntados.

---

3. Fluxo de Trabalho

flowchart TD
    A["Ideia de negócio do Usuário"] --> A2["0. Perguntar Escopo e Provedor"]
    A2 --> B["1. Analisar ideia, propor, perguntar pontos pouco claros"]
    B --> B2["2. Pesquisar provedor"]
    B2 --> C["3. Consultar template.md & references/"]
    C --> D["4. Gerar versão original"]
    D --> E["5. Sincronizar recursos & escrever SKILL.md específico para cada provedor"]
    E --> F["6. Autoverificar com scripts/validate.sh"]
    F -->|Passar| G["Concluído & Entregue"]
    F -->|Falhar| D

0. Perguntar Escopo e Provedor: Execute a seção 2.1 e aguarde a resposta antes de prosseguir.
1. Analisar a ideia: Execute a seção 2.2 até que o design seja finalizado. Nomeie o skill em kebab-case (máximo 64 caracteres, proibido usar anthropic-skills, synced, claude, anthropic).
2. Pesquisar provedor: Execute a seção 2.3 para todos os provedores selecionados.
3. Consultar documentação padrão: Leia template.md (estrutura básica), references/providers.md (diferenças entre provedores), references/frontmatter-spec.md (campos do Claude Code) e examples/sample.md (estilo de escrita e lógica de script).
4. Gerar versão original: Escreva todos os componentes no diretório do primeiro provedor selecionado:
   • SKILL.md: Frontmatter seguro (bloco scalar >-), abaixo de 500 linhas.
   • template.md (ou templates/): Modelo de saída com variáveis de exemplo ${VARIABLE}.
   • examples/sample.md: Texto de exemplo real, sem placeholders.
   • references/ (se houver documentação de especificação/conhecimento complexo a ser separada).
   • scripts/validate.sh: Script para verificar a integridade do resultado.
   • Recursos compartilhados escritos de forma neutra em relação ao provedor: scripts chamados por caminho relativo a partir do diretório do skill.
5. Implantar por provedor:
   • Copiar recursos compartilhados: execute PROVIDERS="<provedores selecionados>" bash scripts/sync-skill.sh <skill-name>. O script copia todos os arquivos, exceto SKILL.md e agents/, e relata [TODO] para provedores que ainda não possuem SKILL.md.
   • Para os diretórios restantes, escreva SKILL.md específico de acordo com a tabela de conversão em references/providers.md seção 3. Reescreva o texto do corpo, não apenas remova campos de frontmatter. Se Codex e Antigravity forem selecionados juntos, haverá apenas um diretório .agents/skills/, e o script mesclará automaticamente.
   • Skill com efeitos colaterais: a versão .agents/skills/ cria adicionalmente agents/openai.yaml com policy.allow_implicit_invocation: false e insere a frase "Usar apenas quando o usuário solicitar diretamente" na description.
   • Escopo user-global: adicione SCOPE=user ao executar o script.
   • Escopo project-personal: adicione os diretórios do skill recém-criados a .git/info/exclude (não modifique .gitignore, não faça commit).
6. Autoverificação:
   • Execute PROVIDERS="<provedores selecionados>" bash scripts/validate.sh <skill-name> (adicione SCOPE=user se for user-global).
   • O script verifica: frontmatter YAML válido, markdownlint, SKILL.md com <= 500 linhas, arquivos obrigatórios presentes em todos os provedores selecionados, e SKILL.md para Codex/Antigravity sem campos ou tokens que apenas Claude Code entende.
   • Leia cada linha [WARN]: se mencionar Claude porque Claude é o assunto, mantenha; caso contrário, corrija.
   • Se houver erros, corrija até receber [PASS].

---

4. Restrições e Padrões (Guardrails)

• REGRAS OBRIGATÓRIAS (CRÍTICAS):
  • Todas as escolhas devem ser perguntadas de acordo com o princípio 6 e aguardar resposta antes de prosseguir.
  • Sempre perguntar escopo e provedor antes de criar um novo skill (seção 2.1).
  • Não decidir por conta própria sobre pontos pouco claros: analisar, propor e perguntar (seção 2.2) antes de gerar arquivos.
  • Pesquisar o provedor antes de escrever a versão para esse provedor (seção 2.3); não adivinhar especificações.
  • Não copiar integralmente SKILL.md entre provedores: cada provedor tem sua própria versão de acordo com seu padrão; validate.sh deve obter [PASS] para todos os provedores selecionados.
  • Zero Poluição do Espaço de Trabalho: documentação de exemplo deve estar apenas em examples/; não criar arquivos fora do diretório empacotado do skill.
  • Manter SKILL.md abaixo de 500 linhas: mover conteúdo detalhado para references/ ou templates/.
  • Padronização do Frontmatter: se description contiver dois pontos :, use scalar >- ou aspas "...".
  • Cumprir regras do Markdownlint (MD001 - MD047) para todos os arquivos Markdown criados.
• FAÇA (Recomendado):
  • Declarar o mecanismo "executar apenas quando o usuário solicitar" para todos os skills com efeitos colaterais, conforme a maneira correta de cada provedor (Codex: agents/openai.yaml; Antigravity: frase na description).
  • Usar variáveis de modelo ${NOME_VARIAVEL} com nomes sugestivos no template.
  • Limpar imediatamente quaisquer arquivos temporários gerados durante os testes automatizados.
• NÃO FAÇA (Não recomendado):
  • Não colocar toda a documentação de referência longa diretamente no SKILL.md.
  • Não deixar URLs em texto puro no arquivo markdown sem usar <> ou links markdown.
  • Não usar nomes de skill com mais de 64 caracteres ou contendo letras maiúsculas/caracteres especiais.
  • Não chamar o agente de "Claude" na versão para provedores diferentes de Claude Code.