agenthub

Présentation du skill agenthub

À quoi sert agenthub

agenthub est un skill d’Agent Orchestration conçu pour faire travailler plusieurs agents IA en parallèle sur une même tâche de dépôt. Chaque agent évolue dans un git worktree isolé, explore une approche différente, signale son avancement via un .agenthub/board local et laisse une branche qui pourra être évaluée puis fusionnée. L’objectif principal n’est pas de « demander une réponse à une IA », mais de « tester plusieurs solutions crédibles, les comparer et conserver la meilleure ».

Cas d’usage les plus adaptés

Le skill agenthub est particulièrement pertinent lorsque la réussite peut être comparée entre plusieurs tentatives : optimisation des performances, refactorisation de code, variantes de prompts ou de contenus, exploration de pistes de recherche, amélioration de tests ou stratégies d’implémentation concurrentes. Il est surtout utile lorsqu’un agent risque de rester bloqué dans un optimum local et que vous voulez obtenir de la diversité sans gérer manuellement les branches, les notes de statut et le classement des résultats.

Différenciateurs clés et contraintes

Le différenciateur essentiel est l’isolation fondée sur git : les sorties des agents sont séparées dans des branches hub/{session-id}/agent-{N}/attempt-{M} au lieu d’être mélangées dans un seul working tree. AgentHub fournit aussi des références de coordination pour les modèles fan-out/fan-in, tournoi et ensemble, ainsi que des scripts pour l’initialisation de session, la gestion du board, l’analyse de DAG, la validation en dry-run et le classement des résultats. La principale contrainte est qu’il faut un véritable dépôt git ; c’est un mauvais choix pour des réponses ponctuelles en chat sans fichiers, sans chemin d’évaluation ou sans possibilité de relire une fusion.

Comment utiliser le skill agenthub

Installation d’agenthub et préparation du dépôt

Installez le skill dans votre environnement Claude skills avec :

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

Utilisez-le ensuite depuis le dépôt du projet cible, pas depuis un dossier vide. Avant de lancer des agents, assurez-vous que le dépôt est propre, ou que vous savez précisément quels fichiers non commités doivent faire partie de la base de départ. Si vous voulez d’abord inspecter l’implémentation, commencez par SKILL.md, puis lisez :

• references/agent-templates.md pour les styles de dispatch optimizer, refactorer, explorer et apparentés.
• references/coordination-strategies.md pour choisir entre les workflows fan-out, tournoi ou ensemble.
• references/dag-patterns.md pour le nommage des branches, la détection de frontier et le comportement de merge.
• scripts/hub_init.py, scripts/board_manager.py, scripts/dag_analyzer.py et scripts/result_ranker.py pour les détails opérationnels.

Commandes et workflow agenthub

Dans un usage normal d’agenthub, le skill expose des slash commands comme :

• /hub:init pour définir la tâche, le nombre d’agents, les critères d’évaluation et la session.
• /hub:spawn pour lancer des sous-agents en parallèle dans des worktrees isolés.
• /hub:status pour consulter l’avancement et l’état des branches.
• /hub:board pour lire ou écrire les notes de dispatch, de progression et de résultat.
• /hub:eval pour classer les sorties selon une métrique ou un juge LLM.
• /hub:merge pour fusionner la branche gagnante et archiver les perdantes.
• /hub:run pour un cycle complet en une seule fois : init, baseline, spawn, evaluate, merge.

Pour une validation manuelle, les scripts inclus montrent la mécanique attendue. Par exemple, hub_init.py peut initialiser .agenthub/ avec une tâche, un nombre d’agents, une commande d’évaluation, une métrique et une direction ; dag_analyzer.py peut afficher les branches frontier ; board_manager.py gère les publications de progression et de résultats.

Transformer un objectif vague en prompt solide

Un prompt faible serait : « Use agenthub to improve this app. » Un meilleur prompt donne au coordinateur les informations nécessaires pour répartir le travail et juger les agents :

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.

Ce format fonctionne mieux parce que chaque agent connaît la cible, le score mesurable, les changements autorisés et la condition d’arrêt.

Conseils pratiques pour la qualité

Pour la plupart des sessions, utilisez 2 à 5 agents ; les recommandations de coordination du dépôt signalent des rendements décroissants au-delà. Privilégiez une évaluation fondée sur des métriques lorsque c’est possible, car elle limite la part de subjectivité dans le choix du gagnant. N’utilisez un juge LLM que pour les tâches comme la qualité documentaire, les variantes de contenu ou la synthèse de recherche, lorsqu’aucune métrique fiable en ligne de commande n’existe. Pour les tâches volumineuses, envisagez un modèle ensemble uniquement si les sous-tâches sont réellement indépendantes ; sinon, le fan-out/fan-in est plus simple et plus sûr.

FAQ du skill agenthub

agenthub est-il réservé aux tâches de code ?

Non. agenthub est centré sur git, mais le travail peut porter sur du code, de la documentation, des prompts, des notes de recherche, des benchmarks ou des brouillons de contenu, tant que les sorties vivent dans un dépôt et peuvent être comparées. Il apporte le plus de valeur lorsque plusieurs tentatives indépendantes peuvent produire des résultats réellement différents.

En quoi agenthub diffère-t-il d’un prompt classique ?

Un prompt classique demande à une exécution de modèle de résoudre une tâche. Le skill agenthub coordonne plusieurs tentatives, les isole dans des worktrees, enregistre l’avancement via un board, analyse l’état des branches et évalue un gagnant. Cette structure compte lorsque l’exploration et la comparaison valent davantage qu’une réponse unique et directe.

Les débutants peuvent-ils utiliser le skill agenthub ?

Oui, s’ils comprennent les notions git de base comme les branches, les commits et la revue de merge. Les débutants devraient commencer par /hub:run ou par une session /hub:init simple avec 2 agents et une commande d’évaluation claire. Évitez de démarrer avec des stratégies de tournoi ou d’ensemble tant que vous n’êtes pas à l’aise avec la revue de branches concurrentes.

Quand ne faut-il pas utiliser agenthub ?

N’utilisez pas agenthub lorsque la tâche est minuscule, que la réponse attendue est évidente, que le dépôt n’est pas sous git, que les critères d’évaluation sont flous ou que les conflits de merge coûteraient plus cher que le bénéfice de l’exploration parallèle. Pour des modifications simples, un prompt direct suivi d’une revue classique sera plus rapide.

Comment améliorer le skill agenthub

Améliorer les entrées agenthub avant de lancer les agents

La meilleure façon d’améliorer les résultats d’agenthub est de définir précisément la compétition. Indiquez la tâche, les fichiers ou modules dans le périmètre, les zones exclues, le nombre d’agents, le template, la commande d’évaluation, le nom de la métrique, le sens de la métrique, les contraintes de qualité et la politique de merge. Si les agents optimisent quelque chose, donnez-leur une valeur de référence ; s’ils rédigent, fournissez une grille d’évaluation et des exemples de sortie acceptable.

Éviter les modes d’échec courants

Les problèmes fréquents incluent des agents qui optimisent la mauvaise métrique, produisent des résultats incomparables, écrasent des hypothèses ou laissent des branches qui passent un benchmark étroit mais échouent sur des tests plus larges. Pour les éviter, imposez à chaque agent d’exécuter la même commande d’évaluation, de publier sa progression dans .agenthub/board/progress, d’écrire ses résultats finaux dans .agenthub/board/results et de garder des commits assez petits pour être relus. Ajoutez la contrainte « tous les tests doivent passer » lorsque la correction compte plus que le score brut.

Itérer après le premier résultat

Après /hub:eval, ne fusionnez pas aveuglément. Inspectez le diff gagnant, lisez les publications de résultats des agents perdants et recherchez les idées partielles réutilisables. Si le gagnant est bon sans être décisif, lancez un second tour de type tournoi depuis la branche gagnante avec des contraintes affinées. Si plusieurs agents ont résolu des parties indépendantes différentes, envisagez du cherry-picking avec une approche ensemble, mais seulement après avoir vérifié les conflits et la couverture de tests.

Utiliser les fichiers de support comme guide opérationnel

Pour un usage durable, traitez les fichiers de support du dépôt comme des playbooks. Utilisez references/coordination-strategies.md pour choisir le modèle d’orchestration, references/agent-templates.md pour aligner le comportement des agents avec la tâche, references/dag-patterns.md pour comprendre la logique de branches et de frontier, et scripts/dry_run.py pour valider les fichiers du skill avant de dépendre de l’automatisation. agenthub passe ainsi d’une idée séduisante d’agents parallèles à un workflow de dépôt répétable.