agenthub

agenthub skill の概要

agenthub は何に使うものか

agenthub は、同じリポジトリ上のタスクに対して複数の AI エージェントを並列に走らせるための Agent Orchestration skill です。各エージェントは分離された git worktree で作業し、それぞれ異なるアプローチを試し、ローカルの .agenthub/board に進捗を報告し、評価・マージできるブランチを残します。主な用途は「AI に 1 つの答えを聞く」ことではありません。「有望な解決策を複数試し、比較し、最も良いものを残す」ための仕組みです。

向いているユースケース

agenthub skill が特に力を発揮するのは、複数の試行結果を比較して成否を判断できるタスクです。たとえば、パフォーマンス最適化、コードリファクタリング、プロンプトやコンテンツ案の比較、調査探索、テスト改善、実装方針の競合案検証などが該当します。1 つのエージェントが局所最適に陥る可能性があり、かつブランチ管理、進捗メモ、結果の順位付けを手作業で行いたくない場合に特に便利です。

主な差別化ポイントと制約

重要な差別化ポイントは、git ベースで作業を分離できることです。エージェントの成果物は 1 つの working tree に混在せず、hub/{session-id}/agent-{N}/attempt-{M} のようなブランチに分かれます。AgentHub には、fan-out/fan-in、tournament、ensemble といった調整パターンのリファレンスに加え、セッション作成、board 管理、DAG 分析、dry-run 検証、結果ランキングのためのスクリプトも含まれています。主な制約は、実際の git リポジトリが必要なことです。ファイルがない単発チャット回答、評価方法がないタスク、マージレビューを行う余地がない作業には向いていません。

agenthub skill の使い方

agenthub のインストールとリポジトリ準備

Claude skills 環境にこの skill をインストールするには、次を実行します。

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

その後は、空のフォルダではなく対象プロジェクトのリポジトリ内で使います。エージェントを起動する前に、リポジトリが clean な状態であること、または未コミットのどのファイルを baseline に含めるのかを意図的に把握していることを確認してください。実装内容を先に確認したい場合は、まず SKILL.md を読み、続いて次のファイルを確認します。

• references/agent-templates.md: optimizer、refactorer、explorer などの dispatch スタイル。
• references/coordination-strategies.md: fan-out、tournament、ensemble のどのワークフローを選ぶか。
• references/dag-patterns.md: ブランチ命名、frontier 検出、マージ動作。
• scripts/hub_init.py、scripts/board_manager.py、scripts/dag_analyzer.py、scripts/result_ranker.py: 実運用上の詳細。

コマンドとワークフロー

通常の agenthub 利用では、次のような slash commands が提供されます。

• /hub:init: タスク、エージェント数、評価基準、セッションを定義します。
• /hub:spawn: 分離された worktree で並列 subagents を起動します。
• /hub:status: 進捗とブランチ状態を確認します。
• /hub:board: dispatch、進捗、結果メモを読み書きします。
• /hub:eval: メトリクスまたは LLM judge によって成果物を順位付けします。
• /hub:merge: 勝者ブランチをマージし、敗者ブランチをアーカイブします。
• /hub:run: init、baseline、spawn、evaluate、merge までを一度に実行するライフサイクルです。

手動で検証したい場合は、同梱スクリプトを見ると期待される動作の流れが分かります。たとえば、hub_init.py はタスク、エージェント数、評価コマンド、メトリクス、方向を指定して .agenthub/ を初期化できます。dag_analyzer.py は frontier branches を表示でき、board_manager.py は進捗や結果の投稿を管理します。

ざっくりした目標を強いプロンプトに変える

弱いプロンプトの例は「Use agenthub to improve this app.」です。より良いプロンプトでは、coordinator がエージェントを割り振り、結果を判定するために必要な情報を渡します。

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.

この形のほうがうまく機能します。各エージェントが、目標、測定可能なスコア、許可される変更、停止条件を理解できるためです。

実用上の品質を上げるコツ

多くのセッションでは 2〜5 個のエージェントを使うのが現実的です。リポジトリ内の coordination guidance でも、それ以上は効果が逓減しやすいとされています。可能な場合は、主観的な勝者選定を減らせるため、メトリクスベースの評価を優先してください。ドキュメント品質、コンテンツ案、調査の統合など、信頼できる command-line metric がないタスクでのみ LLM judge を使うのが適しています。大きなタスクで ensemble pattern を検討する場合は、サブタスクが本当に独立しているときに限るべきです。そうでない場合は、fan-out/fan-in のほうがシンプルで安全です。

agenthub skill FAQ

agenthub はコーディング専用ですか？

いいえ。agenthub は git 中心の仕組みですが、成果物がリポジトリにあり、比較できるなら、対象はコード、ドキュメント、プロンプト、調査メモ、ベンチマーク、コンテンツ下書きでも構いません。複数の独立した試行が、意味のある差を持つ結果を生み出せるときに最も価値があります。

agenthub は通常のプロンプトと何が違いますか？

通常のプロンプトは、1 回のモデル実行にタスクを解かせます。agenthub skill は複数の試行を調整し、worktree に分離し、board に進捗を記録し、ブランチ状態を分析し、勝者を評価します。単一の直接回答よりも、探索と比較に価値がある場面では、この構造が効いてきます。

初心者でも agenthub skill を使えますか？

はい。branches、commits、merge review といった基本的な git の概念を理解していれば使えます。初心者は、まず /hub:run か、2 エージェントで明確な evaluation command を指定したシンプルな /hub:init セッションから始めるのがよいでしょう。競合ブランチのレビューに慣れるまでは、tournament や ensemble の戦略から始めるのは避けてください。

agenthub を使わないほうがよい場面は？

タスクが非常に小さい、望ましい答えが明らか、リポジトリが git 管理されていない、評価基準が曖昧、または並列探索の利益よりマージコンフリクト対応のコストが大きい場合は、agenthub を使わないほうがよいです。単純な編集であれば、通常のプロンプトと通常のレビューのほうが速く進みます。

agenthub skill を改善する方法

agenthub の入力を起動前に改善する

agenthub の結果を良くする最も効果的な方法は、競争条件を正確に定義することです。タスク、対象となるファイルやモジュール、除外範囲、エージェント数、template、evaluation command、metric name、metric direction、品質上の制約、merge policy を含めてください。エージェントが最適化を行うなら baseline value を渡し、下書きを作るなら rubric と許容できる出力例を渡します。

よくある失敗パターンを防ぐ

よくある問題には、エージェントが誤ったメトリクスを最適化する、結果同士を比較できなくなる、前提を上書きしてしまう、狭い benchmark は通るが広いテストでは失敗するブランチを残す、といったものがあります。これを防ぐには、すべてのエージェントに同じ eval command の実行を求め、.agenthub/board/progress に進捗を投稿させ、.agenthub/board/results に最終結果を書かせ、レビューしやすい小さなコミットを維持させます。正しさが生スコアより重要な場合は、「all tests must pass」を制約として追加してください。

最初の結果のあとに反復する

/hub:eval の後に、何も確認せずマージしてはいけません。勝者の diff を確認し、敗者エージェントの result posts を読み、有用な部分的アイデアがないか探します。勝者は良いが決定打に欠ける場合は、勝者ブランチを起点に、制約を洗練した tournament-style の第 2 ラウンドを実行します。別々のエージェントが独立した部分をそれぞれ解決している場合は、ensemble approach として cherry-pick を検討できますが、コンフリクトとテストカバレッジを確認してからにしてください。

サポートファイルを運用ガイドとして使う

長期的にうまく使うには、リポジトリ内のサポートファイルを playbook として扱います。references/coordination-strategies.md で orchestration pattern を選び、references/agent-templates.md でタスクに合う agent behavior を確認し、references/dag-patterns.md で branch/frontier logic を理解し、scripts/dry_run.py で自動化に頼る前に skill files を検証します。これにより agenthub は、見栄えのする並列エージェントのアイデアではなく、再現可能なリポジトリ運用ワークフローになります。