miyago9267

Shoal — AI skill for Claude Code

AI community

只需定義一次 agent role，shoal 就能依照個廠牌 agent 配好模型、權限與 prompt，自動 orchestration；毋需撰寫任何程式.

How to install Shoal

This entry records only its repository, not the path inside it, so there is no exact command to give. Open miyago9267/shoal and copy the folder into ~/.claude/skills/, or the file into ~/.claude/agents/.

What Shoal does

只需定義一次 agent role，shoal 就能依照個廠牌 agent 配好模型、權限與 prompt，自動 orchestration；毋需撰寫任何程式。 / Define agent roles once. shoal resolves the model, permissions and prompt for each agent tool; adding a new tool is configuration, not code.

Alternatives in AI

Open Multi Agent — TypeScript multi-agent orchestration engine — one runTeam() call from goal to result 5.8k ★
Define — Definition phase - Clarify and scope problems with multi-AI consensus 2.8k ★
Loushang — AI-native agent harness for coding workflows by python: multi-model LLM orchestration, stateful sessions, tool 1.3k ★

README

shoal

只需定義一次 agent role，shoal 就能依照各廠牌 agent 配好模型、權限與 prompt，自動 orchestration；毋需撰寫任何程式。

繁體中文 · [English](docs/README.en.md) · [简体中文](docs/README.zh-CN.md)

它解決什麼

一份 role 定義，五個 host 各自拿到合適的模型、權限和 prompt。
主 session 負責判斷與整合，改檔和長指令派給對應的 role。
派工規則由 guard 在每個 host 強制執行，不靠模型自覺。
要支援新工具，填設定就好，不用寫程式。

運作方式

![分層：core、binding、各 host](docs/assets/shoal-overview-zh-TW.svg)

role 寫在 core，每個 host 用 binding 說明自己的模型與權限，再由 `render.py` 產出安裝檔。

![路由：一個 role 在各 host 選到哪個模型](docs/assets/shoal-routing-zh-TW.svg)

role 只寫 tier，不寫模型名稱；每個 host 從自己的模型目錄挑出符合的那一個。

![orchestration：一個回合怎麼分工](docs/assets/shoal-orchestration-zh-TW.svg)

主 session 先看工作的形狀和風險，再決定自己做、派給哪個 role，或走完整的審查流程。

![guard：哪些事會被擋、出口是什麼](docs/assets/shoal-guard-zh-TW.svg)

主 session 沒派可寫 role 就改檔，或 subagent 不是 shoal 的可寫 role 卻改檔，都會被擋；出口是改派可寫的 role，或在 prompt 加 `#direct`。

快速開始

# Codex CLI
bash install/install.sh --codex-home "${CODEX_HOME:-$HOME/.codex}"
# Claude Code（plugin，裝最新穩定版）
claude plugin marketplace add miyago9267/shoal
claude plugin install shoal@shoal
# Grok Build（不加 --apply 是 dry-run）
python3 tools/install_grok.py
# OpenCode（全域）
sh hosts/opencode/plugin/install/install.sh --global --enable

Gemini/agy 與不用 plugin 的 Claude Code 見 [INSTALL.md](./INSTALL.md)。

模組

只裝需要的部分：`python3 tools/shoal_install.py --host ` 預設只印出會執行的指令，加 `--apply` 才安裝。

不要派工守門就加 `--without dispatch-guard`，`--list` 列出模組與已安裝狀態。

外部 guard 經 guard chain 接入：`--chain-add` 登記，不需要改 shoal。

細節見 [INSTALL.md 的模組](./INSTALL.md#模組)。

支援的 host

Host	安裝方式	guard
Claude Code	plugin，或 `tools/install_hooks.py`	hook，預設擋
Codex CLI	`install/install.sh`	hook，需在 `/hooks` 核准一次
Gemini/agy	`hosts/agy/dist` 加 `tools/install_hooks.py`	hook，預設擋，沒有 `#direct`
Grok Build	`tools/install_grok.py`	原生 hooks
OpenCode	`install.sh --enable`	plugin 內建