aitormf/agent-skills

Convierte una idea vaga o a medio definir en una especificación (problema, usuarios, historias de usuario, requisitos, casos extremos y criterios de aceptación) mediante una entrevista por rondas. Úsalo cuando te pidan escribir una especificación, definir una funcionalidad, aclarar requisitos o pasar de una idea a algo implementable.

¿Qué es agent-skills?

Este skill guía una conversación estructurada por rondas para transformar una idea inicial difusa en una especificación lista para planificar. Es útil para desarrolladores y agentes de IA que necesitan clarificar requisitos antes de implementar, ya que evita suposiciones silenciosas y asegura que se cubran aspectos clave como el problema, los usuarios, las historias de usuario, el alcance, los casos extremos, las restricciones no funcionales, la seguridad y los criterios de aceptación. Funciona para cualquier agente de desarrollo (Claude Code, Cursor, Codex) y se basa en un archivo SKILL.md con reglas claras: lleva la conversación el agente, la persona responde; los artefactos se guardan en `docs/specs/` con estados de borrador, aprobado u obsoleto; y cada pregunta no resuelta se presenta con opciones para que la persona decida. El flujo termina cuando hay suficiente contenido para redactar un `spec.md` usando una plantilla y se sugiere como siguiente paso la revisión con `review-spec` o el pase a `spec-to-plan`.

Compatible con~Claude Code~Codex CLI~Cursor

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

Documentación

De la idea a la especificación

Ayuda a la persona a convertir una idea en una especificación lista para planificar. Tú lideras la conversación; la persona da las respuestas.

Artefactos y estado

Cada elemento de trabajo reside en docs/specs/<AAAAMMDD>-<tipo>-<nombre>/. El tipo sigue Conventional Commits (feat, fix, refactor, docs…) y el nombre está en kebab-case. Si ese directorio ya existe, añade -2.
spec.md y plan.md llevan status: draft | approved | obsolete en su frontmatter. Solo una persona puede establecer approved.
Si modificas un artefacto aprobado, vuelve a ponerlo como draft y dilo.
La gestión del trabajo (prioridad, responsable, hecho) no es competencia de este skill: reside en el gestor de tareas. Si hay un issue, su ID va en issue:.

Comportamiento

Empieza resumiendo la idea en un párrafo corto.
Identifica qué falta para redactar una buena especificación y haz el número mínimo de preguntas útiles, empezando por las bloqueantes.
Concéntrate en el qué y el por qué, no en el cómo: sin frameworks ni arquitectura a menos que la persona lo pida. Eso pertenece a spec-to-plan.
Si existe docs/ARCHITECTURE.md, léelo para usar el vocabulario del glosario y detectar conflictos con los principios.

Preguntas por rondas

Problema y resultado esperado.
Usuarios y actores.
Historias de usuario (qué necesita cada uno y por qué).
Alcance y fuera de alcance.
Comportamiento y casos extremos: datos vacíos, inválidos o masivos; fallos de dependencias externas; acciones concurrentes.
Restricciones no funcionales.
Seguridad, si afecta a datos, autenticación o entrada externa: sensibilidad de los datos, quién puede hacer qué, qué entradas no son confiables y qué pruebas negativas se necesitan.
Criterios de aceptación ("Dado…, cuando…, entonces…").

Si algo sigue siendo ambiguo después de una ronda, pregunta solo sobre esa parte.

Preguntas abiertas

Nunca asumas una respuesta en silencio. Para cada pregunta no resuelta:

[Pregunta]

A) [Tu propuesta por defecto, si la hay]

B) [Alternativa obvia]

C) Déjalo como pregunta abierta en la especificación

D) Otra respuesta

Solo se resuelve cuando la persona responde o elige dejarlo abierto.

Formato de cada respuesta: Lo que entiendo · Preguntas abiertas · Siguiente paso.

Tamaño

Ajusta la profundidad al cambio. Propón la ruta y deja que la persona decida:

Cambio	Artefactos
Error de una línea	Ninguno, o solo `tasks.md`
Error complejo	`spec.md` + `tasks.md`
Funcionalidad pequeña	`spec.md` + `plan.md` + `tasks.md`
Funcionalidad de producción o refactor arquitectónico	Todo, con revisión de especificación y plan

Cuándo parar

Para cuando haya suficiente para: objetivo, problema, usuarios, historias de usuario, alcance y fuera de alcance, requisitos funcionales y no funcionales, casos extremos y criterios de aceptación.

Luego:

Propón el nombre del directorio y redacta el borrador de spec.md a partir de assets/spec-template.md, con status: draft. Elimina las secciones opcionales que no apliquen.
Muestra el borrador y escríbelo solo una vez que la persona lo apruebe.
Siguiente paso sugerido: revisarlo con review-spec. Si es pequeño y la persona está conforme, puede marcarlo como approved y pasar a spec-to-plan.