write-issue

Redacta el texto de una incidencia (bug, funcionalidad o tarea) en un archivo CommonMark dentro de la carpeta `issues/` del proyecto, listo para copiar en el gestor de incidencias (Redmine, GitHub, GitLab). Úsala cuando el usuario describe un problema a resolver o una actividad a realizar y quiere preparar la incidencia.

¿Qué es write-issue?

Esta habilidad permite a un agente de IA (como Claude Code, Cursor o Codex) generar automáticamente el texto de una incidencia (issue) a partir de la descripción del usuario, guardándola como un archivo CommonMark en la carpeta `issues/` del proyecto. Es útil para desarrolladores que quieren documentar bugs, funcionalidades o tareas de forma estructurada y coherente, lista para copiar en gestores como Redmine, GitHub o GitLab. La habilidad primero clasifica la solicitud, verifica la información revisando el código del proyecto (archivos, clases, rutas, tablas) y solicita al usuario cualquier detalle faltante (pasos para reproducir, comportamiento esperado, criterios de aceptación). Luego escribe un archivo con formato CommonMark siguiendo una plantilla que incluye contexto, descripción, pasos (solo para bugs), comportamiento esperado, criterios de aceptación, notas técnicas y referencias. El archivo se nombra `issues/YYYY-MM-DD-slug.md` y se puede renombrar posteriormente con el número de incidencia. La habilidad **no** crea, modifica ni elimina incidencias en el gestor; solo genera el texto que el usuario copiará manualmente.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/gabriele-murara/team-skills/tree/HEAD/plugins/issues/skills/write-issue

Installed? Explore more Productividad y colaboración skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Redacción de una incidencia

Prepara el texto de una incidencia a partir de lo descrito por el usuario ($ARGUMENTS y la conversación). El usuario copiará el texto en el gestor de incidencias, donde creará la incidencia y le asignará responsable, prioridad, versión, etc. Esta habilidad no crea la incidencia en el gestor.

Gestor: solo lectura

En el gestor (Redmine, GitHub, GitLab) el agente solo puede leer las incidencias. No debe nunca modificarlas, ni siquiera si el usuario lo pide:

  • nada de creación, modificación, cierre, reapertura o eliminación;
  • nada de comentarios, notas, adjuntos, tiempo empleado;
  • nada de cambios de estado, responsable, prioridad, versión, etiquetas.

Usa solo peticiones de lectura: curl sin -X ni datos (por lo tanto GET), gh issue view, gh issue list. Nunca POST, PUT, PATCH, DELETE, ni comandos como gh issue create, edit, comment, close, reopen, delete. Si es necesario insertar texto en el gestor, escríbelo en un archivo en issues/: lo copia el usuario.

1. Carpeta issues

En la raíz del proyecto (raíz del repositorio git, si existe) debe existir la carpeta issues/ con un .gitignore que ignore todo el contenido excepto a sí mismo:

*
!.gitignore

Si la carpeta o el .gitignore faltan, créalos. Si el .gitignore existe con un contenido diferente, no lo modifiques: comunícalo al usuario.

2. Recopilación y verificación de la información

  1. Clasifica la solicitud: bug, funcionalidad o tarea (mantenimiento, actualización, refactorización, documentación...).
  2. Verifica lo descrito en el código del proyecto: busca los archivos, las clases, las rutas, las tablas y los comportamientos mencionados, y comprueba que existan y funcionen según lo descrito. Anota los archivos implicados.
  3. Identifica la información faltante o ambigua, por ejemplo:
    • bug: pasos para reproducirlo, comportamiento esperado y actual, entorno (producción, staging, local), mensajes de error o logs;
    • funcionalidad: quién la usa, qué debe poder hacer, casos límite, restricciones;
    • para todas: criterios para considerar la incidencia resuelta.
  4. Si falta algo necesario, o si el código no se corresponde con lo descrito, pregunta al usuario antes de escribir. Haz las preguntas todas juntas y solo sobre lo que realmente se necesita.

No propongas ni implementes la solución: la incidencia describe el problema y el resultado esperado. Las notas técnicas solo sirven para orientar a quien trabajará en ella.

3. Escritura del archivo

Escribe el archivo issues/<AAAA-MM-DD>-<slug>.md, donde slug es el slug del título en minúsculas, con palabras separadas por - y sin caracteres especiales (máximo 50 caracteres). Si el archivo ya existe, añade un sufijo -2, -3...

Estructura del archivo:

# <Título breve y específico>

## Contexto

[Dónde se sitúa el problema o la tarea, y por qué es necesaria.]

## Descripción

[Bug: comportamiento actual. Funcionalidad/tarea: lo que hay que hacer.]

## Pasos para reproducir

1. [...]

## Comportamiento esperado

[...]

## Criterios de aceptación

- [ ] [Condición verificable]

## Notas técnicas

- `ruta/del/archivo` — [por qué es relevante]

## Referencias

- [Enlace, incidencias relacionadas, logs, capturas de pantalla]

Reglas:

  • Pasos para reproducir solo para bugs; Comportamiento esperado para bugs y funcionalidades. Omite Notas técnicas y Referencias si están vacías.
  • La línea # Título va en el campo título del gestor; el resto, desde los títulos ## hacia abajo, va en la descripción.
  • Formato CommonMark; código y logs en bloque de código con el lenguaje.
  • Idioma: español. Sin emojis.
  • Texto conciso y comprensible para quien no haya seguido la conversación: sin referencias a "como se dijo antes" ni a la sesión.

4. Respuesta al usuario

Indica:

  • la ruta del archivo creado;
  • el título propuesto y el tipo (bug, funcionalidad, tarea);
  • que, después de crear la incidencia en el gestor, conviene renombrar el archivo incluyendo el número de incidencia (por ejemplo issues/123-<slug>.md): así open-issue 123 lo encuentra incluso sin acceso al gestor.

Skills relacionados