agenthub

Overview of agenthub skill

What agenthub is for

agenthub is an Agent Orchestration skill for running several AI agents against the same repository task in parallel. Each agent works in an isolated git worktree, explores a different approach, reports progress through a local .agenthub/board, and leaves a branch that can be evaluated and merged. The main job-to-be-done is not “ask an AI for one answer”; it is “try multiple credible solutions, compare them, and keep the best one.”

Best-fit use cases

The agenthub skill is strongest when success can be compared across attempts: performance optimization, code refactoring, prompt/content variants, research exploration, test improvement, or competing implementation strategies. It is especially useful when one agent might get stuck in a local optimum and you want diversity without manually managing branches, status notes, and result ranking.

Key differentiators and constraints

The important differentiator is git-based isolation: agent outputs are separated by hub/{session-id}/agent-{N}/attempt-{M} branches instead of mixed in one working tree. AgentHub also includes coordination references for fan-out/fan-in, tournament, and ensemble patterns, plus scripts for session setup, board management, DAG analysis, dry-run validation, and result ranking. The main constraint is that you need a real git repository; this is a poor fit for one-off chat answers with no files, no evaluation path, or no tolerance for merge review.

How to Use agenthub skill

agenthub install and repository setup

Install the skill in your Claude skills environment with:

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

Then use it from the target project repository, not from an empty folder. Before spawning agents, make sure the repo is clean or that you intentionally know which uncommitted files should be part of the baseline. If you want to inspect the implementation first, start with SKILL.md, then read:

• references/agent-templates.md for optimizer, refactorer, explorer, and related dispatch styles.
• references/coordination-strategies.md for choosing fan-out, tournament, or ensemble workflows.
• references/dag-patterns.md for branch naming, frontier detection, and merge behavior.
• scripts/hub_init.py, scripts/board_manager.py, scripts/dag_analyzer.py, and scripts/result_ranker.py for operational details.

Commands and workflow

In normal agenthub usage, the skill exposes slash commands such as:

• /hub:init to define the task, agent count, evaluation criteria, and session.
• /hub:spawn to launch parallel subagents in isolated worktrees.
• /hub:status to inspect progress and branch state.
• /hub:board to read or write dispatch, progress, and result notes.
• /hub:eval to rank outputs by metric or LLM judge.
• /hub:merge to merge the winning branch and archive losers.
• /hub:run for a one-shot lifecycle: init, baseline, spawn, evaluate, merge.

For manual validation, the included scripts show the expected mechanics. For example, hub_init.py can initialize .agenthub/ with a task, agent count, evaluation command, metric, and direction; dag_analyzer.py can show frontier branches; board_manager.py manages progress/result posts.

Turn a rough goal into a strong prompt

A weak prompt is: “Use agenthub to improve this app.” A stronger prompt gives the coordinator the information needed to dispatch and judge 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.

This works better because each agent knows the target, measurable score, allowed changes, and stop condition.

Practical quality tips

Use 2–5 agents for most sessions; the repository’s coordination guidance notes diminishing returns beyond that. Prefer metric-based evaluation when possible, because it reduces subjective winner selection. Use an LLM judge only for tasks like documentation quality, content variants, or research synthesis where no reliable command-line metric exists. For large tasks, consider an ensemble pattern only if subtasks are truly independent; otherwise, fan-out/fan-in is simpler and safer.

agenthub skill FAQ

Is agenthub only for coding tasks?

No. agenthub is git-centered, but the work can be code, documentation, prompts, research notes, benchmarks, or content drafts as long as the outputs live in a repository and can be compared. It is most valuable when multiple independent attempts can produce meaningfully different results.

How is agenthub different from a normal prompt?

A normal prompt asks one model run to solve a task. The agenthub skill coordinates multiple attempts, isolates them in worktrees, records progress through a board, analyzes branch state, and evaluates a winner. That structure matters when exploration and comparison are more valuable than a single direct answer.

Can beginners use the agenthub skill?

Yes, if they understand basic git concepts such as branches, commits, and merge review. Beginners should start with /hub:run or a simple /hub:init session using 2 agents and a clear evaluation command. Avoid starting with tournament or ensemble strategies until you are comfortable reviewing competing branches.

When should I not use agenthub?

Do not use agenthub when the task is tiny, the desired answer is obvious, the repo is not under git, the evaluation criteria are unclear, or merge conflicts would be more expensive than the benefit of parallel exploration. For simple edits, a direct prompt plus normal review is faster.

How to Improve agenthub skill

Improve agenthub inputs before spawning

The best way to improve agenthub results is to define the competition precisely. Include the task, files or modules in scope, excluded areas, agent count, template, evaluation command, metric name, metric direction, quality constraints, and merge policy. If agents are optimizing, give them a baseline value; if they are drafting, give them a rubric and examples of acceptable output.

Prevent common failure modes

Common problems include agents optimizing the wrong metric, producing incomparable results, overwriting assumptions, or leaving branches that pass a narrow benchmark but fail broader tests. Prevent this by requiring every agent to run the same eval command, post progress to .agenthub/board/progress, write final results to .agenthub/board/results, and keep commits small enough to review. Add “all tests must pass” as a constraint when correctness matters more than raw score.

Iterate after the first result

After /hub:eval, do not merge blindly. Inspect the winning diff, read losing agents’ result posts, and look for useful partial ideas. If the winner is good but not decisive, run a tournament-style second round from the winning branch with refined constraints. If different agents solved different independent parts, consider cherry-picking with an ensemble approach, but only after checking conflicts and test coverage.

Use the support files as an operating guide

For better long-term use, treat the repository’s support files as playbooks. Use references/coordination-strategies.md to choose the orchestration pattern, references/agent-templates.md to match the agent behavior to the task, references/dag-patterns.md to understand branch/frontier logic, and scripts/dry_run.py to validate the skill files before relying on automation. This turns agenthub from a flashy parallel-agent idea into a repeatable repository workflow.