delegate-skills — Delegar tareas a modelos más baratos

delegate-chore

Línea de escape para tareas secundarias. task_type=chore, modelo predeterminado haiku (el más barato). El despacho a sistemas de ejecución (Codex / Devin / Cursor / Claude) lo realiza dispatch.sh.

Rutas de scripts

• Claude Code: skill_dir=.claude/skills/delegate-chore
• Codex: skill_dir=.agents/skills/delegate-chore

Los siguientes ejemplos de comandos usan .claude/skills/delegate-chore para Claude Code. Si se usa con Codex, reemplazar por la misma estructura relativa .agents/skills/delegate-chore.

Referencia de precios de modelos

Solo cuando sea necesario un análisis de costos o comparación de tarifas, leer <skill_dir>/model-token-prices.json. Estos datos son solo de referencia y no se usan para decidir si se delega o no.

Antes de delegar (puerta de costos)

Delegar conlleva una sobrecarga (inicio del worker, intercambio de solicitud/respuesta, lectura por parte del agente principal). Si esta tarea se puede scriptar con un solo comando (sed / find / chmod etc.) y no es necesario cargar el contenido en el contexto del modelo, delegar suele ser una pérdida neta (la sobrecarga supera los beneficios de higiene del contexto y de tokens). En ese caso, no delegar; que el agente principal lo ejecute directamente o, si se repite, proponerlo en el bucle de retroalimentación para automatización. La delegación vale la pena solo para trabajos voluminosos donde el modelo necesita leer y procesar el contenido. Justificación en docs/design/delegate-chore.md §5.

Flujo de ejecución (one-shot)

1. Creación de solicitud: Pasar por stdin el Markdown con Objetivo / Alcance / Contexto / Criterios de aceptación / Verificación / Restricciones. La solicitud debe ser concisa: en Contexto no pegar el contenido de archivos, sino referenciarlos por ruta (y rango de líneas si es necesario) (para no aumentar la salida del agente principal = tokens facturables).
   • Si el usuario especifica un modelo o esfuerzo en la conversación, anteponer variables de entorno en línea a la llamada run (ejemplo: DELEGATE_CHORE_MODEL=gpt-5.5@high bash .../run.sh ...). En caso de exit 6, usar la línea de stderr que incluye los valores permitidos directamente como explicación al usuario.
2. Ejecución: out="$(printf '%s' "$req_md" | bash .claude/skills/delegate-chore/scripts/run.sh chore DELEGATE_CHORE_MODEL haiku "$PARENT_TASK_TYPE_CHAIN" "$REQUESTER_SESSION_ID")" (si se inicia desde el nivel superior, $PARENT_TASK_TYPE_CHAIN puede estar vacío).
   • run ejecuta internamente prepare → dispatch → read-response en secuencia. stdout devuelve un único JSON (tanto en éxito como en fallo) con exit_code / status / content / content_truncated / response_file / observe_file / run_dir.
   • Si se omite el selector, el valor predeterminado es auto. El sexto argumento posicional es el selector de read-response, que tiene un significado diferente al sexto argumento posicional session_mode de prepare.sh.
   • El código de salida se transmite desde los scripts internos. exit 3 = prerrequisitos insuficientes / exit 4 = ciclo de delegación, abortar.
   • Antes de despachar, run imprime en stderr observe_file: <path>. En caso de terminación forzada, usar esa ruta como vía de recuperación.
   • En modo no interactivo (por ejemplo, claude -p), ejecutar run siempre en primer plano y establecer un timeout de Bash mayor que el tiempo estimado de delegación (en Claude Code, BASH_DEFAULT_TIMEOUT_MS / BASH_MAX_TIMEOUT_MS o el argumento timeout de la herramienta Bash).
3. Consumo de respuesta: Leer status="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .status)" / content="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .content)". Si content_truncated es true, extraer response_file="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .response_file)" y leer por secciones con bash .claude/skills/delegate-chore/scripts/read-response.sh "$response_file" <N>. Después de leer, no resumir ni repetir (echo) el texto del worker. La respuesta al usuario del agente principal debe limitarse a una línea que apunte al Resumen (para no aumentar la salida del agente principal = tokens facturables; spec.md §6).

Flujo avanzado (scripts individuales)

Para flujos que requieren supervisión durante el despacho, ejecución en segundo plano, reanudación o seguimiento, usar los scripts individuales tradicionales.

1. Preparación (agregada): Un único script prepare.sh que realiza verificación de prerrequisitos → resolución de modelo → confirmación de cadena → generación de solicitud (reduciendo los viajes de ida y vuelta de Bash y la salida al contexto principal). Pasar por stdin el Markdown con Objetivo / Alcance / Contexto / Criterios de aceptación / Verificación / Restricciones. La solicitud debe ser concisa: en Contexto no pegar el contenido de archivos, sino referenciarlos por ruta (y rango de líneas si es necesario) (para no aumentar la salida del agente principal = tokens facturables). exit 3 = prerrequisitos insuficientes / exit 4 = ciclo de delegación, abortar.
   • Si el usuario especifica un modelo o esfuerzo en la conversación, anteponer variables de entorno en línea a la llamada prepare (ejemplo: DELEGATE_CHORE_MODEL=gpt-5.5@high bash .../prepare.sh ...). Si prepare sale con exit 6, usar la línea de stderr que incluye los valores permitidos directamente como explicación al usuario.
   • out="$(printf '%s' "$req_md" | bash .claude/skills/delegate-chore/scripts/prepare.sh chore DELEGATE_CHORE_MODEL haiku "$PARENT_TASK_TYPE_CHAIN" "$REQUESTER_SESSION_ID")" (si se inicia desde el nivel superior, $PARENT_TASK_TYPE_CHAIN puede estar vacío)
   • model="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .model)" / request_file="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .request_file)" / response_file="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .response_file)" / run_dir="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .run_dir)" / observe_file="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .observe_file)"
2. Ejecución: bash .claude/skills/delegate-chore/scripts/dispatch.sh "$model" chore "$request_file" "$response_file" "$run_dir" "$observe_file". El despacho a sistemas de ejecución (Codex / Devin / Cursor / Claude) según el prefijo del nombre del modelo lo realiza dispatch.sh. stdout solo contiene la ruta de response_file. En modo no interactivo (por ejemplo, claude -p), ejecutar dispatch siempre en primer plano y establecer un timeout de Bash mayor que el tiempo estimado de delegación (en Claude Code, BASH_DEFAULT_TIMEOUT_MS / BASH_MAX_TIMEOUT_MS o el argumento timeout de la herramienta Bash). Durante la ejecución, la supervisión normal se realiza leyendo desde observe_file solo state.phase / state.started_at / heartbeat.ts / heartbeat.stdout_bytes / heartbeat.stderr_bytes / heartbeat.last_stream_change_at con read-json.sh. state.phase puede ser prepared | running | superseded | stalled | ended. prepared / superseded son observaciones no despachadas (state.started_at == null, usage no establecido, equivalente a null en read-json.sh), por lo que al agregar uso se excluyen del denominador.
3. Lectura de respuesta: bash .claude/skills/delegate-chore/scripts/read-response.sh "$response_file" auto. Con auto, si la respuesta es pequeña (menos de 10KB por defecto), lee el estado y todas las secciones de una vez; si es grande, devuelve estado + índice + sección Resumen, y se pueden obtener secciones adicionales con ... "$response_file" <N>. Después de leer, no resumir ni repetir (echo) el texto del worker. La respuesta al usuario del agente principal debe limitarse a una línea que apunte al Resumen (para no aumentar la salida del agente principal = tokens facturables; spec.md §6).

Reutilización de sesión (reanudable / seguimiento)

Las sesiones reanudables o de seguimiento no son objetivo del flujo one-shot, por lo que se usan scripts individuales.

El valor predeterminado es ejecución normal. Solo cuando sea probable que el agente principal deba revisar y devolver cambios (como correcciones transversales grandes), indicar explícitamente desde el principio una ejecución inicial reanudable. No usar en exceso.

• Ejecución inicial reanudable: Pasar resumable como sexto argumento de prepare.sh. dispatch recibe resumable como séptimo argumento, y cadenas vacías como octavo y noveno.
  • out="$(printf '%s' "$req_md" | bash .claude/skills/delegate-chore/scripts/prepare.sh chore DELEGATE_CHORE_MODEL haiku "$PARENT_TASK_TYPE_CHAIN" "$REQUESTER_SESSION_ID" resumable)"
  • session_mode="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .session_mode)" / lineage_id="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .lineage_id)"
  • bash .claude/skills/delegate-chore/scripts/dispatch.sh "$model" chore "$request_file" "$response_file" "$run_dir" "$observe_file" "$session_mode" "" ""
  • Después de leer la respuesta, verificar bash .claude/skills/delegate-chore/scripts/read-json.sh .backend_session.persistence "$observe_file". Si no es resumable, no se puede hacer seguimiento; decidir en el momento sin esperar una caída implícita posterior.
• Ejecución de seguimiento: Usar solo si el agente principal encuentra problemas al revisar diferencias. Pasar followup=<observe_file_anterior> como sexto argumento de prepare.sh. exit 5 indica fallo de verificación, por lo que se aborta y se vuelve a emitir como delegación normal. No hacer caída implícita.
  • out="$(printf '%s' "$req_md" | bash .claude/skills/delegate-chore/scripts/prepare.sh chore DELEGATE_CHORE_MODEL haiku "$PARENT_TASK_TYPE_CHAIN" "$REQUESTER_SESSION_ID" "followup=$previous_observe_file")"
  • session_mode="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .session_mode)" / resume_id="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .resume_id)" / backend_session_home="$(printf '%s' "$out" | bash .claude/skills/delegate-chore/scripts/read-json.sh .backend_session_home)"
  • bash .claude/skills/delegate-chore/scripts/dispatch.sh "$model" chore "$request_file" "$response_file" "$run_dir" "$observe_file" "$session_mode" "$resume_id" "$backend_session_home"
  • La solicitud de seguimiento debe incluir siempre el problema encontrado por el agente principal, el rango relevante del último git diff y una referencia al response_file anterior. No depender únicamente del contexto de conversación antiguo del worker.

Propuesta de promoción a skill (bucle de retroalimentación)

Las tareas que llegan a delegate-chore son una señal de que no existe un skill dedicado. Después de consumir la respuesta, si la tarea:

• Aparece repetidamente / es una categoría reutilizable claramente delimitada

Entonces proponer al usuario mediante AskUserQuestion la creación de un nuevo skill delegate-<nombre> (incluyendo nombre sugerido / modelo predeterminado / permisos de herramientas / tipo de inicio). Tras el acuerdo, usar skill-creator para generar un esqueleto que siga este protocolo. No proponer para tareas únicas o triviales.

Propuesta de automatización de procesos deterministas

Con el mismo espíritu que la promoción a skill, si se descubre que la misma secuencia de comandos, procedimiento de verificación o edición estandarizada aparece repetidamente y las ramificaciones son fijas sin necesidad de juicio del LLM, proponer mediante AskUserQuestion una automatización adecuada (script, git hook, npm script, CI, etc.), incluyendo el procedimiento objetivo, el destino de automatización y el desencadenante previsto. No proponer para procedimientos únicos o que impliquen toma de decisiones.

Ocultación del tiempo de espera (para padres interactivos)

En modo interactivo, se puede ocultar el tiempo de espera ejecutando dispatch.sh (o run.sh) en segundo plano, verificando state.phase / heartbeat en observe_file y llamando a read-response.sh solo cuando sea ended. Esto mejora la sensación de espera aunque el tiempo total (wall time) no cambie. En modo no interactivo, la ejecución debe ser en primer plano como siempre.

Restricciones

• Se permiten ediciones. Pero no hacer push (el agente principal maneja directamente push y PR).
• No re-delegar a tipos dentro de task_type_chain (sí se puede delegar a otros tipos).
• El agente principal no debe hacer echo ni resumir la salida del worker. La respuesta al usuario debe limitarse a una línea que apunte al Resumen (para no aumentar la salida = tokens facturables; spec.md §6).