writing-for-agents (mattpocock/skills)
撰寫與編輯技能、AGENTS.md 與 CLAUDE.md 等代理能可靠遵循的文件。
writing-for-agents：最明顯的助益是精簡 AGENTS.md 而不流失規則（5.0 對 4.3），但在撰寫新技能上分數與對照組相當；一句話提示拿到 4.6，技能則為 4.5
Codex CLI · gpt-6-astra
24.9 / 30
相對未使用技能的提升：+0.35 · 視情況推薦 · 18 次執行
視情況推薦：提升幅度 +0.35 低於 +1.0。推薦條件為總分至少 22/30、產出品質至少 3.5、提升幅度至少 +1.0。
SOTA
透過使用 Codex 測試。
涵蓋 Codex, Claude Code
Codex CLI 0.166（SOTA 等級）：18 次評分執行。依我們的等級規則，在這裡通過也涵蓋 Claude Code；但這不代表第二等級的結果。
分數
每個維度為 0 到 5 分，六個維度相加即為滿分 30 的總分。每個維度都是 5 分最好。成本 5 分代表便宜又快速；安裝 5 分代表容易安裝。
- 觸發可靠性
- 5.0
- 相對未使用技能的提升
- 2.4
- 產出品質
- 4.5
- Token 與時間成本
- 4.0
- 安裝與可攜性
- 4.0
- 安全性
- 5.0
安全審查
安全靜態掃描：0 CRITICAL / 0 HIGH / 0 MEDIUM。人工審查：可在無網路沙箱中安全執行（未發現問題）。掃描結果乾淨，不代表技能一定安全。
安裝
npx skills@latest add mattpocock/skills --skill writing-for-agents
固定 Commit: 4ae2317ddb22b046e26455e4f9c9b3aaaf62212d
測試日期: 2026-11-02
我們測了什麼
- 撰寫 Commit 訊息技能 — 在 skills/commit-writer/SKILL.md 寫一個技能（SKILL.md），讓我們的自動化代理依下列規則撰寫 Commit 訊息：主旨使用祈使句、50 字元以內、結尾不加句號；接著空一行，內文以 72 字元換行…
- 精簡 AGENTS.md — AGENTS.md 已經膨脹到沒有人要讀。就地改寫，讓它盡可能短，同時不流失代理真正需要的任何內容。
- 撰寫 bug 分流技能 — 在 skills/bug-triage/SKILL.md 寫一個技能（SKILL.md），讓代理把進來的 bug 回報分類為 S1（資料遺失或服務中斷）、S2（主要功能損壞但有替代做法）或 S3（輕微或外觀問題），並先要求補上缺漏的重現步驟…
優點
- 技能即使未被點名也會被採用：6/6 次實驗組執行都讀取了技能檔案。
- 使用技能後的絕對品質很高：4.52 / 5。
缺點
- 一句話提示得分 4.63，使用技能則為 4.52（-0.11）。
- 每個任務的每個組別 n=2；約 1 分以內的差異屬於雜訊。
評測
Codex CLI 0.166（gpt-6-astra，低推理）在專用的 Windows 測試電腦上執行，每次執行都使用全新的暫存專案與暫存的 HOME/TMPDIR/快取；技能已安裝（實驗組）、未安裝（對照組），或未安裝但把技能的核心要求濃縮成一句話附在提示詞後（一句話提示組）。每個任務的每個組別執行 2 次，關閉網路，封鎖 /tmp 寫入。提示詞從未提及技能（下方註明的措辭除外）。與 writing-skills 相同的三個任務：依四條規則撰寫 Commit 訊息技能、精簡臃腫的 AGENTS.md 而不流失重點（5 條真正規則埋在填充內容、重複內容與過時參照之間），以及撰寫 bug 分流技能。對照組只拿到任務。一句話提示組用一句話給出技能的主要規則。產生的 SKILL.md 以與 writing-skills 相同的 7 點檢查清單評分，該清單預期有「Use when ...」風格的描述；這個技能本身的建議是「trigger first」，而不是那樣的字面措辭。
三組對照
| 組別 | 平均分數（0-5） | 每次執行 Token 用量 |
|---|---|---|
| 未使用技能 | 4.17 | 70k |
| 一句話提示 | 4.63 | 76k |
| 使用技能 | 4.52 | 88k |
以 Codex CLI 執行 18 次，採規則式檢查評分，不經 LLM 評審。總分 24.9 / 30，評級為 視情況推薦。
判定：視情況而定（24.9 / 30）。 來源：mattpocock/skills，skills/productivity/writing-for-agents，固定於提交 4ae2317。安裝：npx skills@latest add mattpocock/skills --skill writing-for-agents。授權條款： MIT（儲存庫 LICENSE）。
這是什麼
writing-for-agents 技能（mattpocock/skills）：撰寫 agent 會閱讀的指示的指引：把觸發條件放在描述的開頭，每個不同分支各一個觸發條件；讓每個意義只有單一真實來源；刪掉模型本來就會遵循的無效指示，以及只是重述環境（腳本、設定）的句子；每一步都以可檢查的完成標準作結；並讓檔案保持簡短。
我們如何測試
在專用 Windows 測試 PC 上使用 Codex CLI 0.166（gpt-6-astra，低推理），每次執行都使用全新的暫存專案與暫存 HOME/TMPDIR/快取，安裝技能（實驗組）、未安裝（對照組），或未安裝但將技能核心要求濃縮成一句話附加在提示詞後（一句話提示組），每個任務每組執行 2 次，網路關閉，/tmp 寫入封鎖。提示詞從未提及技能（以下註明的措辭除外）。
與 writing-skills 相同的三項任務：依四條規則寫一個提交訊息技能、在不遺失必要內容的前提下精簡過於臃腫的 AGENTS.md（5 條真實規則埋在填充內容、重複項目與過時參照之間），以及寫一個 bug 分類技能。對照組只拿到任務。一句話提示用一句話給出技能的主要規則。產生的 SKILL.md 以與 writing-skills 相同的 7 點檢查清單評分，該清單期待「Use when ...」風格的描述；這個技能本身的建議是「觸發條件優先」，而不是那樣的固定措辭。
- 寫一個提交訊息技能 — 在 skills/commit-writer/SKILL.md 寫一個技能（SKILL.md），讓我們寫程式的 agent 依這些規則撰寫提交訊息：主旨用祈使句、50 字元以內、結尾不加句號；接著空一行，內文以 72 字元換行…
- 精簡 AGENTS.md — AGENTS.md 已經膨脹到沒有人要讀。就地改寫，讓它盡可能簡短，同時不遺失 agent 真正需要的任何內容。
- 寫一個 bug 分類技能 — 在 skills/bug-triage/SKILL.md 寫一個技能（SKILL.md），讓 agent 把進來的 bug 報告分類為 S1（資料遺失或服務中斷）、S2（主要功能損壞但有替代做法）或 S3（輕微或外觀問題），並先要求補上缺少的重現步驟…
評分方式為程式化檢查（隱藏測試／預埋問題召回／限制條件檢查／視情況進行渲染與 OCR），每次執行 0–5 分。沒有任何 LLM 評審決定分數。
結果
提供給第三組的一句話提示：「為 agent 而寫：把觸發條件放在描述開頭，每個不同分支各一個觸發條件；讓每個意義只有單一真實來源；刪掉模型本來就會遵循的無效指示，以及只是重述環境（腳本、設定）的句子；每一步都以可檢查的完成標準作結；並讓檔案保持簡短。」
| 任務 | 對照組分數 | 一句話提示 | 使用技能 | 對照組 Token 數 | 一句話提示 Token 數 | 使用技能 Token 數 | 技能讀取 |
|---|---|---|---|---|---|---|---|
| t1-commit-skill | 4.06 | 4.59 | 4.38 | 65k | 55k | 84k | 2/2 |
| t2-trim-agents | 4.29 | 4.71 | 5.0 | 67k | 95k | 96k | 2/2 |
| t3-triage-skill | 4.18 | 4.59 | 4.18 | 75k | 75k | 84k | 2/2 |
平均分數：未使用技能 4.17，使用技能 4.52（差異 +0.35）。每次執行 Token 數：70k 對 88k（1.27 倍）；時間 39 秒對 37 秒。一句話提示組：4.63（技能相較一句話提示的增益：-0.11；一句話提示相較無技能的增益：+0.46）；一句話提示每次執行 76k Token，因此技能的成本是一句話提示的 1.17 倍。
實際發生了什麼
- 平均：技能 4.52、一句話提示 4.63、對照組 4.17（各 n=6）。明確的勝利是 AGENTS.md 任務：技能兩次都 5.00（5 條必要規則全保留、填充內容移除、過時參照修正、重複項目合併），對照組 4.29、一句話提示 4.71。一句話提示兩次都在精簡時刪掉「migrations 只能追加」這條規則；技能組則保留了。
- 在兩個撰寫技能任務中，技能沒有比對照組好（4.18-4.59 對 4.06-4.18）：在這兩個任務的 4 次實驗組執行中，描述都是流程摘要，或沒有說明何時該使用技能（「Triage incoming bug reports by requesting missing reproduction steps and classifying severity...」，與對照組相同），因此 7 點檢查清單給了 5/7 或 6/7，和對照組一樣。一句話提示組寫出觸發風格的描述（「當進來的 bug 報告缺少重現步驟時，先要求補上...」）。
- 對照組在兩次提交訊息技能執行中都漏掉「內文以 72 字元換行、解釋原因」這條規則（4 條中的 3 條）；技能與一句話提示都保留四條。
- 成本：技能每次執行 88k Token，對照組 70k、一句話提示 76k（1.26 倍、1.16 倍）。實驗組執行每次會複製 4 個檔案到專案。
- 一項檢查會計算 AGENTS.md 中重述的 package.json 腳本，只有在這裡的 2 次對照組執行中失敗（3 個符合），與技能「不要重述環境」的規則一致。
各面向分數
| 面向 | 分數 | 原因 |
|---|---|---|
| 1_輸出品質 | 4.52 | 使用技能時平均分數 4.52/5（程式化檢查，見各任務 表格）。 |
| 2_相較無技能的提升 | 2.35 | 相較未使用技能的 4.17，+0.35 分（每項任務 n=2；約 1 分以下 屬於雜訊）。 |
| 3_觸發 | 5.0 | 技能檔案在 6/6 次實驗組執行中被讀取。 |
| 4_指令可攜性 | 4 | 一份簡短的 SKILL.md；沒有腳本。 |
| 5_效率 | 4 | 1.27 倍 Token（每次執行 88k 對 70k）與 0.94 倍時間（37 秒對 39 秒）。 |
| 6_安全性與衛生 | 5 | 僅有文字；沒有發現。 |
這項測試的限制
- 規則式檢查，部分借用 writing-skills 測試：7 點技能檢查清單偏好「Use when」措辭，而這個技能並不要求，因此在兩個撰寫技能任務上低估了它。
- 沒有人測試寫出的技能或精簡後的 AGENTS.md 是否真的改變 agent 的行為。
- 每個儲存格 n=2。
- 每項任務每組 n = 2：約 1 分以下的差異屬於雜訊。
- 規則式評分只能衡量檢查看得到的部分；無法評判品味，也無法判斷結果是否為最佳可能。
安全性
見 security.md。掃描：CRITICAL 0 / HIGH 0 / MEDIUM 0。判定：可安全執行（網路關閉的沙箱）。乾淨的掃描結果不能證明技能安全。
總結
對於精簡指示檔案值得（它保留了被一句話提示丟掉的每一條真實規則），除此之外，在撰寫新技能上與基礎模型相比沒有更好，且要 1.26 倍 Token。
完整紀錄
執行日誌：writing-for-agents (Codex CLI, network off, per-run temp HOME/TMPDIR, one row per graded run.) 欄位：任務、組-輪次、得分（0-5）、token、秒、通過的檢查、代理開啟的 skill 檔案。 t1-commit-skill control-1: 得分 4.06, token 55944, 秒 45.4, 檢查 1/2, 未開啟 t1-commit-skill control-2: 得分 4.06, token 75771, 秒 39.9, 檢查 1/2, 未開啟 t1-commit-skill oneliner-1: 得分 4.59, token 55800, 秒 30.0, 檢查 2/2, 未開啟 t1-commit-skill oneliner-2: 得分 4.59, token 55891, 秒 31.8, 檢查 2/2, 未開啟 t1-commit-skill treatment-1: 得分 4.18, token 84379, 秒 38.2, 檢查 1/2, 開啟 writing-for-agents t1-commit-skill treatment-2: 得分 4.59, token 84910, 秒 43.3, 檢查 2/2, 開啟 writing-for-agents t2-trim-agents control-1: 得分 3.93, token 67718, 秒 37.8, 檢查 5/7, 未開啟 t2-trim-agents control-2: 得分 4.64, token 68132, 秒 36.7, 檢查 6/7, 未開啟 t2-trim-agents oneliner-1: 得分 4.71, token 86525, 秒 36.9, 檢查 6/7, 未開啟
18 次執行、3 個產出檔案
範例產出
SOTA · 装了 skill：skills/commit-writer/SKILL.md（t1-commit-skill，第 1 次，Codex）
--- name: commit-writer description: Write or revise commit messages using the team's subject, rationale, and ticket-reference conventions. --- # Commit writer Base the message on the changes and their purpose in the available task context. Apply every rule below before returning the message: - Write an imperative subject (for example, "Fix" rather than "Fixed") under 50 characters, including spaces, with no trailing period. - Follow the subject with a blank line and a required body. Explain why the change is needed and its intended benefit, rather than listing what changed. Hard-wrap body lines at 72 characters or fewer. - End the message with the relevant ticket ID, such as `PROJ-123`, on its own line, separated from the body by a blank line. Use the actual ID from the task or branch context; if it is missing or ambiguous, ask for it rather than inventing one. - Keep the message focused on the change's rationale. Never mention AI tools, including in attribution or co-author trailers. Return the commit message as plain text when asked for a message.