github-triage

Visión general de la skill github-triage

Qué hace github-triage

La skill github-triage ayuda a un agente a clasificar issues de GitHub mediante una máquina de estados estricta basada en labels, en lugar de depender de comentarios improvisados en cada issue. Está pensada para repositorios que buscan un intake más consistente, estados de issue más claros y un handoff fiable cuando un issue queda listo para implementación.

Para quién es esta skill

La skill github-triage encaja especialmente bien para maintainers, operadores de repositorios y colaboradores asistidos por IA que necesitan:

• revisar bugs y feature requests entrantes
• decidir si un issue es accionable
• pedir la información que falta sin perder el hilo
• preparar issues para un agente de código AFK
• mantener labels consistentes en todo el repo

Si el problema real en tu equipo es “nuestros issues son un caos y nadie sabe qué está listo”, esta skill es una muy buena opción.

El trabajo real que resuelve

Para la mayoría de los equipos, hacer triage no consiste solo en poner labels. Lo difícil es convertir reportes vagos en uno de unos pocos estados duraderos:

• necesita revisión de maintainer
• necesita aclaración del autor del issue
• listo para un agente
• listo para una persona
• no se va a hacer

github-triage resulta útil porque trata el seguimiento de issues como un flujo de trabajo, no solo como una tarea de redactar comentarios.

Qué hace diferente a github-triage

La principal diferencia es que github-triage obliga a usar dos labels paralelas en cada issue:

• exactamente una label de category, como bug o enhancement
• exactamente una label de state, como needs-triage o ready-for-agent

Puede parecer simple, pero mejora de forma tangible el seguimiento de issues en GitHub porque evita estados ambiguos y obliga a definir con más claridad cuál es la siguiente acción.

Por qué la gente lo adopta

La razón más fuerte para instalar github-triage no es solo la automatización. Es la combinación de:

• una máquina de estados definida
• un proceso interactivo de preguntas para recopilar lo que falta
• un flujo de agent brief duradero para el handoff a implementación
• memoria institucional opcional mediante registros en .out-of-scope/

En conjunto, esto da a los maintainers algo bastante más estructurado que un prompt genérico del tipo “haz triage de este issue”.

Restricciones importantes antes de instalarlo

Esta skill asume un flujo de trabajo centrado en GitHub y da por hecho el uso de gh para las operaciones en GitHub. También presupone que tu repo puede sostener una taxonomía de labels controlada. Si tu repositorio ya tiene un sistema grande de labels, conflictivo y sin intención de limpiarlo, la adopción será más difícil que la propia skill.

Cómo usar la skill github-triage

Contexto de instalación para github-triage

En una configuración basada en Skills, instala github-triage desde el repositorio mattpocock/skills:

npx skills add mattpocock/skills --skill github-triage

Después de instalarlo, abre primero estos archivos:

• SKILL.md
• AGENT-BRIEF.md
• OUT-OF-SCOPE.md

Ese orden de lectura importa: primero entiende la máquina de estados, después el contrato de handoff al agente y, por último, el patrón de memoria para rechazos recurrentes.

Qué necesita github-triage como entrada

La skill github-triage funciona mejor cuando el agente tiene:

• el contexto del repositorio actual
• acceso a git remote para inferir el repo
• acceso a gh para leer y actualizar issues
• el conjunto actual de labels del repositorio de destino
• el número del issue o la lista de issues que hay que clasificar

Sin acceso a labels y a GitHub CLI, se pierde gran parte del valor práctico.

Empieza comprobando si las labels están listas

Antes de usar github-triage a escala, confirma que tu repo tiene las labels esperadas:

Category labels

• bug
• enhancement

State labels

• needs-triage
• needs-info
• ready-for-agent
• ready-for-human
• wontfix

La regla clave es que cada issue debe tener exactamente una label de categoría y exactamente una label de estado. Si tu repo no las tiene, créalas o mapea sus equivalentes primero.

El flujo principal de github-triage

Un flujo práctico de github-triage usage se parece a esto:

1. identificar el issue objetivo
2. revisar las labels existentes para detectar conflictos o ausencia de labels de state/category
3. leer el cuerpo del issue y la conversación
4. decidir si el issue:
   • es claramente accionable
   • tiene información faltante
   • queda fuera de alcance
   • encaja mejor para una persona que para un agente AFK
5. hacer preguntas de seguimiento concretas si hace falta
6. aplicar una label de categoría y una label de estado
7. si está listo para un agente, redactar un agent brief estructurado

Ese último paso es donde esta skill aporta más valor que un simple ordenamiento de issues.

Cómo hacer buenos prompts para github-triage

Un prompt débil:

• “Triage issue #142.”

Un prompt más sólido:

• “Use github-triage for issue #142 in the current repo. Check for conflicting labels first, classify it as exactly one category and one state, identify missing information if any, and if it is implementation-ready, draft a durable agent brief with testable acceptance criteria.”

Por qué funciona mejor:

• le indica al agente que primero valide el estado de las labels
• pide una decisión de clasificación, no solo comentarios
• hace explícito el artefacto de handoff

Convierte una intención aproximada del maintainer en una solicitud completa

Muchos maintainers saben qué resultado quieren, pero no cómo formular el prompt. Esta es una plantilla más sólida para github-triage usage:

• “Review issue # with github-triage. Determine whether this is a bug or enhancement, choose the correct state label, ask no more than 5 clarifying questions if information is missing, and recommend ready-for-agent, ready-for-human, or wontfix with reasoning.”

Funciona porque reduce el espacio de decisión sin impedir que la skill siga su flujo.

Usa con cuidado la fase de preguntas de github-triage

La skill menciona sesiones interactivas de preguntas. En la práctica, eso significa pedir la mínima información que falta para hacer avanzar el issue. Un buen proceso de preguntas es:

• específico
• acotado
• vinculado a una transición de estado

Por ejemplo, conviene pedir:

• pasos de reproducción
• comportamiento esperado frente al real
• detalles del entorno
• forma esperada de la API o de la UX
• criterios de aceptación

No hagas preguntas genéricas como “cuéntame más” si el issue solo necesita un dato puntual para pasar de needs-info a ready-for-agent.

Cómo deben redactarse los agent briefs

Cuando un issue pasa a ready-for-agent, github-triage espera un agent brief duradero y orientado al comportamiento. Según AGENT-BRIEF.md, el brief debería:

• definir el comportamiento deseado, no los pasos de implementación
• evitar file paths y números de línea
• incluir criterios de aceptación concretos y comprobables
• actuar como especificación autoritativa, incluso si la conversación del issue es ruidosa

Esta es una de las partes más útiles de la github-triage guide, sobre todo en flujos de seguimiento de issues donde el trabajo se transfiere de forma asíncrona.

Cuándo usar la base de conocimiento de out-of-scope

Si una feature request se rechaza repetidamente, github-triage for Issue Tracking se vuelve más eficaz cuando se combina con documentos en .out-of-scope/. Esto resulta útil cuando los maintainers quieren:

• evitar volver a debatir decisiones antiguas
• conservar la justificación tras cerrar el issue
• detectar rápido solicitudes duplicadas

Crea un archivo por concepto, no un archivo por issue. Así conviertes decisiones pasadas en memoria reutilizable del proyecto.

Archivos que debes leer antes de cambiar el flujo

Lee estos archivos en este orden si quieres adaptar la skill en lugar de limitarte a invocarla:

1. SKILL.md para el modelo de labels y el flujo de triage
2. AGENT-BRIEF.md para entender qué significa realmente ready-for-agent
3. OUT-OF-SCOPE.md para el manejo persistente de solicitudes rechazadas

Es la ruta más corta para entender cómo espera este repo que el triage de issues produzca resultados estables.

Patrones de flujo donde github-triage encaja mejor

github-triage funciona especialmente bien para:

• repos con un volumen frecuente de issues entrantes
• equipos que usan agentes de IA para implementar
• maintainers que quieren labels y estructura de comentarios consistentes
• colas de issues donde “falta más información” es algo habitual

Resulta menos convincente para repositorios muy pequeños con muy poco volumen de issues o para equipos que ya aplican otro sistema maduro de operaciones sobre issues.

Preguntas frecuentes sobre la skill github-triage

¿github-triage es solo para repositorios grandes?

No. Los repos pequeños también pueden beneficiarse, especialmente si un maintainer está desbordado por un intake de issues inconsistente. Aun así, las mayores mejoras aparecen cuando entran suficientes issues como para que las labels y la calidad del handoff empiecen a importar de verdad.

¿github-triage es fácil de usar para principiantes?

Sí, siempre que ya entiendas lo básico sobre labels e issues en GitHub. La github-triage skill tiene un enfoque claro y opinionado, pero no es técnicamente compleja. La principal curva de aprendizaje está en aplicar su máquina de estados de forma consistente.

¿En qué se diferencia github-triage de un prompt normal?

Un prompt normal puede resumir un issue o sugerir labels. github-triage añade un flujo estructurado:

• reglas explícitas de labels
• comprobación de conflictos
• lógica de aclaración
• un artefacto de handoff ready-for-agent bien definido
• memoria opcional de elementos fuera de alcance

Esa estructura reduce la improvisación y mantiene resultados de triage más consistentes entre distintos issues.

¿Necesito GitHub CLI para usar github-triage?

Para un uso práctico, sí. La skill da por hecho el uso de gh para las operaciones en GitHub. Sin eso, todavía puedes imitar el razonamiento, pero pierdes el flujo directo de lectura de issues y gestión de labels que hace que la skill sea realmente útil en operación.

¿Cuándo encaja mal github-triage?

Es mejor no usar github-triage si:

• tu equipo no quiere un modelo estricto de labels de estado
• tu repo usa una taxonomía de labels muy distinta y no hay intención de mapearla
• solo quieres conversación libre, no un triage controlado
• tus issues rara vez llegan a un handoff a agentes

En esos casos, puede bastar con un prompt personalizado más ligero.

¿github-triage reemplaza a los maintainers?

No. La skill ayuda a los maintainers a estandarizar decisiones, recopilar información faltante y preparar issues para su ejecución. No elimina la necesidad de criterio sobre alcance, roadmap o dirección de producto.

Cómo mejorar la skill github-triage

Dale a github-triage un entorno de trabajo más limpio

La forma más rápida de mejorar los resultados de github-triage es ordenar primero tus labels. La skill da lo mejor de sí cuando el repo tiene:

• ausencia de labels de estado duplicadas
• ausencia de significados solapados entre estados
• labels de categoría claras
• definiciones acordadas para ready-for-agent y ready-for-human

Si tus labels son caóticas, la salida se sentirá insegura porque el propio flujo también lo es.

Proporciona mejor contexto del issue desde el principio

La skill funciona mejor cuando el issue ya incluye señales útiles como:

• pasos reproducibles
• comportamiento esperado y comportamiento real
• capturas de pantalla o logs
• versión y detalles del entorno
• un resultado claro para la feature request

Esto reduce preguntas innecesarias y hace más fiable la decisión de estado.

Pide decisiones, no resúmenes

Un fallo habitual es pedirle a github-triage que “revise” un issue sin solicitar una transición de estado. Mejor forma de plantearlo:

• pide la label de categoría exacta
• pide la label de estado exacta
• pregunta si el issue está listo para agente, persona, más información o rechazo
• pide una justificación breve

Así obtienes resultados sobre los que puedes actuar de inmediato.

Mejora la calidad de los handoffs ready-for-agent

Si github-triage marca algo como ready-for-agent, revisa el brief en busca de estas debilidades:

• instrucciones procedimentales en lugar de especificaciones de comportamiento
• referencias a file paths frágiles
• criterios de aceptación vagos
• ausencia de edge cases o condiciones de fallo

Un brief más sólido debería seguir siendo útil aunque el repo cambie y aun así dejar claro para un agente cómo se ve el éxito.

Usa preguntas de aclaración más acotadas

Otro fallo habitual es preguntar de más. Puedes mejorar la salida de la skill indicándole que solo haga preguntas que desbloqueen el siguiente cambio de estado. Por ejemplo:

• buena: “What exact error message do you see?”
• débil: “Can you describe the issue in more detail?”

Las preguntas específicas hacen que los issues en needs-info sean más fáciles de resolver.

Añade y mantén memoria de out-of-scope

Si tu proyecto rechaza repetidamente las mismas clases de solicitudes, mantener contenido en .out-of-scope/ hace que github-triage sea más útil con el tiempo. Esto mejora la consistencia, acelera el triage y conserva el razonamiento para futuros maintainers.

Revisa las primeras ejecuciones para detectar deriva de estado

Al adoptar github-triage install en un repo real, revisa el primer lote de issues clasificados para detectar:

• ausencia de labels de categoría
• varias labels de estado en un mismo issue
• uso excesivo de needs-info
• ready-for-agent prematuro
• razonamientos inconsistentes para wontfix

Estas señales hablan de la adopción, no solo de problemas en la salida. Ajusta la política y luego vuelve a usar la skill.

Itera endureciendo el contrato del prompt

Si la primera salida es demasiado laxa, no pidas simplemente “más detalle”. Refina el contrato del prompt. Ejemplo:

• “Re-run github-triage on issue #142. Keep exactly one category and one state label, propose at most 3 clarifying questions, and only mark ready-for-agent if you can write acceptance criteria that are independently testable.”

Ese tipo de restricción mejora más la fiabilidad que pedir una respuesta más larga.

Define los umbrales propios de tu repositorio

La mejora más importante es acordar qué califica para cada estado en tu repo. github-triage te da un marco, pero tu equipo debería definir umbrales como:

• cuándo un bug tiene suficiente detalle de reproducción
• cuándo una mejora está lo bastante definida para implementarse
• cuándo algo realmente queda fuera de alcance
• cuándo hace falta juicio humano en lugar de ejecución por parte de un agente

Una vez que esos umbrales quedan explícitos, la github-triage skill se vuelve mucho más consistente y valiosa.