07 - Agent Skill：讓 AI 自己操控 Herdr
← 06-CLI與自動化基礎 | 00-Index | 下一篇 → 08-Claude當大腦-Codex當雙手
這一章在幹嘛
前一章你學會自己下 herdr 指令。這一章把那套能力交給 Claude，讓它可以：
- 檢視 workspace、tab、pane、和隔壁的 agent
- 分割 pane、跑指令，而且不搶你的焦點
- 讀 pane 輸出和近期 log
- 等 server、等測試、或等另一個 agent 做完
- 在旁邊的 pane 啟動 helper agent
做完這一步，「Claude 當大腦、Codex 當雙手」才可能。
它是什麼（別誤會）
Herdr 的 agent skill 不是一個 app、也不是服務，它就是一個 Markdown 指令檔，路徑在 repo 的 skills/herdr/SKILL.md。
它教 agent「在 Herdr pane 裡面怎麼控制 Herdr」。裝進任何支援 skill 或自訂指令的 coding agent 就能用。
📌 另有一份不同用途的文件：https://herdr.dev/agent-guide.md 是給「幫人類學習 / 安裝 / 排錯 Herdr 的 agent」看的。 Skill 是給操作 Herdr 的 agent；Guide 是給教人類的 agent。 別搞混。
安裝
方法一：npx skills（推薦）
npx skills add herdrdev/herdr --skill herdr -g-g 是全域安裝（給支援的 agent）；不加 -g 就裝進目前專案。
⚠️ 如果你之前在 skill 還放在 repo 根目錄時就裝過，要重跑一次這個 add 指令（不要用
skills update）。add 會取代那份過大的舊檔並記錄新位置。
方法二：手動
拿 repo 那份當來源真相：
https://github.com/herdrdev/herdr/blob/master/skills/herdr/SKILL.md- 有 skill 系統的 agent → 裝成名為
herdr的 skill - 沒有 skill 系統的 agent → 把整份貼進 agent 的專案或使用者指令裡
方法三：從已安裝的 binary 印出來（版本一定對得上）
herdr --skill這會印出跟你這支 binary 同一個 release 的那份。想直接落地：
mkdir -p ~/.claude/skills/herdr
herdr --skill > ~/.claude/skills/herdr/SKILL.md💡 建議用方法三。因為 skill 裡描述的 CLI 行為會隨版本演進，用 binary 內建的那份可以確保「skill 講的」跟「binary 做的」一致。
安裝之後
在 Herdr 裡面啟動 agent：
herdr # 先進 Herdr
claude # 在 pane 裡開 Claude Code或用任何其他 coding agent。重點是 agent 的 process 要跑在 Herdr 裡面，這樣才有 HERDR_ENV=1。
唯一的安全守則：HERDR_ENV=1
Skill 開頭就是一條 guardrail：
test "${HERDR_ENV:-}" = 1檢查沒過 → agent 應該說「我沒有跑在 Herdr 管理的 pane 裡」然後停手。
為什麼？因為這樣可以防止「Herdr 外面的 agent」去控制一個它不擁有的 session。想像一下：你在別的視窗跑一個 Claude，它突然開始關掉你正在用的 pane——這條規則就是防這個。
Herdr 注入每個受管理 pane 的變數：
printf '%s\n' "$HERDR_ENV" "$HERDR_WORKSPACE_ID" "$HERDR_TAB_ID" "$HERDR_PANE_ID"Skill 教了 agent 哪些紀律（重點摘要）
這幾條是 skill 文件裡的硬規則，你自己寫 prompt 時也應該遵守同樣的紀律：
探索
- 用
herdr --help，再用herdr agent/herdr pane/herdr workspace這種「只打指令群、不帶子指令」來看說明。 - ❌ 不要跑光禿禿的
herdr來探索——那會啟動 / attach TUI。 - ❌ 不要用「省略參數」去試會改狀態的巢狀指令。像
herdr workspace create這種有預設值是合法的，它會真的執行。
版面
- 預設在目前 tab 開兄弟 pane、用目前的工作目錄。 除非使用者明確要求，不要自作主張建 workspace、tab、worktree 或換 cwd。
- 尊重使用者指定的方向；沒指定就先
herdr pane layout看形狀，寬的往右切、窄或高的往下切。 - 背景工作一律
--no-focus，除非使用者要求切過去。 - 明確保留呼叫者的工作目錄：
--cwd "$PWD"。
目標
- 用
--current、明確的 pane ID、或唯一的 agent 名字。 - ❌ 不要依賴別的 client 的 focus pane。
- ❌ 不要從 sidebar 順序或文件範例推 ID，一律從 JSON 回應 parse。
破壞性動作
- ❌ 不要關掉不是自己建立的 workspace / tab / pane / session，除非使用者明確要求。
- ❌ 絕不從一個活躍 session 裡跑
herdr server stop，除非使用者真的要停 server 和它的 pane process。 - ❌ 絕不殺掉主要的 Herdr process。 要做隔離實驗就用具名的測試 session。
給 Claude Code 的一份專案級指示（可直接抄）
Skill 裝好之後，建議在 ~/.claude/CLAUDE.md 或專案的 CLAUDE.md 再加一段「什麼時候該用」的規則。因為 skill 本身的觸發條件寫得很嚴格：
“Use only when the user explicitly mentions Herdr or asks to use Herdr… Do not use merely because a task could benefit from a background terminal, delegation, or parallel work.”
也就是說——你不明說，Claude 不會自己去用 Herdr。這是好的預設（避免它亂開 pane），但你需要一段自己的規則來降低每次都要囉唆的成本：
## Herdr 委派規則（Andrew 專用）
當任務同時滿足以下條件，主動提議「用 Herdr 開 Codex pane 分工」：
1. 可切成 ≥ 2 個彼此獨立的子任務
2. 每個子任務預期執行 > 5 分鐘
3. 子任務**不需要 PubMed MCP 或醫學事實查證**（那些我自己做）
提議時要講清楚：切幾個 pane、每個負責什麼、預期多久、以及我要怎麼驗收。
獲得同意後才動手，並遵守：
- 一律 `--no-focus`，不搶我的畫面
- 一律 `--cwd "$PWD"`
- Codex **只寫檔，不 commit、不 push**
- 全部做完由你（Claude）統一驗證 + 唯一一次 commit這段規則不是 Herdr 官方的，是根據你兩個 repo 的既有慣例（
Obsidian-med-note的「orchestrator 做唯一一次 commit」、Taiwan_IM_board的「零錯誤優先」）寫的。細節見 10-實戰-Obsidian醫學筆記庫。
驗證 skill 有沒有生效
在 Herdr 的一個 pane 裡開 Claude，然後問它：
你現在跑在 Herdr 裡面嗎？如果是，列出目前 session 有哪些 workspace 和 pane。
期待的行為：
- 它先跑
test "${HERDR_ENV:-}" = 1 - 通過之後跑
herdr workspace list/herdr pane list - 回報實際的 ID 和內容
如果它說「我沒辦法存取終端狀態」或開始亂猜 → skill 沒裝好，或者它不在 Herdr pane 裡。檢查：
echo "$HERDR_ENV" # 應該是 1
ls ~/.claude/skills/herdr/SKILL.md一個容易忽略的好處：Claude 可以「看」你的其他終端
Skill 裝好之後，Claude 不只能開新 agent，還能檢視你手邊已經在跑的東西：
herdr pane list --workspace "$HERDR_WORKSPACE_ID"
herdr pane read w1:p3 --source recent-unwrapped --lines 100實際用途：
- 「隔壁 pane 那個
npm run dev噴什麼錯？」→ 它自己去讀，不用你複製貼上 - 「幫我看一下 Codex 那邊卡在哪」→ 它讀
agent read+agent explain - 「等 build 跑完再繼續」→
pane wait-output
這件事本身就值得裝 skill，就算你完全不做多 agent 編排。
🔗 相關筆記
- 06-CLI與自動化基礎 — 上一步：指令本身
- 08-Claude當大腦-Codex當雙手 — 下一步：核心架構
- 05-Agent偵測與狀態機制 — Claude 判斷「做完沒」的依據
- Codex 06 - 進階功能 — Codex 那邊的 Skills 概念
最後更新：2026-08-04