agenthub

Descripción general del skill agenthub

Para qué sirve agenthub

agenthub es un skill de Agent Orchestration para ejecutar varios agentes de IA en paralelo sobre una misma tarea dentro de un repositorio. Cada agente trabaja en un git worktree aislado, explora un enfoque distinto, informa su avance mediante un .agenthub/board local y deja una rama que se puede evaluar y fusionar. El objetivo principal no es “pedirle una respuesta a una IA”, sino “probar varias soluciones creíbles, compararlas y quedarse con la mejor”.

Casos de uso donde mejor encaja

El skill agenthub funciona mejor cuando el éxito puede compararse entre intentos: optimización de rendimiento, refactorización de código, variantes de prompts o contenido, exploración de investigación, mejora de pruebas o estrategias de implementación competidoras. Es especialmente útil cuando un agente podría quedarse atrapado en un óptimo local y quieres diversidad sin tener que gestionar manualmente ramas, notas de estado y ranking de resultados.

Diferenciadores clave y restricciones

El diferenciador importante es el aislamiento basado en git: las salidas de los agentes quedan separadas en ramas hub/{session-id}/agent-{N}/attempt-{M} en lugar de mezclarse en un único working tree. AgentHub también incluye referencias de coordinación para patrones fan-out/fan-in, tournament y ensemble, además de scripts para configurar sesiones, gestionar el board, analizar DAG, validar en modo dry-run y ordenar resultados. La restricción principal es que necesitas un repositorio git real; no es una buena opción para respuestas puntuales de chat sin archivos, sin una ruta de evaluación o sin tolerancia para revisar merges.

Cómo usar el skill agenthub

Instalación de agenthub y configuración del repositorio

Instala el skill en tu entorno de Claude skills con:

npx skills add alirezarezvani/claude-skills --skill agenthub

Después úsalo desde el repositorio del proyecto objetivo, no desde una carpeta vacía. Antes de lanzar agentes, asegúrate de que el repo esté limpio o de que sepas intencionalmente qué archivos sin commit deben formar parte de la línea base. Si quieres inspeccionar primero la implementación, empieza por SKILL.md y luego lee:

• references/agent-templates.md para estilos de despacho como optimizer, refactorer, explorer y otros relacionados.
• references/coordination-strategies.md para elegir flujos fan-out, tournament o ensemble.
• references/dag-patterns.md para entender nombres de ramas, detección de frontier y comportamiento de merge.
• scripts/hub_init.py, scripts/board_manager.py, scripts/dag_analyzer.py y scripts/result_ranker.py para detalles operativos.

Comandos y flujo de trabajo

En el uso normal de agenthub, el skill expone slash commands como:

• /hub:init para definir la tarea, el número de agentes, los criterios de evaluación y la sesión.
• /hub:spawn para lanzar subagentes en paralelo dentro de worktrees aislados.
• /hub:status para revisar el progreso y el estado de las ramas.
• /hub:board para leer o escribir notas de despacho, avance y resultados.
• /hub:eval para clasificar salidas por métrica o con un LLM judge.
• /hub:merge para fusionar la rama ganadora y archivar las perdedoras.
• /hub:run para un ciclo de vida de una sola pasada: init, baseline, spawn, evaluate, merge.

Para validación manual, los scripts incluidos muestran la mecánica esperada. Por ejemplo, hub_init.py puede inicializar .agenthub/ con una tarea, número de agentes, comando de evaluación, métrica y dirección; dag_analyzer.py puede mostrar ramas frontier; board_manager.py gestiona publicaciones de progreso y resultados.

Convierte un objetivo impreciso en un prompt sólido

Un prompt débil sería: “Use agenthub to improve this app.” Un prompt más sólido le da al coordinador la información necesaria para despachar y evaluar agentes:

Use agenthub for Agent Orchestration in this git repo.

Task: Reduce API p95 latency for `/search` without changing response schema.
Agents: 4
Template: optimizer
Evaluation command: `pytest tests/test_search.py && python bench/search_latency.py --json`
Metric: `p95_ms`
Direction: lower
Constraints:
- Keep public API compatibility.
- Do not add external services.
- Prefer small commits with clear explanations.
Success bar: at least 15% lower p95 with all tests passing.
After spawning, use the board to track each agent’s strategy and final result, then evaluate and recommend the winning branch before merge.

Esto funciona mejor porque cada agente conoce el objetivo, la puntuación medible, los cambios permitidos y la condición de parada.

Consejos prácticos de calidad

Usa de 2 a 5 agentes en la mayoría de las sesiones; la guía de coordinación del repositorio señala que, por encima de ese rango, los beneficios tienden a disminuir. Siempre que sea posible, prefiere una evaluación basada en métricas, porque reduce la selección subjetiva del ganador. Usa un LLM judge solo para tareas como calidad de documentación, variantes de contenido o síntesis de investigación cuando no exista una métrica confiable por línea de comandos. Para tareas grandes, considera un patrón ensemble solo si las subtareas son realmente independientes; de lo contrario, fan-out/fan-in es más simple y seguro.

Preguntas frecuentes del skill agenthub

¿agenthub es solo para tareas de código?

No. agenthub está centrado en git, pero el trabajo puede ser código, documentación, prompts, notas de investigación, benchmarks o borradores de contenido, siempre que las salidas vivan en un repositorio y puedan compararse. Aporta más valor cuando varios intentos independientes pueden producir resultados significativamente distintos.

¿En qué se diferencia agenthub de un prompt normal?

Un prompt normal pide a una ejecución de modelo que resuelva una tarea. El skill agenthub coordina varios intentos, los aísla en worktrees, registra el progreso mediante un board, analiza el estado de las ramas y evalúa un ganador. Esa estructura importa cuando explorar y comparar es más valioso que obtener una única respuesta directa.

¿Pueden usar el skill agenthub personas principiantes?

Sí, si entienden conceptos básicos de git como ramas, commits y revisión de merges. Quienes empiezan deberían usar /hub:run o una sesión sencilla con /hub:init, 2 agentes y un comando de evaluación claro. Evita comenzar con estrategias tournament o ensemble hasta que te sientas cómodo revisando ramas competidoras.

¿Cuándo no debería usar agenthub?

No uses agenthub cuando la tarea sea muy pequeña, la respuesta deseada sea obvia, el repo no esté bajo git, los criterios de evaluación no estén claros o los conflictos de merge vayan a costar más que el beneficio de la exploración en paralelo. Para ediciones simples, un prompt directo más una revisión normal es más rápido.

Cómo mejorar el skill agenthub

Mejora las entradas de agenthub antes de lanzar agentes

La mejor forma de mejorar los resultados de agenthub es definir la competencia con precisión. Incluye la tarea, los archivos o módulos dentro del alcance, las áreas excluidas, el número de agentes, el template, el comando de evaluación, el nombre de la métrica, la dirección de la métrica, las restricciones de calidad y la política de merge. Si los agentes están optimizando, dales un valor de baseline; si están redactando, dales una rúbrica y ejemplos de salidas aceptables.

Evita modos de fallo comunes

Los problemas frecuentes incluyen agentes que optimizan la métrica equivocada, producen resultados incomparables, sobrescriben supuestos o dejan ramas que pasan un benchmark estrecho pero fallan pruebas más amplias. Evítalo exigiendo que cada agente ejecute el mismo comando de evaluación, publique avances en .agenthub/board/progress, escriba resultados finales en .agenthub/board/results y mantenga commits lo bastante pequeños como para revisarlos. Añade “all tests must pass” como restricción cuando la corrección sea más importante que la puntuación bruta.

Itera después del primer resultado

Después de /hub:eval, no hagas merge a ciegas. Inspecciona el diff ganador, lee las publicaciones de resultados de los agentes perdedores y busca ideas parciales útiles. Si el ganador es bueno pero no concluyente, ejecuta una segunda ronda estilo tournament desde la rama ganadora con restricciones refinadas. Si distintos agentes resolvieron partes independientes diferentes, considera hacer cherry-picking con un enfoque ensemble, pero solo después de revisar conflictos y cobertura de pruebas.

Usa los archivos de soporte como guía operativa

Para un mejor uso a largo plazo, trata los archivos de soporte del repositorio como playbooks. Usa references/coordination-strategies.md para elegir el patrón de orquestación, references/agent-templates.md para ajustar el comportamiento del agente a la tarea, references/dag-patterns.md para entender la lógica de ramas/frontier y scripts/dry_run.py para validar los archivos del skill antes de depender de la automatización. Esto convierte agenthub de una idea llamativa de agentes en paralelo en un flujo de trabajo de repositorio repetible.