---
title: "07 - Agent Skill：讓 AI 自己操控 Herdr"
type: note
specialty: Programming
tags: [herdr從0開始使用教學, 07-agent-skill, claude-code, skill]
created: 2026-08-04
updated: "2026"
modified: 2026-08-04
---

# 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`](https://github.com/herdrdev/herdr/blob/master/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`（推薦）

```bash
npx skills add herdrdev/herdr --skill herdr -g
```

`-g` 是全域安裝（給支援的 agent）；不加 `-g` 就裝進目前專案。

> ⚠️ 如果你之前在 skill 還放在 repo 根目錄時就裝過，**要重跑一次這個 add 指令**（不要用 `skills update`）。add 會取代那份過大的舊檔並記錄新位置。

### 方法二：手動

拿 repo 那份當來源真相：

```text
https://github.com/herdrdev/herdr/blob/master/skills/herdr/SKILL.md
```

- 有 skill 系統的 agent → 裝成名為 `herdr` 的 skill
- 沒有 skill 系統的 agent → 把整份貼進 agent 的專案或使用者指令裡

### 方法三：從已安裝的 binary 印出來（版本一定對得上）

```bash
herdr --skill
```

這會印出**跟你這支 binary 同一個 release 的那份**。想直接落地：

```bash
mkdir -p ~/.claude/skills/herdr
herdr --skill > ~/.claude/skills/herdr/SKILL.md
```

> 💡 **建議用方法三**。因為 skill 裡描述的 CLI 行為會隨版本演進，用 binary 內建的那份可以確保「skill 講的」跟「binary 做的」一致。

---

## 安裝之後

在 Herdr 裡面啟動 agent：

```bash
herdr        # 先進 Herdr
claude       # 在 pane 裡開 Claude Code
```

或用任何其他 coding agent。**重點是 agent 的 process 要跑在 Herdr 裡面，這樣才有 `HERDR_ENV=1`。**

---

## 唯一的安全守則：`HERDR_ENV=1`

Skill 開頭就是一條 guardrail：

```bash
test "${HERDR_ENV:-}" = 1
```

**檢查沒過 → agent 應該說「我沒有跑在 Herdr 管理的 pane 裡」然後停手。**

為什麼？因為這樣可以防止「Herdr 外面的 agent」去控制一個**它不擁有的 session**。想像一下：你在別的視窗跑一個 Claude，它突然開始關掉你正在用的 pane——這條規則就是防這個。

Herdr 注入每個受管理 pane 的變數：

```bash
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），但你需要一段自己的規則來降低每次都要囉唆的成本：

```markdown
## 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。
```

**期待的行為**：

1. 它先跑 `test "${HERDR_ENV:-}" = 1`
2. 通過之後跑 `herdr workspace list` / `herdr pane list`
3. 回報實際的 ID 和內容

**如果它說「我沒辦法存取終端狀態」或開始亂猜** → skill 沒裝好，或者它不在 Herdr pane 裡。檢查：

```bash
echo "$HERDR_ENV"        # 應該是 1
ls ~/.claude/skills/herdr/SKILL.md
```

---

## 一個容易忽略的好處：Claude 可以「看」你的其他終端

Skill 裝好之後，Claude 不只能開新 agent，還能**檢視你手邊已經在跑的東西**：

```bash
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 判斷「做完沒」的依據
- [[Programming/Codex/Codex從0開始使用教學/06-進階功能-Skills-Automations-多代理|Codex 06 - 進階功能]] — Codex 那邊的 Skills 概念

---

*最後更新：2026-08-04*