agenthub

agenthub skill 概覽

agenthub 的用途

agenthub 是一個用於 Agent Orchestration 的 skill，可讓多個 AI agents 針對同一個 repository task 並行作業。每個 agent 都會在隔離的 git worktree 中工作，探索不同解法，透過本機 .agenthub/board 回報進度，並留下可供評估與合併的 branch。它要解決的核心工作不是「問 AI 一個答案」，而是「嘗試多個有可信度的解法、比較結果，並保留最好的那個」。

最適合的使用情境

agenthub skill 最適合用在成功結果可以跨嘗試比較的任務：效能最佳化、程式碼重構、prompt／內容版本比較、研究探索、測試改善，或多種實作策略競爭。當單一 agent 可能卡在局部最佳解，而你又希望取得多樣化解法、但不想手動管理 branches、狀態筆記與結果排序時，它特別有用。

主要差異與限制

agenthub skill 的關鍵差異在於以 git 為基礎的隔離：agent 的輸出會分別放在 hub/{session-id}/agent-{N}/attempt-{M} branches，而不是混在同一個 working tree 裡。AgentHub 也提供 fan-out/fan-in、tournament、ensemble patterns 的協調參考，以及 session setup、board management、DAG analysis、dry-run validation、result ranking 等 scripts。主要限制是你需要一個真正的 git repository；如果只是一次性的聊天回答，沒有檔案、沒有評估路徑，或無法接受 merge review，那就不適合使用。

如何使用 agenthub skill

agenthub 安裝與 repository 設定

在你的 Claude skills 環境中使用以下指令安裝此 skill：

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

接著請從目標 project repository 中使用它，而不是在空資料夾中執行。產生 agents 之前，請先確認 repo 是乾淨的，或你很清楚哪些尚未 commit 的檔案應該納入 baseline。若想先檢視實作內容，請從 SKILL.md 開始，接著閱讀：

• references/agent-templates.md：了解 optimizer、refactorer、explorer，以及相關 dispatch styles。
• references/coordination-strategies.md：用來選擇 fan-out、tournament 或 ensemble workflows。
• references/dag-patterns.md：了解 branch naming、frontier detection 與 merge behavior。
• scripts/hub_init.py、scripts/board_manager.py、scripts/dag_analyzer.py、scripts/result_ranker.py：查看實際操作細節。

指令與工作流程

在一般的 agenthub 使用情境中，此 skill 會提供以下 slash commands：

• /hub:init：定義 task、agent count、evaluation criteria 與 session。
• /hub:spawn：在隔離的 worktrees 中啟動 parallel subagents。
• /hub:status：檢查進度與 branch state。
• /hub:board：讀寫 dispatch、progress 與 result notes。
• /hub:eval：依 metric 或 LLM judge 排名輸出結果。
• /hub:merge：合併勝出的 branch，並封存未勝出的 branches。
• /hub:run：執行一次性的完整生命週期：init、baseline、spawn、evaluate、merge。

若要手動驗證，隨附 scripts 會展示預期的運作方式。例如，hub_init.py 可用 task、agent count、evaluation command、metric 與 direction 初始化 .agenthub/；dag_analyzer.py 可顯示 frontier branches；board_manager.py 則管理 progress/result posts。

把粗略目標轉成有效 prompt

較弱的 prompt 是：「Use agenthub to improve this app.」更好的 prompt 會提供 coordinator 派工與評估 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.

這樣效果更好，因為每個 agent 都知道目標、可量化的分數、允許的變更範圍，以及停止條件。

實用的品質建議

多數 sessions 使用 2–5 個 agents 即可；repository 的 coordination guidance 也提到，超過這個數量後通常會出現邊際效益遞減。能用 metric-based evaluation 時就優先使用，因為它能降低主觀選擇勝出者的風險。只有在文件品質、內容版本或研究彙整這類沒有可靠 command-line metric 的任務中，才建議使用 LLM judge。大型任務若要採用 ensemble pattern，前提是 subtasks 真正彼此獨立；否則 fan-out/fan-in 通常更簡單也更安全。

agenthub skill 常見問題

agenthub 只適合 coding tasks 嗎？

不是。agenthub 以 git 為中心，但工作內容可以是 code、documentation、prompts、research notes、benchmarks 或 content drafts；只要輸出存在於 repository 中，而且能夠比較即可。當多個獨立嘗試能產生有意義差異的結果時，它最有價值。

agenthub 和一般 prompt 有什麼不同？

一般 prompt 是請一次 model run 解決一個任務。agenthub skill 則會協調多次嘗試，將它們隔離在 worktrees 中，透過 board 記錄進度，分析 branch state，並評估勝出者。當探索與比較比單一直接答案更重要時，這種結構就很關鍵。

初學者可以使用 agenthub skill 嗎？

可以，只要理解 branches、commits、merge review 等基本 git 概念即可。初學者建議從 /hub:run 開始，或用 2 個 agents 與清楚的 evaluation command 建立簡單的 /hub:init session。在還不熟悉如何審查 competing branches 前，先不要從 tournament 或 ensemble strategies 開始。

什麼時候不該使用 agenthub？

當任務很小、想要的答案很明顯、repo 沒有使用 git、evaluation criteria 不清楚，或 merge conflicts 的成本高於 parallel exploration 的收益時，就不該使用 agenthub。對簡單修改來說，直接 prompt 加上一般 review 會更快。

如何改善 agenthub skill 的成效

產生 agents 前先改善 agenthub 輸入

改善 agenthub results 的最佳方式，是把競爭條件定義清楚。請包含 task、納入範圍的 files 或 modules、排除範圍、agent count、template、evaluation command、metric name、metric direction、quality constraints 與 merge policy。如果 agents 要做最佳化，請提供 baseline value；如果 agents 要撰寫草稿，請提供 rubric 以及可接受輸出的 examples。

避免常見失敗模式

常見問題包括 agents 最佳化錯誤 metric、產出無法互相比較的結果、覆寫彼此假設，或留下只通過狹窄 benchmark、卻無法通過更廣泛 tests 的 branches。要避免這些問題，請要求每個 agent 執行相同的 eval command、將進度發佈到 .agenthub/board/progress、將最終結果寫到 .agenthub/board/results，並讓 commits 小到足以 review。當 correctness 比 raw score 更重要時，請把「all tests must pass」加入 constraints。

第一次結果後繼續迭代

執行 /hub:eval 後，不要盲目 merge。請檢查勝出者的 diff，閱讀未勝出 agents 的 result posts，並尋找有用的局部想法。如果勝出結果不錯但還不夠明確，可從 winning branch 出發，用更精準的 constraints 執行 tournament-style 的第二輪。如果不同 agents 解決了不同且彼此獨立的部分，可以考慮用 ensemble approach 進行 cherry-picking，但務必先檢查 conflicts 與 test coverage。

把支援檔案當作操作手冊

若要讓 agenthub skill 長期穩定發揮，請把 repository 的 support files 當作 playbooks 使用。用 references/coordination-strategies.md 選擇 orchestration pattern，用 references/agent-templates.md 將 agent behavior 對應到 task，用 references/dag-patterns.md 理解 branch/frontier logic，並用 scripts/dry_run.py 在依賴 automation 前驗證 skill files。這會讓 agenthub 從一個吸睛的 parallel-agent 概念，變成可重複執行的 repository workflow。