handoff

handoff es un Skill de la biblioteca de herramientas open source de Matt Pocock pensado para gestionar el traspaso de trabajo en sesiones largas. Su definición oficial es muy sencilla: convertir la conversación actual en un documento de handoff que permita a otro Agent continuar el trabajo.

Es un Skill activado explícitamente por el usuario. Solo se ejecuta cuando se introduce /handoff; disable-model-invocation: true significa que el propio AI no decide utilizarlo por iniciativa propia.

El problema que intenta resolver es muy concreto: la ventana de contexto de un LLM es limitada y, cuando una sesión se alarga demasiado, el rendimiento puede deteriorarse. AI Hero describe esta zona como la “dumb zone”, que en modelos frontier suele aparecer aproximadamente a partir de 125K–150K tokens y puede traducirse en respuestas más descuidadas, olvidos y un mayor número de errores.

Pero la diferencia fundamental respecto a un simple prompt del tipo “resume esta conversación” está en el objetivo: handoff no está pensado principalmente para comprimir información, sino para hacer que el trabajo sea portable. La documentación oficial lo resume como “What it buys is portability, not compression”.

El resultado se guarda en un directorio temporal del sistema en lugar de formar parte del workspace. Además, los artefactos existentes se referencian en lugar de copiarse y el documento incluye una sección con el Skill que el siguiente Agent debería utilizar.

¿Por qué AI Coding necesita Handoff?

Imagina una funcionalidad en la que un Agent lleva varias horas trabajando. Durante ese tiempo ha leído mucho código, realizado algunos cambios, investigado varios problemas, tomado decisiones provisionales, encontrado un bloqueo que todavía no ha resuelto y determinado cuál debería ser el siguiente paso.

Entonces ocurre cualquiera de estas situaciones: el contexto está casi lleno, termina la jornada, quieres cambiar de Agent o necesitas abrir una sesión independiente para investigar un problema.

Si simplemente creas una nueva sesión, puedes perder una gran cantidad de estado de trabajo en curso.

Lo que realmente necesitas conservar no es todo el historial de la conversación, sino algo mucho más concreto:

• qué se está haciendo;
• por qué se ha llegado hasta ese punto;
• qué se ha completado;
• dónde está el bloqueo actual;
• qué debería hacerse a continuación;
• dónde está la información relevante.

Ese es precisamente el espacio que intenta ocupar handoff.

¿Qué conserva realmente handoff?

handoff conserva el Live Thread, es decir, el hilo de trabajo actual, no todo el conocimiento del proyecto.

Su principio de diseño más importante es “referenciar en lugar de copiar”. El SKILL.md indica explícitamente que no se debe duplicar información que ya haya sido capturada por otros artefactos, como specs, planes, ADR, issues, commits o diffs. En su lugar, se deben incluir las rutas o URL correspondientes.

La ventaja es evidente: menos duplicación, menos contexto, menos posibilidades de contradicción y menos riesgo de que distintas copias de un mismo documento terminen desactualizadas.

El conocimiento estable del proyecto debería permanecer en CONTEXT.md, SPEC, ADR y otros artefactos formales. handoff se ocupa de aquello que todavía no ha quedado registrado en otro lugar: el estado temporal del trabajo.

Sin embargo, este diseño también tiene una debilidad.

Si el archivo referenciado desaparece, cambia o el nuevo Agent no consigue localizarlo, el handoff pierde parte de su utilidad.

El Issue #186 revela un problema todavía más interesante: en muchas sesiones, la propia conversación es el único artefacto existente. No hay ADR, PRD ni plan. En esos casos, aplicar estrictamente la regla de “referenciar en lugar de copiar” puede provocar que información importante desaparezca.

handoff frente al historial completo de la conversación

Entregar toda la conversación anterior a un nuevo Agent parece, en principio, la solución más completa. En la práctica puede ser justo lo contrario.

Un historial largo contiene decisiones, pero también preguntas ya resueltas, alternativas descartadas, experimentos, discusiones preliminares y mucho contexto que ya no resulta relevante.

El nuevo Agent tiene entonces que realizar un trabajo adicional:

leer el pasado y reconstruir el presente.

handoff intenta invertir este proceso. En lugar de conservarlo todo, selecciona la información necesaria para que otro Agent pueda continuar.

Por eso, una conversación completa no siempre es el mejor contexto posible. Más información no significa necesariamente mejor contexto. Para un Agent que entra a mitad del trabajo, conocer exactamente qué está pendiente puede ser más útil que recibir cientos de mensajes sobre decisiones que ya quedaron descartadas.

handoff frente a compact

Esta es probablemente la distinción más importante.

/compact resuelve el problema de un contexto demasiado largo. El trabajo continúa dentro de la misma sesión y simplemente necesitas reducir el tamaño de la conversación para poder seguir trabajando.

/handoff, en cambio, resuelve el problema de que el trabajo necesita desplazarse a otro lugar.

AI Hero propone un criterio especialmente útil:

Situación	Herramienta	Motivo
Mismo harness y mismo directorio, pero el contexto es demasiado largo	/compact	El trabajo no se está desplazando
Cambiar de harness, por ejemplo Claude → Codex	/handoff	El nuevo harness no tiene el contexto anterior
Cambiar de directorio o repositorio	/handoff	El trabajo cambia de entorno
Entregar el trabajo a otro desarrollador	/handoff	La otra persona necesita un contexto legible
Crear una tarea paralela a mitad del trabajo	/handoff	Otro Agent puede continuar una rama independiente

El criterio puede resumirse de una manera muy sencilla:

¿El trabajo está “viajando”?

Si la respuesta es no, normalmente basta con /compact.

Si la respuesta es sí, /handoff tiene mucho más sentido.

La formulación de AI Hero es especialmente clara: /compact conserva tu intención, /clear no conserva nada y /handoff conserva la capacidad del trabajo para desplazarse.

handoff frente a la documentación del proyecto

La documentación del proyecto responde principalmente a preguntas como:

¿Qué es este proyecto, cómo debería funcionar y por qué está diseñado de esta manera?

Un handoff responde a otra pregunta:

¿Hasta dónde he llegado, por qué he llegado hasta aquí y qué debería hacer ahora?

La diferencia fundamental es:

conocimiento del proyecto frente a estado actual del trabajo.

Esto cubre un espacio que normalmente queda entre la documentación formal y el historial de conversación.

Durante el desarrollo existen muchas cosas que todavía no merecen convertirse en una spec o ADR:

• qué se está investigando;
• qué alternativa acaba de descartarse;
• por qué un bug sigue sin solución;
• hasta dónde llegan los cambios actuales;
• qué prueba debería ejecutarse después.

Si todo esto vive únicamente dentro del contexto del Agent, puede desaparecer al terminar la sesión.

Ahí es donde handoff tiene su argumento más sólido.

¿Funciona realmente el traspaso entre Agents?

Mismo Agent, mismo proyecto

Si el único problema es que la conversación se ha hecho demasiado larga, normalmente es mejor utilizar /compact.

No hace falta crear un handoff simplemente para seguir trabajando en el mismo entorno.

Agents diferentes

Aquí aparece el caso de uso más interesante.

Por ejemplo:

Claude Code → Codex

El nuevo harness no tiene acceso al contexto de la sesión anterior. Un handoff puede actuar como puente entre ambos.

No elimina la necesidad de leer código, pero evita tener que reconstruir desde cero el estado mental de la sesión anterior.

Desarrolladores diferentes

El concepto también funciona fuera de los Agents.

Si una persona deja una tarea a medio terminar y otra debe continuarla, un documento que explique qué se ha hecho, qué queda pendiente y dónde están las referencias relevantes puede ser mucho más útil que entregar todo el historial de chat.

Side Task / Prototype

Este es probablemente uno de los usos más interesantes y menos evidentes.

Imagina que estás trabajando en una discusión de arquitectura y aparece una pregunta que solo puede responderse ejecutando código. No quieres consumir el contexto de la sesión principal ni mezclar el experimento con el trabajo actual.

Puedes crear una sesión de Prototype, hacer el experimento, obtener la respuesta y después devolver el resultado al flujo principal mediante otro handoff.

Dos cruces entre sesiones, una conversación principal activa y sin necesidad de volver a explicar todo desde cero.

Una experiencia práctica de desarrollo

Supongamos que estás construyendo un nuevo módulo de pagos.

Sesión 1

El Agent analiza el proyecto, localiza los módulos relacionados con pagos, modifica parte del código y descubre un problema arquitectónico. El trabajo queda incompleto.

Sesión 2

Con handoff, el flujo ideal sería:

leer handoff → localizar archivos → consultar spec/ADR → revisar diff → continuar.

Sin handoff:

releer conversaciones → leer código → reconstruir el progreso → hacer preguntas → continuar.

La diferencia parece evidente, pero no conviene exagerarla.

El Issue #186 muestra precisamente dónde puede fallar este modelo. Según la experiencia descrita allí, al generar un handoff después de una sesión larga de planificación, el documento podía conservar un resumen de las decisiones pero perder silenciosamente información como:

• alternativas descartadas;
• restricciones sutiles asociadas a decisiones aceptadas;
• valores numéricos por defecto;
• prioridades;
• orden de implementación.

El problema de fondo es importante:

“resumir” y “archivar decisiones” no son exactamente la misma operación.

Para un LLM, resumir normalmente significa conservar los puntos principales y eliminar detalles secundarios. Pero en ingeniería, algunos de esos detalles aparentemente secundarios pueden ser precisamente los que determinan cómo debe implementarse una decisión.

¿Puede handoff crear nuevos problemas?

Sí.

Entre sus principales limitaciones están:

• genera trabajo adicional antes de cerrar una sesión;
• el Agent puede omitir información importante;
• puede interpretar incorrectamente el estado actual;
• el documento puede quedar obsoleto;
• el nuevo Agent puede no leer correctamente todas las referencias;
• si la documentación del proyecto ya es deficiente, handoff solo transmite parte de ese problema;
• para tareas muy cortas puede ser una capa innecesaria;
• requiere que el usuario lo invoque manualmente.

No son simplemente inconvenientes teóricos. Algunos ya han aparecido en experiencias de usuarios.

La respuesta de Matt Pocock al Issue #186 también resulta interesante: cuestiona si determinados problemas de sesiones largas pueden ser simplemente una limitación general de los LLM con ventanas de contexto extensas que ningún ajuste del Skill puede solucionar completamente.

Esto es importante porque evita atribuir a handoff una capacidad que realmente pertenece al modelo.

handoff frente a otras soluciones de contexto

Solución	Adecuada para conservar	No adecuada para conservar
Historial completo del chat	Historia completa	Estado actual, por exceso de ruido
TODO manual	Próximas acciones sencillas	Contexto y razones de las decisiones
README	Conocimiento general del proyecto	Estado de trabajo actual
CONTEXT.md	Conceptos y contexto estable	Progreso temporal
/compact	Contexto comprimido de la sesión actual	Transferencia entre sesiones o Agents
Git commit message	Cambios realizados	Contexto completo del trabajo
handoff	Dónde está el trabajo, por qué está ahí y qué hacer después	Conocimiento permanente del proyecto

La diferencia más importante es que cada mecanismo tiene una responsabilidad distinta.

Git conserva el estado del código.

SPEC y ADR conservan decisiones y diseño.

CONTEXT.md conserva conceptos relevantes del proyecto.

compact permite seguir trabajando dentro del mismo contexto.

handoff conserva el estado temporal necesario para trasladar el trabajo.

¿Merece la pena convertir handoff en parte del flujo estándar?

Para un desarrollador que trabaja principalmente en tareas pequeñas, probablemente no.

Si una funcionalidad tarda diez minutos en implementarse, crear un documento de handoff puede costar más que simplemente terminarla.

Pero la situación cambia cuando el trabajo dura días, requiere varias sesiones o implica múltiples Agents.

Desarrolladores normales

Si trabajas durante horas en una misma sesión o cambias frecuentemente de Agent, instalarlo puede tener sentido.

Proyectos de larga duración

Cuando una funcionalidad se desarrolla durante varios días y atraviesa múltiples sesiones, el valor aumenta considerablemente.

Flujos multi-Agent

Este es probablemente el escenario donde handoff ofrece su mayor ventaja. El caso de fork, es decir, separar temporalmente una tarea secundaria y después devolver el resultado al flujo principal, es especialmente interesante.

Tareas pequeñas

Aquí puede convertirse fácilmente en sobreingeniería.

Ventajas

• Conserva el estado del trabajo en curso: la documentación guarda lo establecido; handoff guarda lo que todavía está sucediendo.
• Permite que el trabajo “viaje”: entre Agents, directorios, desarrolladores o tareas paralelas.
• Referencia en lugar de duplicar: reduce documentos innecesarios y contradicciones.
• Sugiere el siguiente Skill: ayuda a orientar la primera acción del siguiente Agent.
• Incluye mecanismos de desidentificación: elimina automáticamente determinados secretos y datos personales.
• Permite enfocar el handoff: el propósito de la siguiente sesión puede utilizarse para limitar qué información debe incluirse.
• Es ligero: el SKILL.md contiene solo unas pocas líneas de instrucciones esenciales y no obliga a adoptar un proceso de desarrollo completo.

Desventajas y limitaciones

• Depende de la capacidad del Agent para resumir correctamente: el Issue #186 muestra que pueden perderse alternativas descartadas y restricciones importantes.
• “Referenciar en lugar de copiar” puede ser problemático cuando la conversación es el único artefacto existente.
• El nuevo Agent sigue necesitando leer el código y los archivos referenciados.
• No es una base de conocimiento: no sustituye CONTEXT.md, SPEC ni ADR.
• No sincroniza automáticamente el proyecto: el usuario debe invocarlo.
• Tiene poco valor en tareas pequeñas.
• Puede presentar problemas de compatibilidad con archivos temporales en determinados entornos, como el comportamiento de mktemp en macOS/BSD.
• El documento puede quedar obsoleto.
• No sustituye Git: handoff conserva contexto de trabajo; Git conserva el estado del código.

Evaluación final

Puntuación: 4,0/5,0

Criterio	Puntuación
---	---:
Gestión del contexto	4,0/5
Transferencia entre Agents	5,0/5
Soporte para sesiones largas	4,5/5
Flujos multi-Agent	4,5/5
Ahorro real de tiempo	3,5/5
Precisión de la información	3,0/5
Facilidad de uso	5,0/5
Complejidad del flujo	4,5/5
Integración con herramientas de ingeniería	4,5/5

Entonces, ¿realmente sirve handoff?

Sí, pero resuelve un problema muy específico: trasladar el estado de un trabajo de una sesión a otra.

Si nunca necesitas cambiar de sesión, Agent o entorno, probablemente no lo necesitas.

¿Cuál es la diferencia principal entre handoff y compact?

compact responde a:

“El contexto es demasiado largo, pero sigo trabajando aquí.”

handoff responde a:

“Este trabajo necesita moverse a otro lugar.”

Si el trabajo no está “viajando”, utiliza compact. Si necesita viajar, utiliza handoff.

¿Y frente a CONTEXT.md, SPEC o ADR?

La diferencia está en el tipo de información.

handoff conserva dónde está el trabajo ahora.

CONTEXT.md, SPEC y ADR conservan qué es el proyecto, cómo funciona y por qué se ha diseñado de determinada manera.

Por tanto, handoff no sustituye estos artefactos. Ocupa el espacio intermedio entre la documentación formal y el contexto temporal del chat.

¿Cuándo debería utilizarse?

Principalmente en cuatro situaciones:

1. Cambiar de Agent.
2. Mover el trabajo a otro directorio o entorno.
3. Entregar el trabajo a otro desarrollador.
4. Crear una tarea paralela a mitad del trabajo y después devolver sus resultados al flujo principal.

¿Cuándo no hace falta?

Cuando continúas en la misma sesión, cuando solo necesitas reducir el contexto o cuando la tarea es tan pequeña que terminarla resulta más sencillo que documentarla.

¿Debería instalarlo un usuario normal de AI Coding?

Sí, pero con condiciones.

Si utilizas AI principalmente para scripts sencillos y tareas cortas, probablemente no notarás ningún beneficio.

Si trabajas en proyectos medianos o grandes, mantienes sesiones largas, cambias de Agent con frecuencia o utilizas varios Agents para desarrollar distintas partes del mismo proyecto, handoff puede convertirse en uno de los Skills más útiles de tu flujo de trabajo.

El propio Matt Pocock ha señalado que handoff se encuentra entre los Skills que utiliza con mayor frecuencia. Pero eso no significa que sea universalmente necesario: su ámbito de aplicación sigue siendo bastante específico.

Conclusión

handoff merece la pena de forma condicional.

No es una herramienta imprescindible para cualquier usuario de AI Coding ni pretende sustituir Git, Issues, SPEC, ADR o la documentación del proyecto.

Su valor aparece cuando el trabajo deja de pertenecer a una única conversación.

Cuando una tarea debe pasar de Claude Code a Codex, de un Agent a otro, de un directorio a otro, de un desarrollador a otro o de una sesión principal a una tarea paralela, handoff ofrece una forma ligera de transportar el estado actual del trabajo sin convertir el historial completo del chat en una nueva carga de contexto.

El problema detectado en el Issue #186 —la posible pérdida de decisiones, restricciones y detalles implícitos durante el resumen— merece seguirse de cerca. Un handoff incorrecto puede ser incluso peor que no tenerlo, porque transmite al siguiente Agent una sensación falsa de continuidad.

Aun así, para su objetivo concreto, la propuesta es convincente:

handoff no hace que el Agent sea más inteligente. Hace que el trabajo pueda continuar cuando el Agent o la sesión cambian.

Y a medida que AI Coding evoluciona desde el modelo de “un Agent, una sesión” hacia flujos con sesiones largas, múltiples Agents y trabajo paralelo, esa capacidad de transportar el estado de un trabajo se vuelve cada vez más útil.