xufang5219/agent-skills

Pregúntale a Matt

No recuerdas todas las habilidades, así que pregunta.

Antes de decir lo que hace una habilidad o recomendar que se salte un paso, lee el SKILL.md de esa habilidad: los resúmenes aquí son solo para orientación.

Un flujo es un camino a través de las habilidades. La mayoría de los caminos recorren un flujo principal y dos rampas de entrada se fusionan en él. Todo lo demás es independiente, o una capa de vocabulario que funciona por debajo.

El flujo principal: idea → envío

La ruta que recorre la mayor parte del trabajo. Tienes una idea y quieres que se construya.

1. /grill-with-docs afina la idea mediante una entrevista. Comienza aquí siempre que trabajes en un directorio de trabajo: tiene estado, conservando lo que aprende en GLOSSARY.md y ADR. (¿No hay directorio de trabajo? Usa /grill-me en su lugar, cubierto en Independiente. Ambos ejecutan la misma primitiva /grilling; grill-with-docs es el que deja un rastro documental, lo que lo convierte en el mejor de los dos siempre que haya un repositorio donde dejarlo).

2. Rama: ¿puedes resolver todas las preguntas en la conversación? Si una pregunta necesita una respuesta ejecutable (estado, lógica de negocio, una interfaz de usuario que tengas que ver), desvía a través de un prototipo, puenteado por /handoff en ambas direcciones (un prototipo vive en su propio directorio, que es exactamente para lo que sirve /handoff; consulta Límites de fase):

   • /handoff hacia afuera, luego abre una nueva sesión contra ese archivo,
   • /prototype para responder a la pregunta con código desechable,
   • /handoff de vuelta lo que aprendiste, y referéncialo desde el hilo de la idea original.

3. Rama: ¿Es una construcción de múltiples sesiones?

   • Sí → /to-spec (convierte el hilo en una especificación), luego /to-tickets para dividirlo en tickets trazadores, cada uno declarando sus bordes bloqueantes. Luego trabaja los tickets de una de dos maneras:
     • /implement por ticket, limpiando el contexto entre cada uno. En un rastreador local, es un archivo por ticket en .scratch/<feature>/issues/, trabajados primero los bloqueantes a mano; en un rastreador real, los bordes se convierten en enlaces bloqueantes nativos, por lo que cualquier ticket cuyos bloqueantes estén hechos se puede tomar. Cada ticket es autocontenido, por lo que el contexto del último es desechable.
     • /implement-spec para toda la especificación en una sola ejecución. Lee los tickets como un grafo de tareas, ejecuta agentes implementadores en la frontera lista en paralelo y unifica todo en una rama de integración. Recurre a él cuando prefieras orquestar la construcción en lugar de impulsar cada ticket tú mismo.
   • No → /implement aquí mismo, en la misma ventana de contexto.

   De cualquier manera, el código se construye impulsando /tdd (una rebanada rojo-verde a la vez) y se cierra con /code-review, una revisión de dos ejes (Estándares + Especificación) del diff. /implement ejecuta ambos por ticket; los implementadores de /implement-spec impulsan /tdd, y ejecuta un /code-review sobre la rama de integración. Recurre a /tdd por sí solo cuando solo quieras construir un comportamiento concreto con pruebas primero sin una especificación completa, y a /code-review por sí solo cada vez que quieras revisar una rama o PR contra un punto fijo.

   Cuando el trabajo sube como una solicitud de extracción, /pr da forma al cuerpo: el visual más pequeño que muestra el cambio, evidencia de antes/después de que funciona, y una llamada de puerta unidireccional o bidireccional. Es invocado por el modelo, por lo que el agente recurre a él cada vez que escribe un PR.

4. /retro cierra el ciclo. Después de una construcción, y especialmente de una que salió mal, revisa la sesión y sugiere cambios en el entorno del agente, no en el código: punteros de navegación, comprobaciones automatizadas, los estándares de codificación que /code-review aplica, archivos de dirección, herramientas. Los errores mecánicos se convierten en comprobaciones deterministas; los juicios se convierten en estándares de codificación. La siguiente construcción comienza entonces desde un entorno mejor.

Higiene del contexto

Mantén los pasos 1–3 en una ventana de contexto ininterrumpida (no compactes ni limpies hasta después de /to-tickets) para que la entrevista, la especificación y los tickets se construyan sobre el mismo pensamiento. Cada /implement comienza entonces fresco, trabajando desde el ticket. Ejecuta /retro en la sesión que está revisando, antes de limpiar; después de limpiar, apúntalo al registro de esa sesión.

El límite de esto es la zona inteligente: la ventana (~150k tokens en modelos de última generación) dentro de la cual el modelo aún razona con claridad. Si una sesión se acerca a ella antes de /to-tickets, no sigas con rendimiento degradado; /compact en el límite de fase más cercano y continúa (consulta Límites de fase).

Rampas de entrada

Una situación inicial que genera trabajo y luego se fusiona con el flujo principal.

• Errores y solicitudes acumulándose → /triage. Mueve los issues a través de roles de triaje y produce issues listos para el agente, que /implement recoge más tarde.

  El triaje es solo para issues que no creaste tú: informes de error, solicitudes de funciones entrantes, cualquier cosa que llegue en bruto. Los tickets que /to-tickets produjo ya están listos para el agente, así que no los triajes.

• Algo está roto → /diagnosing-bugs. Para los difíciles: el error que resiste un primer vistazo, la falla intermitente, la regresión que se coló entre dos estados conocidos como buenos. Se niega a teorizar hasta que tenga un bucle de retroalimentación ajustado (un comando que ya se vuelve rojo en este error), luego arregla con una prueba de regresión. Una vez que la corrección está hecha, ejecuta /retro en la misma sesión para preguntar qué habría prevenido el error; donde el hallazgo real es que no hay un buen punto de ruptura para asegurarlo, ese es un trabajo para /improve-codebase-architecture.

• Un esfuerzo enorme y difuso: un proyecto desde cero o una gran construcción de funcionalidad, demasiado grande para una sesión → /wayfinder, el flujo más exigente cognitivamente aquí. Cuando el camino desde aquí hasta el destino aún no es visible, traza un mapa compartido de tickets de decisión en el rastreador de issues y los resuelve uno a la vez, produciendo decisiones, no entregables, hasta que la niebla se disipe y el camino esté claro. Mientras que /grill-with-docs afina una idea que puedes sostener en una sesión, wayfinder es para la idea que no puedes, y es más lento y denso, así que guárdalo exactamente para eso, nunca para una funcionalidad bien definida.

  Cuando el mapa se aclara, entrega, no construye: fusiona con el flujo principal en /to-spec, que colapsa las decisiones vinculadas del mapa en un plan construible, luego /to-tickets y /implement como de costumbre. Pasar el mapa directamente a /implement omite ese colapso y tira los detalles vinculados, así que ve directamente a /implement solo cuando el esfuerzo resultó ser realmente pequeño.

Salud del código base

No es trabajo de funcionalidad, solo mantenimiento.

• /improve-codebase-architecture se ejecuta cada vez que tengas un momento libre para mantener el código base en buen estado para que los agentes operen en él. Superficializa oportunidades de profundización; elegir una genera una idea que puedes llevar al flujo principal en /grill-with-docs. Es el estudio que encuentra los candidatos; /codebase-design (abajo) es el banco donde diseñas el elegido.

Vocabulario subyacente

Dos referencias invocadas por el modelo que funcionan debajo de las otras habilidades, cada una es la única fuente de verdad para su vocabulario. Recurre a ellas directamente cuando las palabras, no el proceso, son el problema; o deja que las habilidades anteriores las incorporen.

• /domain-modeling: agudiza el lenguaje del dominio del proyecto: desafía un término difuso, resuelve una palabra sobrecargada ("cuenta" haciendo tres trabajos), registra una decisión difícil de revertir como un ADR. Es la disciplina activa que /grill-with-docs impulsa para mantener GLOSSARY.md como un glosario limpio.
• /codebase-design es el vocabulario de módulo profundo (módulo, interfaz, profundidad, punto de ruptura, adaptador, apalancamiento, localidad) para diseñar la forma de un módulo: mucho comportamiento detrás de una interfaz pequeña en un punto de ruptura limpio. /tdd y /improve-codebase-architecture hablan ambos en él.

Límites de fase

Una fase es un fragmento de trabajo dentro de una sesión: la entrevista, la implementación, el control de calidad. En el límite entre dos de ellas tienes cinco opciones, y elegir entre ellas es la decisión más difusa en todo este mapa:

• Continuar: quédate quieto. No cuesta nada, no pierde nada.
• /clear: vacía la ventana, cuando nada de esto importa para lo que sigue.
• /handoff escribe un archivo markdown portátil. Estrecho: solo para un nuevo arnés, un nuevo directorio, un colega, o bifurcar una tarea secundaria en medio de una fase. Lo que compra es portabilidad.
• Subagente: envía una tarea con un alcance muy ajustado a su propia ventana y recibe un informe.
• /compact comprime este contexto y siembra una nueva sesión con él. El predeterminado, en la parte inferior del árbol en lugar del primer recurso.

Lee PHASE-BOUNDARIES.md para el árbol ordenado: las cinco preguntas, el razonamiento detrás de cada rama, y por qué el costo de la fuente principal hace que Continuar sea el que hay que descartar primero. Toma la decisión en un límite; en medio de una fase, continúa o divide el resto en subagentes.

Independiente

Completamente fuera del flujo principal.

• /grill-me: la misma entrevista implacable que /grill-with-docs, pero sin estado: no guarda nada localmente y no construye un GLOSSARY.md. Recurre a él cuando no estés trabajando en un directorio de trabajo (afinando un plan, un diseño, un escrito, cualquier cosa sin un repositorio debajo). Si estás en un directorio de trabajo, usa /grill-with-docs en su lugar: ejecuta la misma entrevista y deja un rastro documental, por lo que es estrictamente el mejor.
• /grilling es la primitiva de entrevista en sí misma: rondas, la frontera, los hechos son trabajo del agente y las decisiones son tuyas. /grill-me y /grill-with-docs son las dos formas nombradas de entrar, y /triage, /wayfinder e /improve-codebase-architecture todas lo ejecutan internamente. Recurre a él directamente solo cuando quieras la entrevista sin envoltorio.
• /prototype es un programa pequeño y desechable que responde a una pregunta de diseño: ¿este modelo de estado se siente correcto, o cómo debería verse esta interfaz de usuario? Desechable es una restricción sobre cómo se escribe el código, no una promesa de destruirlo: la respuesta se pliega en el código real, y el prototipo en sí se mantiene como una fuente primaria en una rama prototype/<name> desde main, apuntada desde el issue de implementación. Es el desvío en el paso 2 del flujo principal, pero recurre a él cada vez que una pregunta de diseño es difícil de resolver en papel.
• /research: delega el trabajo de lectura a un agente de fondo: investiga una pregunta contra fuentes primarias, luego deja un archivo Markdown citado en el repositorio. Sigue trabajando mientras lee. El archivo que produce es algo para llevar al flujo principal en /grill-with-docs, ya que la investigación alimenta el pensamiento en lugar de reemplazarlo.
• /to-questionnaire entra en juego cuando lo que te bloquea no está en tu cabeza ni en el código base, sino en la cabeza de otra persona, y les escribe un cuestionario para que lo llenen. Es el inverso de /grill-me: en lugar de entrevistarte a ti sobre el tema, te entrevista a ti sobre el envío (a quién va dirigido, qué necesitas de vuelta) y apunta las preguntas a la brecha. Lo que vuelve es material para /grill-with-docs o /to-spec.
• /wizard es para los pasos que solo un humano puede tomar: aprovisionar infraestructura, configurar credenciales o secretos de CI, navegar por un panel de control de terceros desconocido, ejecutar una migración o corte único. Genera un script bash interactivo que abre cada URL, captura cada valor y lo escribe en .env y secretos de GitHub, para que el procedimiento deje de ser algo que re-explicas a un agente cada vez. Invocado por el modelo, por lo que el agente recurre a él en el momento en que se encuentra con un muro que solo tú puedes pasar. Si el agente pudiera hacerlo solo, debería; esto es para cuando un humano está realmente en el bucle.
• /wait-what es el correctivo para un mensaje que no llegó. Úsalo en medio de una conversación, dentro de cualquier otra habilidad, y el agente reformula lo que acaba de decir con el contexto que te faltaba, en español sencillo, usando el vocabulario de GLOSSARY.md. Funciona después del hecho; /grill-with-docs es la cura preventiva, porque un lenguaje compartido acordado temprano es lo que evita que la jerga llegue en absoluto.
• /teach: aprende un concepto a lo largo de múltiples sesiones, usando el directorio actual como un espacio de trabajo con estado.
• /writing-for-agents es la referencia para escribir documentos que los agentes consumen: habilidades, AGENTS.md, documentos a los que se apunta.

Precondición

/setup-matt-pocock-skills: ejecútalo antes de tu primer flujo de ingeniería para configurar el rastreador de issues, las etiquetas de triaje y el diseño de documentos que las otras habilidades asumen. Los rastreadores de issues personalizados también funcionan.