在 Nemia 中建立一個 Agent 是做什麼的？

一個 Agent 就是一個僱員：一個擁有工作、標準（其技能）和設備（其工具）的人。一個工作流程的步驟就是它填補的一個職位；一個 Agent 可以填補多個工作流程中的職位。一個人的工廠無法從 Nemia 取得 Agent：儲存庫的團隊在它的 workflows/ 目錄中，個人的則在 ~/.agent-workflows/workflows/ 中，而看板的 Agent 頁面會寫入第二種。請閱讀 Nemia 的 README，Agent 是節點的附件，以了解完整格式；這裡只說明程序以及學習它所付出的代價。

它是誰

它的名稱就是其檔案的名稱，檔案位於 agents/<name>.md，使用全小寫的名字（nora），而步驟透過該名稱來引用它（agent: nora）。看板會將該名稱顯示為一個人的名字（Nora），旁邊並有根據名字生成的頭像（Blobatar），在任何顯示位置都一致。
role: 是其擔任的職位，用幾個字描述（Product engineer）；description: 則說明何時應該使用它，一行即可。這兩個都是 Agent 自己的設定行，與 harnessPrompt: 相同：一個試圖設定這些項目的步驟將被拒絕。步驟的 skills: 會加入到其 Agent 的技能中（技能）。
mcp: 指定其對話要載入的 MCP 伺服器，使用結案目錄中 .mcp.json 所賦予的名稱（mcp: playwright）。步驟的 mcp: 會加入到其 Agent 的 MCP 列表中，就像它的 skills: 一樣：一個只有單一儲存庫擁有的伺服器，由需要它的步驟來命名，這樣 Agent 就能保持可攜性。一次對話只載入其 Agent 和步驟所命名的伺服器，沒有其他：如果兩者都沒有設定，則不載入任何伺服器；而一個在結案目錄中未宣告的名稱，會在對話開始時就被拒絕。載入一個伺服器並不允許使用它的所有工具：仍然由其圍欄來決定。一個命名了伺服器的 Agent 無法被試執行，因為試執行沒有結案目錄。
name: 設定行必須與檔案名稱相同；card: 已被棄用（卡片是從其技能生成的：npx wf agents card <name>）。

檔案

首先是前端資料，然後是指令。其他金鑰則決定其對話如何運作——harness、model、effort、context、remote、output 以及它的圍欄——而一個引用它的步驟會使用這些設定，除非步驟本身設定了自己的值。接線（Wiring）是步驟的職責，在此不允許設定：after、input、workspace、check、gate、loop、budget、background。

圍欄放在其 harness 的區塊下：claude: { fence: { permissionMode, tools, allowedTools, disallowedTools } }，或 codex: { fence: { sandbox } }。該區塊只能包含 fence，而如果檔案本身屬於另一個 harness，則拒絕該區塊。頂層的圍欄金鑰是舊的寫法，但仍然會被讀取；nemia frontmatter rewrite <folder> 會將其移入對應的區塊中。
指定步驟可以覆蓋哪些項目：overridable: model, effort, fence, skills，每個詞必須是 OVERRIDABLE 中的一個（model, effort, context, harness, remote, output, fence, skills, mcp）。一個步驟如果設定了這些以外的東西，在載入時會被拒絕，並指明是哪個金鑰和哪個 Agent。如果沒有這行設定，步驟可以覆蓋所有東西，而 nemia start 會提示你加入這一行。

---
role: Code reviewer
harness: claude
model: opus
overridable: model, effort, fence
claude:
  fence:
    permissionMode: dontAsk
    tools: Read, Grep, Glob, Bash
    allowedTools: Bash(git log:*), Bash(git diff:*)
---

前端資料是 YAML，與步驟和技能的格式相同，每個值都按文字內容讀取。如果一個值包含 : 或 #，或者以 YAML 的特殊符號開頭（[, {, *, &, !, |, >, -, ?），則需要用引號括起來，例如 description: "Reviews a change: its correctness"。長數值可以寫成 literal 區塊，使用 |- 並在下面縮排書寫。列表金鑰可以使用 Read, Grep 或 [Read, Grep] 兩種寫法；看板會使用第一種寫法。
指定 effort: 和 context:（例如 200k）：一個任務不會讀取使用者設定，而一個未限制範圍的對話在每次呼叫時可能會讀取多達一百萬個 tokens。
對於經測量後確定會被降級的模型（如 haiku、claude-sonnet-4-5），auto 模式在載入時會被拒絕；請在那裡使用 dontAsk 並加上規則。

它的指令

檔案的主體就是其指令，會附加到 Claude Code 本身的提示詞之後（harnessPrompt: keep；no-coding 會移除 harness 的編碼相關章節，replace 則直接用指令替換它）。保持指令的通用性和簡潔性：說明它是誰、它對什麼負責、它絕對不做什麼、它如何結束一個回合、以及它的結案應該包含什麼。程序性的內容應該放在技能中，而機制本身已經處理的規則（如圍欄、閘門）則不需要額外說明。一個被恢復的對話會沿用開始時的指令主體：對指令的編輯只會影響下一次執行，絕不會影響正在進行中的對話。

五個層級

指令是塑造 Agent（除了其任務之外）的五個層級之一，每個層級由擁有者撰寫：

指令 — Agent 的主體：說明它是誰，無論它在哪裡被僱用。
自訂指令 — 使用者在無需改寫 Agent 的情況下添加的內容，儲存在使用者的儲存庫中，每個 Agent 名稱一個檔案（wf agents custom <name>），永遠不會放在 Agent 的資料夾中。僅包含文字：不設定任何金鑰，因此絕不會擴大圍欄或提供工具。一次執行在啟動時會凍結這些自訂指令，因此對它們的編輯只會影響之後的執行。
資料夾檔案 — Harness 從 Agent 工作的資料夾中讀取的檔案（目前是 CLAUDE.md、AGENTS.md）：這些內容適用於在其中工作的所有 Agent。Nemia 不會對它們進行組合。它們的優先級高於 Agent 自身的指令，但低於工廠規則和步驟政策，儘管 harness 可能將它們呈現為覆蓋所有其他內容：那是 harness 本身的框架。
工廠規則 — 一個工廠的規則和政策，告知所有受僱於該工廠的 Agent：每個工廠一個檔案，儲存在儲存庫中（nemia factory rules <name>），永遠不會放在儲存庫中。僅包含文字，並在執行開始時凍結，如同自訂指令。遠端 Agent 上的步驟不會被告知這些規則。
步驟政策 — 步驟自身的文字和金鑰：此流程的這個職位對某個角色有什麼要求。這是一個正常的層級，不是一種變通方法：在這裡說明一個工作流程期望什麼，並將其排除在指令之外。一個步驟可以增加技能，但絕不能移除技能。

數字代表優先級：當兩個層級說法不一致時，數字較高的層級獲勝，而任務本身高於所有層級。文字到達的順序是另一回事——指令、自訂指令、工廠規則、步驟政策，然後是任務，而資料夾檔案則由 harness 在 Agent 工作的任何地方讀取。哪個層級擁有哪個新指令是 Nemia 自己的路由規則，新指令該去哪裡，在內建的五個層級章節中說明過一次：與其猜測，不如直接問。圍欄只會收緊：一個步驟可以縮小其 Agent 的圍欄，但絕不能擴大它——步驟的 disallowedTools: 會加入到 Agent 的列表中，而載入器會拒絕步驟中任何會賦予 Agent 其檔案所不允許的 tools:、allowedTools:、permissionMode: 或 sandbox:。因此，指令應該說明適用於所有場合的原則，而不要涉及特定工作流程或工作區。

它的結案

output: <name>.schema.json，是一個放在 Agent 旁邊的 JSON Schema：定義了步驟最終會交付什麼，並進行嚴格解碼。內部風格：每個欄位都應有 described、required，並設定 additionalProperties: false。

保留欄位： outcome、summary、artifacts、needs 是每次結案時執行本身會有的欄位；載入器會拒絕宣告其中任何一個的綱要。（因此 Iris 的意圖使用了 proposedOutcome。）
在一次對話的多個試行之間保持綱要一致：如果已繼續的對話發現綱要改變，會重建整個提示快取。
一個步驟可以透過 input: <step> 讀取它所等待的任何步驟的結案，也可以透過中間的步驟讀取；一個會迴圈的步驟（loop:）可能只等待一個步驟，因此它只能透過這種方式讀取迴圈之前的內容（例如，一個審查步驟會這樣讀取規格）。

它的技能

skills: <a>, <b> 指定存放 SKILL.md 的資料夾名稱。系統會依序在 skills/（與 agents 資料夾同層）、儲存庫的 .claude/skills/、儲存庫的目錄、以及 Nemia 自身的技能目錄中尋找。tools: 必須允許 Skill 工具。儲存庫的 .claude/skills/ 僅在該儲存庫是步驟的所在位置時才會被找到，就像啟動指令所賦予的那樣：一個載入資料夾的測試也會傳遞位置資訊。一個帶有 Agent 的步驟可以透過自己的 skills: 來新增技能：對話會先取得 Agent 的技能，然後是步驟的技能，每個技能只出現一次。Agent 的圍欄必須已經允許載入這些技能；步驟永遠不能擴大圍欄。

撰寫技能 使用技能建立工具的方法：一個 description: 說明何時使用它，一個簡短的主體，以及詳細內容放在旁邊的檔案中。
使用他人的技能 保持不變：在一個暫存專案中，執行 DO_NOT_TRACK=1 npx skills add <owner>/<repo> --skill <name> --agent claude-code --copy -y；將該技能資料夾複製到 .claude/skills/ 中，將其條目合併到 skills-lock.json，並將其作者、來源和授權條款添加到 THIRD_PARTY_NOTICES.md（MIT 授權要求在每個副本中都有聲明）。永遠不要編輯它——鎖定檔案會固定它——如需調整，請在 Agent 的主體中進行。如果一個模型可能會呼叫某個技能，請將其供應商化：一個設定 disable-model-invocation: true 的技能是使用者的斜線指令（例如，grill-me 只會呼叫 grilling）。

它的圍欄

一個不寫入任何內容的角色應使用 dontAsk 模式。 只允許在其工作區內進行讀取、唯讀指令，以及允許規則所命名的內容；其他所有操作都會被拒絕而不詢問。儲存庫的設定可能允許其他角色需要的、會寫入工作區的指令（例如建置），因此被賦予 Bash 的 Agent 需要透過 disallowedTools: 逐一禁止這些指令。子 Agent 會繼承模式和規則；請在 allowedTools: 中列出 Agent，這樣派遣本身永遠不會被拒絕。請根據確切名稱允許該角色執行、但儲存庫設定不允許的每個檢查；其技能應該精確地拼寫每個指令，每次一個呼叫（任何包裝、管線、重新導向，或放在 cd、git -C、VAR= 或 for 後面的指令都會被拒絕），並將讀取或搜尋操作交給 Read、Grep 或 Glob，而不是 Bash。
一個會編輯的角色應使用 auto 模式，並根據名稱禁止它絕對不能做的事情：例如 Bash(git push)、Bash(git push:*)、Bash(git branch -D:*)、Bash(git branch --delete --force:*)、Bash(pkill:*)、Bash(killall:*)、mcp__playwright__browser_run_code_unsafe。
步驟只能收緊圍欄，而且只能在 overridable: 指定了 fence 的情況下進行。如果一個步驟需要某個工具、允許規則或模式，而 Agent 的檔案沒有提供，則需要另一個 Agent；步驟的 disallowedTools: 會加入到其 Agent 的列表中：只需寫入步驟新增的禁止項目；它永遠不能移除 Agent 的任何禁止項目。

與使用者對話

一個步驟是 Agent SDK 上的一個工作：它不能在對話內部等待。要提出問題，它會以 blocked 狀態結案，並附上問題；使用者可以在看板上回答，或使用 wf retry <run> <step> --message "…" 指令回答，然後同一個對話會繼續進行，並將答案作為下一個回合。請在需要面試的 Agent 的主體中說明這一點，並對使用者必須確認結案的步驟設定閘門（gate: true）。一個工作的最後一個回合是它的結案訊號：一個執行長時間指令的 Agent（例如 e2e 測試）應該被告知要在前景執行或等待它們，絕不能在有指令正在執行時就結案（例如，一個工程師的第一次網頁建置就在 e2e 測試結束前結案了）。一個標記為 blocked 的結案會獨立被讀取，因此一個進行多回合問答的 Agent 應該在每個回合中都攜帶所有已確定的資訊：例如，一個面試官在第三個回合曾遺失之前做出的決定。請將問題宣告為輸出綱要的一個欄位，格式為 { "x-shape": "questions", "description": "…" }，載入器會將其擴展為一個嚴格的形狀：看板會將它們繪製為使用者可以點擊選擇的選項。一個設有閘門的步驟，如果知道後續步驟的成本，可以在旁邊宣告 { "x-shape": "budgets", "description": "…" }：這是一個包含 { step, usd, why } 的列表，每個項目代表閘門之後的一個步驟，每個步驟只出現一次，金額為大於零的美元，why 說明金額的計算依據。閘門會在結案旁顯示這些預算，批准時會將它們設為那些步驟的上限，並使用使用者可能修改的任何金額（nemia approve <run> <step> --budget <step>=<amount>）；如果上限超過步驟自身的 budget:，會在那裡顯示，且未經要求絕不會批准。一個結案如果其預算指定了另一個步驟、或者沒有金額，將被拒絕並退回其對話。

驗證

在儲存庫中執行 npx wf agents card <name>：真實的載入器會讀取檔案——檢查其金鑰、其綱要中的保留名稱、找到的每個技能——然後印出卡片，或者如果失敗，會用文字指出需要修正的地方。
執行儲存庫自身的檢查，其中它的保護機制會讀取它發布的每個資料夾（圍欄、凍結的步驟、渲染往返測試）：請忽略任何看不到 workflows 資料夾的快取來執行它們。
實際執行它：一個設有閘門的工作流程，使用一個小型的真實卡片來命名該 Agent，並在批准前閱讀其結案。
在儲存庫列出其 Agent 的地方，將新 Agent 的名稱加入。

當你學到新東西時

建立一個 Agent 是驗證此技能的方式。當此處的某個步驟被發現是錯誤或遺漏時——例如你遇到了一個拒絕、或一個你沒預料到的金鑰——請在和建立 Agent 的相同變更中修正這個檔案，最多修改三行，並附上包含該規則的檔案。

在 Nemia 中建立一個 Agent