handoff y to-questionnaire: pasar el contexto a otro agente o a otra persona sin perder nada

Tarde o temprano el trabajo con un agente tiene que salir de la sesión. A veces lo continúa otro agente (en otra herramienta, en otra carpeta, en una sesión limpia). Otras veces lo que falta está en la cabeza de otra persona que no está en la conversación. handoff y to-questionnaire son las dos skills de Matt Pocock para esos dos casos: una escribe el contexto para que otro lo continúe, la otra escribe las preguntas para que otro lo complete.

Es la undécima parte de la guía de las skills de Matt Pocock (repositorio mattpocock/skills, licencia MIT). Las dos se invocan a mano.

Por qué van juntas

Ambas producen un documento Markdown portátil pensado para un lector que no estuvo en la conversación:

handoff: un documento para que otro agente continúe

/handoff resume la conversación actual en un documento para que un agente nuevo siga el trabajo. Sus reglas:

• Se guarda en el directorio temporal del sistema ($TMPDIR, /tmp o %TEMP% en Windows), no en el proyecto.
• Incluye una sección de skills sugeridas: qué skills debería cargar el siguiente agente.
• No duplica: lo que ya está en specs, planes, ADR, issues, commits o diffs se referencia por ruta o URL, no se copia.
• Censura datos sensibles: claves de API, contraseñas e información personal.
• Acepta un argumento: "¿para qué se usará la siguiente sesión?". Con él, el documento se centra en lo que esa sesión necesita.

Cuándo usarla (y cuándo no)

ask-matt es muy preciso aquí. En la frontera entre fases tienes cinco opciones: continuar, /clear, /handoff, un subagente o /compact. /handoff es estrecha: solo hace falta cuando:

• cambias de herramienta (de Claude Code a Codex, por ejemplo),
• cambias de directorio o de repositorio,
• se lo pasas a un compañero,
• o separas una tarea lateral que encontraste a mitad de fase sin desviarte de lo que estabas haciendo.

"Esa lista es toda la cláusula." Lo que /handoff compra es portabilidad: un fichero que viaja. Si nada viaja, no la necesitas. Para seguir en la misma herramienta y carpeta, /compact es la opción por defecto.

El uso más característico está en el flujo de prototipos de la parte 9: /handoff hacia una sesión nueva en la carpeta del prototipo, prototype allí, y /handoff de vuelta con lo aprendido.

Fuente primaria y fuente secundaria

El repositorio explica el coste de cualquier cambio de sesión con una idea útil: todo lo que no sea continuar convierte una fuente primaria (la sesión tal como ocurrió) en una fuente secundaria (un resumen). El resumen tiene menos ruido y deja más espacio, pero pierde información. El fallo típico, según el autor, es "una sesión nueva que está segura de algo equivocado sobre una decisión que el resumen aplanó". Por eso /handoff referencia los artefactos originales en lugar de resumirlos.

to-questionnaire: sacar lo que solo otra persona sabe

/to-questionnaire aparece cuando lo que te bloquea no está ni en tu cabeza ni en el código, sino en la de otra persona: el cliente que sabe cómo factura, el contable que conoce la norma, el responsable de infraestructura que sabe qué carga se espera. La skill escribe un cuestionario para que esa persona lo rellene sola, o para rellenarlo juntos en una reunión.

Pregunta sobre el envío, no sobre el tema

Es lo contrario de grill-me. En lugar de interrogarte sobre el tema (que no puedes responder, por eso necesitas a otra persona), te pregunta sobre el envío, que sí sabes:

1. ¿A quién va? Su rol, su experiencia y su relación contigo. Fija el tono y cuánto contexto debe llevar el documento.
2. ¿Qué necesitas de vuelta? Las decisiones o datos concretos que no puedes resolver solo.
3. Escribe el cuestionario apuntando al hueco entre lo que sabe esa persona y lo que necesitas, y te da la ruta del fichero.

La estructura del documento

• Título, propósito (por qué existe y qué decisión depende de él), de quién a quién y cómo se usarán las respuestas.
• Contexto: un párrafo para orientar a alguien que no estaba en tu cabeza.
• Cómo responder: plazo, esfuerzo aproximado y una invitación explícita a decir "no lo sé" en lugar de saltar preguntas.
• Secciones por tema, con las preguntas más importantes primero (puede que solo tengas una pasada). Cada pregunta es una sola idea, con su hueco de respuesta debajo y, solo si hace falta, una línea de *por qué importa*.
• ¿Algo más?: una pregunta final abierta.

Un ejemplo con el formato de la skill:

### ¿Cuántos suscriptores esperas en los primeros tres meses?

_Por qué importa: decide si empezamos en el plan gratuito del proveedor o contratamos uno de pago desde el principio._

>

Cómo se combinan

Las dos cierran huecos que el agente no puede cerrar desde dentro de la sesión, y encajan con el resto del flujo:

• Lo que vuelve de to-questionnaire es material de entrada para grill-with-docs o to-spec. Las respuestas resuelven ramas del árbol de decisiones que se habían quedado abiertas.
• Si el cuestionario tarda días en volver, /handoff guarda dónde estabas, con la ruta del cuestionario como referencia, para que la sesión que reciba las respuestas sepa qué hacer con ellas.

Un caso práctico: en el ejemplo del ebook de la parte 3, el agente no podía saber el tráfico real del blog ni las comisiones exactas. Un cuestionario a quien gestiona la analítica y la cuenta de pagos, más un /handoff con el estado de la sesión, cierran ese hueco sin perder el resto del razonamiento.

Errores frecuentes

• Usar /handoff para seguir en la misma herramienta y carpeta. /compact o continuar son más baratos.
• Copiar en el handoff lo que ya está en un issue. Referencia, no dupliques.
• Preguntas compuestas en el cuestionario. "¿Qué carga esperas y en qué región?" son dos preguntas.
• Enviar el cuestionario sin contexto. Sin el párrafo de contexto, el destinatario responde a medias.

Preguntas frecuentes

¿El handoff se guarda en el repositorio? No, en el directorio temporal del sistema, para no ensuciar el proyecto. Si lo necesitas en otro sitio, muévelo tú.

¿Puedo usar el cuestionario en una reunión? Sí: la skill lo contempla, para rellenarlo juntos en directo.

¿Hay una versión automática de handoff? En in-progress/ hay una skill beta, claude-handoff, que lanza un agente en segundo plano con claude --bg a partir del resumen. No está en el plugin.

Siguiente paso

La próxima vez que vayas a copiar y pegar una conversación en otra herramienta, usa /handoff con un argumento que diga para qué es la siguiente sesión. En la parte 12 de la guía vemos pr y wizard: cómo presentar el trabajo en un pull request y cómo guiar a una persona por los pasos que el agente no puede dar.