agenthub

agenthub skill 概览

agenthub 适合用来做什么

agenthub 是一个用于 Agent Orchestration 的 skill，适合让多个 AI agent 围绕同一个代码仓库任务并行工作。每个 agent 都在隔离的 git worktree 中执行，探索不同方案，通过本地 .agenthub/board 汇报进展，并最终留下一个可评估、可合并的分支。agenthub skill 的核心价值不是“向 AI 要一个答案”，而是“让多个可信方案同时推进，比较结果，然后保留最好的那个”。

最适合的使用场景

agenthub skill 在“不同尝试之间可以被清晰比较”的任务上最有优势，例如性能优化、代码重构、prompt/内容变体、研究探索、测试改进，或多个实现策略之间的竞争。它尤其适合这样一种情况：单个 agent 可能陷入局部最优，而你希望获得更多方案多样性，同时又不想手动管理分支、状态记录和结果排序。

关键差异与使用约束

agenthub skill 最重要的差异点是基于 git 的隔离机制：agent 的输出会分别放在 hub/{session-id}/agent-{N}/attempt-{M} 分支中，而不是混杂在同一个工作区里。AgentHub 还提供了 fan-out/fan-in、tournament 和 ensemble 等协作模式的参考资料，以及用于 session 初始化、board 管理、DAG 分析、dry-run 校验和结果排序的脚本。主要限制是：你需要一个真实的 git 仓库；如果只是一次性聊天问答、没有文件、没有评估路径，或者不愿进行 merge review，那么它并不合适。

如何使用 agenthub skill

agenthub 安装与仓库准备

在你的 Claude skills 环境中安装这个 skill：

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

然后请在目标项目仓库中使用它，而不是在空文件夹里运行。生成 agents 之前，先确认 repo 是干净的，或者你明确知道哪些未提交文件应该被纳入基线。如果你想先检查实现细节，建议从 SKILL.md 开始，然后阅读：

• references/agent-templates.md：了解 optimizer、refactorer、explorer 以及相关 dispatch 风格。
• references/coordination-strategies.md：选择 fan-out、tournament 或 ensemble 工作流。
• references/dag-patterns.md：理解分支命名、frontier 检测和 merge 行为。
• scripts/hub_init.py、scripts/board_manager.py、scripts/dag_analyzer.py 和 scripts/result_ranker.py：查看具体运行机制。

命令与工作流

在常规 agenthub skill 使用中，它会提供如下 slash commands：

• /hub:init：定义任务、agent 数量、评估标准和 session。
• /hub:spawn：在隔离 worktree 中启动并行 subagents。
• /hub:status：查看进度和分支状态。
• /hub:board：读取或写入 dispatch、progress 和 result 记录。
• /hub:eval：按指标或 LLM judge 对输出排序。
• /hub:merge：合并获胜分支并归档其他分支。
• /hub:run：一键完成生命周期：init、baseline、spawn、evaluate、merge。

如果要手动验证，随附脚本展示了预期的运作方式。例如，hub_init.py 可以使用任务、agent 数量、评估命令、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 都清楚目标、可量化评分、允许的改动范围以及停止条件。

实用质量建议

多数 session 使用 2–5 个 agents 就足够了；仓库中的协作指南也指出，超过这个范围后收益会递减。能用指标评估时，优先选择 metric-based evaluation，因为它能减少主观判断带来的 winner selection 偏差。只有在文档质量、内容变体、研究综合这类没有可靠命令行指标的任务上，才考虑使用 LLM judge。对于大型任务，只有当 subtasks 确实相互独立时，才考虑 ensemble pattern；否则 fan-out/fan-in 更简单，也更安全。

agenthub skill 常见问题

agenthub 只适合代码任务吗？

不是。agenthub 以 git 为中心，但工作内容可以是代码、文档、prompts、研究笔记、benchmarks 或内容草稿，只要输出能放进仓库并且可以比较即可。当多个独立尝试能产出有意义差异时，它的价值最大。

agenthub 和普通 prompt 有什么不同？

普通 prompt 是让一次模型运行解决一个任务。agenthub skill 会协调多次尝试，把它们隔离在不同 worktrees 中，通过 board 记录进展，分析分支状态，并评估出获胜方案。当探索和比较比单个直接答案更重要时，这种结构就很关键。

新手可以使用 agenthub skill 吗？

可以，前提是理解基本 git 概念，例如 branches、commits 和 merge review。新手建议从 /hub:run 开始，或使用 2 个 agents 和一个清晰 evaluation command 的简单 /hub:init session。等你熟悉了如何审查竞争分支后，再尝试 tournament 或 ensemble 策略。

什么时候不该使用 agenthub？

如果任务很小、期望答案显而易见、repo 没有纳入 git、评估标准不清晰，或者解决 merge conflicts 的成本高于并行探索带来的收益，就不应该使用 agenthub。对于简单编辑，直接 prompt 加常规 review 通常更快。

如何改进 agenthub skill 的使用效果

生成 agents 前先优化 agenthub 输入

提升 agenthub skill 结果的最佳方式，是把“竞争规则”定义清楚。请包含任务、涉及的文件或模块、排除范围、agent 数量、template、evaluation command、metric name、metric direction、质量约束和 merge policy。如果 agents 要做优化，给出 baseline value；如果是起草内容，给出 rubric 以及可接受输出的示例。

避免常见失败模式

常见问题包括：agents 优化了错误指标、产出结果不可比较、覆盖了彼此的假设，或者留下了只通过窄 benchmark 但无法通过更广泛测试的分支。要避免这些问题，可以要求每个 agent 运行同一个 eval command，把进展写入 .agenthub/board/progress，把最终结果写入 .agenthub/board/results，并保持 commits 足够小，便于 review。当正确性比原始分数更重要时，请加入 “all tests must pass” 作为约束。

在第一轮结果后继续迭代

执行 /hub:eval 后，不要盲目合并。先检查获胜分支的 diff，阅读未获胜 agents 的 result posts，并寻找可复用的局部思路。如果 winner 表现不错但优势不够明确，可以从获胜分支出发，用更精细的约束跑一轮 tournament-style second round。如果不同 agents 分别解决了相互独立的部分，可以考虑用 ensemble approach 做 cherry-picking，但前提是先检查 conflicts 和 test coverage。

把支持文件当作操作手册

为了更稳定地长期使用 agenthub skill，应把仓库中的支持文件当作 playbooks。使用 references/coordination-strategies.md 选择 orchestration pattern，用 references/agent-templates.md 将 agent 行为匹配到任务，用 references/dag-patterns.md 理解 branch/frontier 逻辑，并在依赖自动化之前用 scripts/dry_run.py 校验 skill files。这样，agenthub 就不只是一个看起来很酷的 parallel-agent 想法，而会变成可重复执行的仓库工作流。