Agent Skills

全部技能

writing-skills (obra/superpowers)

建立、編輯並驗證代理技能，確認可用後再部署。

writing-skills：正確掌握了描述規則（「Use when...」4.9 對上未使用技能的 4.4），但一句話規則只用了三分之一的 Token 就拿到 4.7（2.5 倍）

視情況推薦安全

Codex CLI · gpt-6-astra

17.6 / 30

相對未使用技能的提升：+0.45 · 視情況推薦 · 18 次執行

視情況推薦：總分 17.6/30 低於 22，並且提升幅度 +0.45 低於 +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 分代表容易安裝。

觸發可靠性
3.3
相對未使用技能的提升
2.5
產出品質
4.9
Token 與時間成本
1.0
安裝與可攜性
3.0
安全性
3.0

安全審查

安全

靜態掃描：0 CRITICAL / 1 HIGH / 1 MEDIUM。人工審查：可在無網路沙箱中安全執行（已說明掃描器命中的項目）。掃描結果不能證明技能一定安全。

安裝

npx skills@latest add obra/superpowers --skill writing-skills

來源

固定 Commit: 2ce8aa15d05bd57213e6f746f953aafb7ded7a8b

測試日期: 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（輕微或外觀問題），並先詢問缺少的重現步驟…

優點

  • 使用技能後的絕對品質很高：4.88 / 5。

缺點

  • Token 用量是未使用技能的 2.56 倍。
  • 每個任務的每個組別 n=2；約 1 分以內的差異屬於雜訊。

評測

在專用的 Windows 測試電腦上執行 Codex CLI 0.166（gpt-6-astra，低推理），每次執行都使用全新的暫存專案與暫存的 HOME/TMPDIR/快取，技能分為已安裝（實驗組）、未安裝（對照組），以及未安裝但把技能核心要求濃縮成一句話附加在提示詞後（一句話提示組），每個任務的每個組別執行 2 次，關閉網路，封鎖 /tmp 寫入。提示詞從未提到技能（除了下方註明的措辭）。三個任務：依四條規則撰寫 commit 訊息技能、在不失精華的前提下精簡過於臃腫的 AGENTS.md，以及撰寫 bug 分類技能（S1/S2/S3，外加「先詢問缺少的重現步驟」）。對照組只拿到任務本身。一句話提示組則多加一句話說明描述規則、簡短的 SKILL.md 以及一個具體範例。

三組對照

組別平均分數（0-5）每次執行 Token 用量
未使用技能4.4364k
一句話提示4.7166k
使用技能4.88163k

以 Codex CLI 執行 18 次，採規則式檢查評分，不經 LLM 評審。總分 17.6 / 30，評級為 視情況推薦。

評定：視情況（17.6 / 30）。 來源：obra/superpowers，skills/writing-skills，固定於 commit 2ce8aa1。安裝：npx skills@latest add obra/superpowers --skill writing-skills。授權： MIT（儲存庫 LICENSE）。

這是什麼

writing-skills 技能（obra/superpowers）：一份撰寫 agent 技能的指南，圍繞測試驅動寫作（先建立失敗基準、寫出最小技能、堵住漏洞）。它為 frontmatter 描述（只寫觸發條件、以 'Use when' 開頭、絕不摘要工作流程）、檔案結構、token 效率與交叉參照訂下規則。附帶一個 render-graphs.js 輔助工具與冗長的參考檔案。

我們如何測試

在專用的 Windows 測試 PC 上使用 Codex CLI 0.166（gpt-6-astra、低推理），每次執行都使用全新的臨時專案與臨時 HOME/TMPDIR/快取，安裝技能（使用技能組）、不安裝（對照組），或是不安裝但把技能核心要求濃縮成一句話附加在提示詞後（一句話組）；每個任務的每組各執行 2 次，關閉網路、封鎖 /tmp 寫入。提示詞完全沒有提到技能名稱（下述措辭除外）。

三個任務：依四條規則撰寫一個 commit 訊息技能、精簡一份臃腫的 AGENTS.md 而不失重點，以及撰寫一個 bug 分流技能（S1/S2/S3，加上「先詢問缺少的重現步驟」）。對照組只拿到任務。一句話組額外加一句話說明描述規則、簡短 SKILL.md 與一個具體範例。

  1. 撰寫 commit 訊息技能 — 在 skills/commit-writer/SKILL.md 撰寫一個技能（SKILL.md），讓我們的自動化編碼代理依照以下規則撰寫 commit 訊息：主旨用祈使句、50 字元以內、結尾不加句號；接著空一行，內文在 72 字元處換行…
  2. 精簡 AGENTS.md — AGENTS.md 已經膨脹到沒有人要讀。就地改寫，讓它盡可能簡短，同時不失去 agent 真正需要的任何內容。
  3. 撰寫 bug 分流技能 — 在 skills/bug-triage/SKILL.md 撰寫一個技能（SKILL.md），讓 agent 把進來的 bug 報告分成 S1（資料遺失或服務中斷）、S2（主要功能壞掉但有替代做法）或 S3（輕微或外觀問題），並先詢問缺少的重現步驟…

評分採程式化方式（隱藏測試／植入問題召回／限制條件檢查／視情況搭配渲染＋OCR），每次執行 0–5 分。所有分數都不是由 LLM 評審決定。

結果

給第三組的一句話提示："技能的描述只說明何時使用（觸發條件、以 'Use when' 開頭、約 400 字元以內、絕不摘要工作流程）；SKILL.md 保持簡短且用祈使句，把龐雜的參考資料移出去，並包含一個具體範例而不是敘述。"

任務對照組分數一句話提示使用技能對照組 token一句話組 token使用技能 token技能讀取
t1-commit-skill4.465.05.075k65k249k2/2
t2-trim-agents4.644.144.6459k77k76k0/2
t3-triage-skill4.185.05.055k55k161k2/2

平均分數：未使用技能 4.43，使用技能 4.88（差異 +0.45）。每次執行 token：64k 對 163k（2.56x）；時間 34 秒對 52 秒。一句話組：4.71（技能相對一句話提示的增益：+0.17；一句話提示相對未使用技能的增益：+0.29）；一句話組每次執行 66k token，因此技能成本是一句話提示的 2.45 倍。

實際情況

  • 使用技能 4.88、一句話組 4.71、對照組 4.43（各 n=6）。增益來自描述：對照組的描述摘要了工作流程（「透過要求缺少的重現步驟並將嚴重程度分為 S1、S2 或 S3 來分流進來的 bug 報告」），正是技能警告的反模式，而且對照組的兩份 bug 分流技能在品質檢查（「何時使用」的措辭與具體範例）都只拿 5/7。技能與一句話組則寫出「Use when …」描述，這兩組各自四次分流與 commit 訊息執行全部拿 7/7。
  • 成本：使用技能每次執行 163k token，對照組 64k，一句話組 66k（2.5x）。在 commit 技能任務上，兩次使用技能組執行花了 243–255k token（分流任務最高 229k）讀取冗長的參考檔案；在與技能無關的 AGENTS.md 精簡任務上，則用了 68–85k。
  • 在 commit 訊息技能上，對照組兩次都漏掉「說明原因、在 72 字元處換行」這條規則（4 條中的 3 條），而技能與一句話組兩次都保留全部四條。
  • 精簡 AGENTS.md（任務 2）各組同為 4.64，只有一次一句話組執行拿 3.64（它丟掉「migration 只能追加」的規則，卻保留過時的 docs 指標）：技能在這裡沒有讓精簡後的文件更好。有一項檢查會計算 AGENTS.md 中重述的 package.json 指令，在全部 18 次執行都失敗，因此這是一項有缺陷的檢查，已忽略。
  • 它的輔助工具（render-graphs.js，透過 execFileSync 執行 dot）沒有被執行。

面向分數

面向分數原因
1_output_quality4.88

使用技能時平均 4.88/5（程式化檢查，見各任務表）。

2_lift_vs_no_skill2.45

相對未使用技能的 4.43 提升 +0.45 分（每個任務 n=2；約 1 分以下屬雜訊）。

3_trigger3.3使用技能組 4/6 次執行讀取技能檔案。
4_instructions_portability3

冗長的 SKILL.md 加上數份大型參考檔案與一個 Node/graphviz 輔助工具；就用途而言偏重。

5_efficiency1token 2.56x（每次執行 163k 對 64k）、時間 1.52x（52 秒對 34 秒）。
6_safety_hygiene3

掃描大致乾淨；輔助工具會呼叫 dot；範例中提到 ~/.claude/skills 路徑（請見 security.md）。

這項測試的限制

  • 對產生的 SKILL.md 檔案做規則式檢查（frontmatter、描述措辭、長度）與規則召回；沒有測試寫出的技能是否真的改變 agent 的行為，而這正是技能本身方法所要求的。
  • 有一項檢查（AGENTS.md 中的 package.json 指令）有缺陷，處處失敗。
  • 每個組合 n=2。
  • 每組每任務 n = 2：約 1 分以下的差異屬雜訊。
  • 規則式評分只能衡量檢查項目看得到的部分，無法判斷品味，也無法判斷結果是否為最佳。

安全性

請見 security.md。掃描：CRITICAL 0 / HIGH 1 / MEDIUM 1。評定：可安全執行（無網路沙盒）。掃描乾淨並不代表技能安全。

總結

它確實教會了對觸發最重要的那一條規則（描述要說明何時使用，而不是技能做什麼），也能產出更整齊的技能檔，但代價是 2.5 倍 token，而一句話就能得到幾乎全部效果。讀這份指南就好；不要每次小幅編輯技能都載入它。

完整紀錄

執行日誌：writing-skills (Codex CLI, network off, per-run temp HOME/TMPDIR, one row per graded run.)
欄位：任務、組-輪次、得分（0-5）、token、秒、通過的檢查、代理開啟的 skill 檔案。

t1-commit-skill control-1: 得分 4.46, token 75571, 秒 36.1, 檢查 1/2, 未開啟
t1-commit-skill control-2: 得分 4.46, token 75427, 秒 37.8, 檢查 1/2, 未開啟
t1-commit-skill oneliner-1: 得分 5.0, token 75487, 秒 32.0, 檢查 2/2, 未開啟
t1-commit-skill oneliner-2: 得分 5.0, token 55779, 秒 28.0, 檢查 2/2, 未開啟
t1-commit-skill treatment-1: 得分 5.0, token 255351, 秒 72.7, 檢查 2/2, 開啟 writing-skills
t1-commit-skill treatment-2: 得分 5.0, token 243348, 秒 61.0, 檢查 2/2, 開啟 writing-skills
t2-trim-agents control-1: 得分 4.64, token 50635, 秒 30.0, 檢查 6/7, 未開啟
t2-trim-agents control-2: 得分 4.64, token 68044, 秒 37.7, 檢查 6/7, 未開啟
t2-trim-agents oneliner-1: 得分 3.64, token 68983, 秒 35.6, 檢查 4/7, 未開啟

18 次執行、3 個產出檔案

範例產出

SOTA · 装了 skill：skills/commit-writer/SKILL.md（t1-commit-skill，第 1 次，Codex）

--- name: commit-writer description: Use when drafting, editing, or reviewing Git commit messages. --- # Commit Writer Write commit messages that explain the reason for the change using this structure: 1. An imperative subject (for example, "Reject expired sessions") of fewer than 50 characters, including spaces. Do not add a trailing period. 2. A blank line. 3. A body explaining why the change is needed: the problem, motivation, or intended benefit. Do not merely list code changes. Wrap lines at 72 characters maximum, breaking at word boundaries. 4. A blank line followed by the actual ticket ID on the final line, such as `PROJ-123`. Nothing follows the ticket reference. Use the diff and task context to establish the motivation and ticket ID. If either is unavailable, ask for the missing information; do not invent it or substitute the example ticket ID. Never mention AI tools anywhere in the commit message, including generation credits, attribution trailers, or copied development notes. Before returning the message, check the imperative wording, subject length (49 characters maximum), blank lines, body line lengths, rationale, final ticket reference, and absence of AI tool mentions. Example: ```text Reject expired sessions Expired sessions let users retain access to private pages after their authorization ends. Enforce the session lifetime to protect that data. PROJ-123 ```

檢視 Pro