long-task-coordinator

Visión general de la skill long-task-coordinator

Qué hace long-task-coordinator

long-task-coordinator es una skill de coordinación para trabajos que deben sobrevivir a interrupciones, relevos entre agentes y pausas largas entre turnos. Su función principal es sencilla: sacar el trabajo de larga duración de la memoria frágil del chat y llevarlo a un archivo de estado persistente, con transiciones de estado explícitas, comprobaciones de recuperación y seguimiento de los siguientes pasos.

Quién debería instalarla

Esta skill encaja especialmente bien para quienes hacen orquestación de agentes, investigación delegada, migraciones, trabajos por lotes o cualquier tarea que pueda pausarse, retomarse más tarde o quedar a la espera de otro worker. Si en tu flujo de trabajo aparecen situaciones como “retómalo mañana” o “lánzalo y vuelve a comprobarlo después”, la skill long-task-coordinator es una opción muy adecuada.

La necesidad real que resuelve

Los usuarios no instalan long-task-coordinator solo para “planificar mejor”. La instalan para que el trabajo largo sea recuperable y honesto:

• recuperar el estado tras perder contexto
• seguir la responsabilidad entre coordinador y workers
• representar de forma explícita los estados de espera
• evitar declarar finalizaciones que no son reales
• reanudar desde una fuente de verdad guardada en lugar de adivinar a partir del chat anterior

En qué se diferencia de un prompt de planificación normal

La diferencia no está en la experiencia de dominio, sino en la disciplina de flujo de trabajo:

• un único archivo de estado persistente
• un ciclo fijo: READ -> RECOVER -> DECIDE -> PERSIST -> REPORT -> END
• estados explícitos como running, awaiting-result, paused, blocked y complete
• preferencia por persistir antes de informar, para que la siguiente sesión pueda recuperarse con fiabilidad

Casos ideales y casos en los que no encaja

Usa long-task-coordinator cuando la tarea abarque varias sesiones, implique subagentes o trabajos en segundo plano, o necesite puntos de control y reintentos. Evítala para una tarea pequeña de un solo turno. El repositorio dirige explícitamente los casos de planificación más ligeros hacia planning-with-files, en lugar de añadir la sobrecarga de un flujo largo cuando no hace falta capacidad de recuperación.

Cómo usar la skill long-task-coordinator

Opciones de instalación de long-task-coordinator

El README del repositorio muestra una instalación manual enlazando la skill al directorio de skills de tu cliente, por ejemplo:

ln -s /path/to/agent-playbook/skills/long-task-coordinator ~/.claude/skills/long-task-coordinator
ln -s /path/to/agent-playbook/skills/long-task-coordinator ~/.codex/skills/long-task-coordinator
ln -s /path/to/agent-playbook/skills/long-task-coordinator ~/.gemini/skills/long-task-coordinator

Si usas un gestor de skills, asegúrate de que la ruta final instalada siga exponiendo el contenido real de la carpeta skills/long-task-coordinator, y no solo la raíz del repositorio.

Lee primero estos archivos

Para una adopción rápida pero fiable, léelos en este orden:

1. skills/long-task-coordinator/SKILL.md
2. skills/long-task-coordinator/references/workflow.md
3. skills/long-task-coordinator/evals/prompts.md
4. skills/long-task-coordinator/README.md

Por qué este orden funciona:

• SKILL.md define las condiciones de activación y las reglas principales
• references/workflow.md aporta el patrón de archivo de estado que realmente usarás
• evals/prompts.md muestra cómo se ve un “comportamiento correcto”
• README.md confirma la instalación y el ciclo principal

Qué entrada necesita la skill

La skill long-task-coordinator funciona mejor cuando proporcionas:

• el objetivo de la tarea
• criterios de éxito concretos
• si el trabajo ya está en marcha
• dónde debe vivir el archivo de estado persistente
• cualquier asignación activa a workers o subagentes
• el siguiente disparador de checkpoint, ya sea por tiempo o condición
• bloqueos o dependencias ya conocidos

Sin esta información, el modelo aún puede empezar, pero hará más suposiciones y generará un registro de coordinación más débil.

Convierte una petición imprecisa en una buena invocación

Petición débil:

Help me keep track of this migration.

Mejor petición:

Use long-task-coordinator for this migration. Create or recover a durable state file at docs/migration-state.md. Goal: migrate service auth to OAuth2. Success criteria: tests pass, rollout notes written, old auth path disabled. We may hand work to subagents and resume across sessions. If any work is in flight, use an explicit waiting state instead of implying failure.

La versión más sólida mejora el resultado porque define desde el principio la persistencia, el alcance, la lógica de finalización y el estilo de coordinación.

Crea pronto un archivo de estado persistente

El hábito operativo más importante es crear el archivo de estado antes de que el trabajo se complique. La referencia recomienda rutas como:

• docs/<topic>-execution-plan.md
• docs/<topic>-state.md
• worklog/<topic>-state.md

Como mínimo, guarda:

• Goal
• Success criteria
• Status
• Current step
• Completed work
• Next action
• Next checkpoint
• Blockers
• Owners

Este es el punto clave de adopción: si omites el archivo de estado, pierdes gran parte del valor de la skill long-task-coordinator.

Usa el ciclo de recuperación en cada turno

El ciclo principal del repositorio es el corazón práctico del uso de long-task-coordinator:

READ -> RECOVER -> DECIDE -> PERSIST -> REPORT -> END

En la práctica, esto significa:

1. leer primero el estado guardado
2. verificar si el estado sigue siendo correcto
3. comprobar si volvió algún trabajo delegado
4. decidir si continuar, esperar, reintentar, pausar o cerrar
5. escribir el estado actualizado
6. solo entonces informar al usuario

Este orden es lo que hace que la siguiente sesión sea recuperable.

Usa estados explícitos, especialmente awaiting-result

Una función sutil pero muy valiosa de esta skill es el uso de awaiting-result. Muchos agentes simulan progreso actuando como si una tarea despachada hubiera fallado o terminado cuando en realidad sigue en curso. Esta skill ofrece un modelo más limpio:

• running para trabajo activo del coordinador
• awaiting-result cuando un worker o un job sigue ejecutándose
• paused cuando se ha detenido de forma intencionada
• blocked cuando restricciones externas impiden avanzar
• complete solo cuando los criterios de éxito realmente se han cumplido

Para Agent Orchestration, esta es una de las distinciones más útiles de toda la skill.

Flujo de trabajo recomendado para trabajo delegado

Un buen patrón operativo es:

1. definir la tarea y los criterios de éxito
2. crear el archivo de estado
3. asignar trabajo acotado a un worker
4. registrar el owner y la condición esperada de retorno
5. establecer el estado en awaiting-result si toca esperar
6. reanudar desde la recuperación, no desde la memoria
7. actualizar lo completado y la siguiente acción
8. marcar complete solo después de comprobar los criterios

Este patrón es más seguro que los prompts abiertos de “sigue adelante”, porque los relevos quedan auditables.

Patrones de prompt prácticos que funcionan bien

Los buenos prompts de uso de long-task-coordinator suelen incluir lenguaje de recuperación. Ejemplos:

• “Use long-task-coordinator and recover from any existing state before proposing next steps.”
• “Persist the updated status before reporting.”
• “If a worker is still in flight, mark awaiting-result and define the next checkpoint.”
• “Do not mark complete unless the saved state and success criteria agree.”

Estos patrones se alinean directamente con los prompts de evaluación del repositorio y reducen la falsa sensación de certeza.

Errores habituales al adoptarla

La mayoría de los usos fallidos vienen de huecos en el proceso, no de funciones ausentes:

• depender del historial del chat en lugar de un archivo
• usar textos de estado vagos en vez de los estados definidos
• informar del progreso antes de actualizar el estado guardado
• no registrar owners para el trabajo delegado
• marcar como completado sin revisar los criterios de aceptación
• usar la skill para tareas cortas en las que la sobrecarga de coordinación no compensa

Preguntas frecuentes sobre la skill long-task-coordinator

¿Merece la pena instalar long-task-coordinator para tareas simples?

Normalmente no. Si la tarea es corta, de una sola sesión y no requiere recuperación, long-task-coordinator añade sobrecarga. El repositorio la posiciona explícitamente para trabajos que sobreviven a un turno o dependen de estado persistente.

¿En qué se diferencia de planning-with-files?

planning-with-files es la opción más ligera cuando lo que necesitas principalmente es planificación estructurada. long-task-coordinator está pensada para reanudación, estados de espera explícitos y recuperación tras interrupciones. Elige esta cuando la integridad del estado importe más que la simple organización de pasos.

¿Es buena long-task-coordinator para Agent Orchestration?

Sí. Es uno de los encajes más claros. La skill está diseñada para configuraciones coordinador-worker, ejecución delegada, trabajos en segundo plano y relevos entre varias sesiones. Su seguimiento de owners y el estado awaiting-result resultan especialmente útiles para Agent Orchestration.

¿Requiere un runtime o framework concreto?

No. El README la describe como intencionadamente abstracta y portable. No asume un dominio ni un runtime determinados. El requisito principal es que tu agente pueda leer y escribir un archivo persistente dentro del workspace.

¿Los principiantes pueden usar esta skill long-task-coordinator?

Sí, si ya entienden la tarea que están coordinando. La skill en sí es conceptualmente sencilla, pero los principiantes pueden aplicarla en exceso. Si no estás lidiando con interrupciones, delegación o necesidad de reanudar, es mejor empezar con una skill de planificación más simple.

¿Cuándo no debería usar long-task-coordinator?

Evítala cuando:

• la tarea vaya a terminarse de una sola vez
• no haya necesidad de retomarla más adelante
• no intervenga ningún worker delegado ni proceso en segundo plano
• no quieras añadir el paso extra de mantener un archivo de estado

En esos casos, los prompts normales pueden ser más rápidos.

Cómo mejorar la skill long-task-coordinator

Empieza con criterios de éxito más sólidos

La palanca de calidad más importante es afinar la lógica de finalización. En lugar de “finish the migration”, escribe criterios como:

• auth tests pass
• production config updated
• rollback note added
• legacy path disabled

Unos criterios mejores hacen mucho más difícil que el modelo cierre la tarea antes de tiempo.

Haz que el archivo de estado sea concreto y fácil de reencontrar

No escondas el estado en un archivo temporal arbitrario. Ponlo en una ruta predecible como docs/oauth-migration-state.md. Una buena recuperación depende de que la siguiente sesión encuentre realmente el archivo sin tener que adivinar.

Registra la responsabilidad de forma explícita

Para un mejor uso de long-task-coordinator, registra siempre quién se encarga de qué:

• Origin: define la tarea
• Coordinator: mantiene el estado y la secuencia
• Worker: ejecuta trabajo acotado

Este pequeño hábito reduce duplicaciones, bloqueos y confusión cuando participan varios agentes.

Mejora los prompts con condiciones de checkpoint

Un checkpoint débil dice: “check back later.” Uno fuerte dice: “resume when the worker returns test results or at 15:00 UTC, whichever comes first.” Cuanto más explícito sea el disparador, menos probable será que el coordinador se desvíe.

Evita informes de progreso engañosos

Un modo de fallo habitual es producir informes fluidos en apariencia, pero poco fiables. Corrígelo indicando a la skill que:

• lea primero el estado guardado
• verifique si sigue siendo exacto
• persista las actualizaciones antes de resumir
• distinga entre espera y bloqueo
• justifique complete frente a los criterios de éxito

Esto mantiene las salidas de long-task-coordinator fiables entre sesiones.

Usa los prompts de evaluación como pruebas de aceptación

evals/prompts.md sirve para algo más que una simple comprobación básica. Trátalo como una checklist local para tus propias adaptaciones:

• ¿puede reanudar trabajo interrumpido de forma segura?
• ¿representa la espera con honestidad?
• ¿demuestra la finalización con estado guardado?

Si tu uso personalizado no supera esas pruebas, tu patrón de orquestación sigue siendo demasiado laxo.

Itera después de la primera ejecución

Después de la primera ronda de coordinación, revisa el archivo de estado y endurece cualquier elemento ambiguo:

• sustituye estados vagos
• añade owners que falten
• aclara bloqueos
• divide siguientes acciones demasiado grandes
• añade una condición de checkpoint real

La skill long-task-coordinator mejora rápido cuando el estado persistido se vuelve más específico, porque toda recuperación futura depende de ese archivo y no de la memoria.