aitormf/agent-skills

Transforma uma ideia vaga ou mal definida em uma especificação (problema, usuários, histórias de usuário, requisitos, casos de contorno e critérios de aceitação) por meio de uma entrevista baseada em rodadas. Use quando for solicitado a escrever uma especificação, definir uma funcionalidade, esclarecer requisitos ou passar de uma ideia para algo implementável.

O que é agent-skills?

Esta skill transforma uma ideia vaga em uma especificação pronta para planejamento, conduzindo uma entrevista estruturada por rodadas. O agente lidera a conversa, e o usuário fornece as respostas, focando no 'o quê' e 'por quê', sem abordar arquitetura ou frameworks a menos que o usuário peça. A skill segue oito rodadas de perguntas: problema e resultado esperado, usuários e atores, histórias de usuário, escopo e fora de escopo, comportamento e casos de contorno, restrições não funcionais, segurança (se aplicável) e critérios de aceitação. Cada pergunta não respondida é apresentada como uma questão em aberto com opções, e a skill nunca assume respostas silenciosamente. O resultado é um diretório `docs/specs/<YYYYMMDD>-<tipo>-<nome>/` contendo `spec.md` e opcionalmente `plan.md`, com status `draft`, que o usuário pode aprovar. A skill é útil para desenvolvedores que precisam esclarecer requisitos de forma colaborativa e sistemática, e é compatível com ferramentas como Claude Code, Cursor e Codex que suportam skills de agente baseadas em markdown.

Funciona com~Claude Code~Codex CLI~Cursor

npx skills add https://github.com/aitormf/agent-skills/tree/HEAD/skills/idea-to-spec

Documentação

Da ideia à especificação

Ajude a pessoa a transformar uma ideia em uma especificação pronta para planejamento. Você lidera a conversa; a pessoa dá as respostas.

Artefatos e status

Cada item de trabalho fica em docs/specs/<YYYYMMDD>-<tipo>-<nome>/. O tipo segue Conventional Commits (feat, fix, refactor, docs…) e o nome é em kebab-case. Se esse diretório já existir, adicione -2.
spec.md e plan.md carregam status: draft | approved | obsolete em seu frontmatter. Apenas uma pessoa define approved.
Se você modificar um artefato aprovado, reverta-o para draft e avise.
Gerenciamento de trabalho (prioridade, responsável, concluído) não é função desta skill: isso fica no sistema de tarefas. Se houver uma issue, seu ID vai em issue:.

Comportamento

Comece resumindo a ideia em um parágrafo curto.
Identifique o que está faltando para escrever uma boa especificação e faça o número mínimo de perguntas úteis, começando pelas bloqueadoras.
Foque no o quê e no por quê, não no como: nenhum framework ou arquitetura, a menos que a pessoa os peça. Isso pertence à skill spec-to-plan.
Se docs/ARCHITECTURE.md existir, leia-o para usar o vocabulário do glossário e detectar conflitos com os princípios.

Perguntas por rodada

Problema e resultado esperado.
Usuários e atores.
Histórias de usuário (o que cada um precisa e por quê).
Escopo e fora de escopo.
Comportamento e casos de contorno: dados vazios, inválidos ou massivos; falhas de dependências externas; ações concorrentes.
Restrições não funcionais.
Segurança, se envolver dados, autenticação ou entrada externa: sensibilidade dos dados, quem pode fazer o quê, quais entradas não são confiáveis e quais testes negativos são necessários.
Critérios de aceitação ("Dado…, quando…, então…").

Se algo ainda estiver ambíguo após uma rodada, pergunte apenas sobre essa parte.

Perguntas em aberto

Nunca assuma uma resposta silenciosamente. Para cada pergunta não resolvida:

[Pergunta]

A) [Sua proposta padrão, se houver]

B) [Alternativa óbvia]

C) Deixar como pergunta em aberto na especificação

D) Outra resposta

Ela só é resolvida quando a pessoa responde ou opta por deixá-la em aberto.

Formato de cada resposta: O que entendi · Perguntas em aberto · Próximo passo.

Tamanho

Combine a profundidade com a mudança. Proponha o caminho e deixe a pessoa decidir:

Mudança	Artefatos
Bug de uma linha	Nenhum, ou apenas `tasks.md`
Bug complexo	`spec.md` + `tasks.md`
Funcionalidade pequena	`spec.md` + `plan.md` + `tasks.md`
Funcionalidade de produção ou refatoração arquitetural	Tudo, com revisão de especificação e plano

Quando parar

Pare quando houver o suficiente para: objetivo, problema, usuários, histórias de usuário, escopo e fora de escopo, requisitos funcionais e não funcionais, casos de contorno e critérios de aceitação.

Então:

Proponha o nome do diretório e um rascunho de spec.md a partir de assets/spec-template.md, com status: draft. Exclua as seções opcionais que não se aplicam.
Mostre o rascunho e escreva-o apenas quando a pessoa aprovar.
Próxima etapa sugerida: revisá-lo com review-spec. Se for pequeno e a pessoa estiver satisfeita, ela pode marcá-lo como approved e passar para spec-to-plan.