name: skill-perf description: "測量 OpenClaw 環境中 Skill 的 token 消耗和效能開銷（僅適用於 OpenClaw Agent 環境）。當用戶提到「測量」「測試」「效能」「token 消耗」「多少 token」「開銷」「成本」「效率」或想要評估、對比、最佳化某個 skill 的資源使用時，立即使用此 skill。也適用於 skill 釋出前的效能驗證、多輪測試對比、熱/冷快取分析、以及分析兩個 skill 之間消耗差異。英文觸發詞：measure token cost, performance test, how many tokens, benchmark skill。即使使用者沒有明確說「skill-perf」，只要涉及 OpenClaw skill 效能分析就應觸發。技術實現：通過 OpenClaw 的 sessions_spawn 啟動雙 subagent 併發測量，自動扣除系統底噪，生成 HTML 報告和置信度評級。" user-invocable: true metadata: openclaw: emoji: "📊"

Skill Performance Monitor

測量 Skill 的 token 消耗。

核心架構：雙 subagent 併發

主對話（parent）同一 turn：
  ├── sessions_spawn → 標定 subagent（空任務，獲取底噪基線）
  └── sessions_spawn → 測試 subagent（執行被測 skill）
          ↓ 兩者併發執行
parent 輪詢 runs.json 保持 CommandLane 活躍，等待兩者完成
  → 從 .jsonl 取 totalTokens，計算淨消耗

關鍵原則：兩個 subagent 必須在同一個 turn 內同時 spawn，不能先等標定完成再 spawn 測試。

為什麼需要標定 subagent？ Subagent 的 bootstrap context 只有 AGENTS.md + TOOLS.md，底噪約 17,000~18,500 tokens，需要每輪實測（不能用固定值，會隨系統更新漂移）。

Step 1：讀被測 skill 的 SKILL.md

cat ~/.openclaw/skills/<skill名>/SKILL.md

理解 skill 的核心呼叫方式，用於構造測試 subagent 的 task。

小蔥技能站7w4.net每天更新，海量AI技能等你發現。

Step 2：同一 turn 內併發 spawn 兩個 subagent

在同一個響應 turn 中同時發出兩個 sessions_spawn，不要分兩次：

標定 subagent：

sessions_spawn:
  task: "只輸出 ANNOUNCE_SKIP，不做其他任何事。"
  label: "calib-<skill名>"
  runTimeoutSeconds: 60

測試 subagent（同一 turn）：

sessions_spawn:
  task: "<根據被測 skill 構造的呼叫指令，見下方「如何構造 task」>"
  label: "test-<skill名>"
  runTimeoutSeconds: 300

兩個 sessions_spawn 同時非阻塞返回 { status: "accepted", runId, childSessionKey }。

記錄兩個 childSessionKey，然後立即進入 Step 3 輪詢等待。

如何構造 task

task 讓 subagent 完整執行被測 skill 一次，skill 完成後最後一行輸出 ANNOUNCE_SKIP：

規則： - task 必須先描述 skill 要做的事，最後才說「輸出 ANNOUNCE_SKIP」 - 不要在 task 裡注入 skill 內容（讓 subagent 自己觸發 skill） - 如被測 skill 需要特定引數（URL、裝置型別等），在 task 裡明確給出 - ⚠️ ANNOUNCE_SKIP 是 OpenClaw 的官方魔法詞，必須原樣使用，不能改名 - ⚠️ 不要讓 test subagent 的 task 聽起來像 calib：task 首句必須是 skill 操作，「輸出 ANNOUNCE_SKIP」只能出現在末尾

Step 3：等待完成並生成報告

spawn 兩個 subagent 後，用輪詢指令碼保持 CommandLane 活躍，同時在 session 活著時讀取 totalTokens（session 結束後 ~5 分鐘被清除）：

bash ~/.openclaw/skills/skill-perf/scripts/wait_and_report.sh \
  "<CALIB_childSessionKey>" \
  "<TEST_childSessionKey>" \
  "<skill名>"

指令碼自動完成：輪詢等待 → 從 .jsonl 讀取 totalTokens → 生成報告。

⛔ 嚴禁自行生成 HTML 報告：報告必須由 wait_and_report.sh 或 snapshot.py report 指令碼生成，絕不能由 Agent 手動編寫 HTML 檔案。自行生成的 HTML 缺少詳細步驟分析、置信度評級、快取命中率等核心資料，屬於無效報告。

如果兩個 subagent 都已完成（announce 已到達），可使用以下指令碼生成報告（skill-perf 有專用報告模板，使用指令碼生成，避免 Agent 自行拼湊）：

python3 ~/.openclaw/skills/skill-perf/scripts/snapshot.py report \
  --session "<TEST_childSessionKey>" \
  --calib-key "<CALIB_childSessionKey>" \
  --skill-name "<skill名>"

Step 4：輸出摘要

報告生成後，從命令輸出中讀取並轉述以下摘要（不要自己計算，直接引用報告數字）：

底噪 (calib_noise):  <輸出中的底噪值>  tokens
TEST 總計:           <輸出中的 total>  tokens
NET 淨消耗:          <輸出中的 net_tokens>  tokens
置信度:              <輸出中的評級>
報告連結:            <輸出中 🌐 報告連結: 後的完整 URL（http://localhost:<隨機埠>/...html）>

⚠️ 報告連結必須填寫。連結含隨機埠，只有執行命令才能得到，無法自己推算。沒有連結 = 命令未執行 = 測試無效。

⛔ 報告檔案路徑說明：snapshot.py 會將報告儲存到 ~/.openclaw/skills/skill-perf/reports/ 並自動啟動本地 HTTP 服務，輸出 http://localhost:<埠>/...html 連結。不要把報告路徑寫成 /tmp/ 或其他自定義位置。

注意事項

• 併發是關鍵：兩個 subagent 必須在同一 turn 同時 spawn，先後 spawn 會導致它們序列等待，失去併發優勢
• sessions_spawn 是非阻塞的，立即返回 { status: "accepted", runId, childSessionKey }
• ⚠️ 嚴禁手動傳 --noise 引數：使用 --calib-key 讀取底噪
• ⛔ 嚴禁使用舊版 before/after 流程：子命令已廢棄刪除
• 多輪測試時：第 1 輪（冷快取）偏高屬正常，以第 2 輪及之後（熱快取）作為穩態參考值

📖 各 Skill 淨消耗參考值 & Token 欄位詳解 → 見 references/TOKEN_GUIDE.md

這是一個專業級的 skill 效能測量工具，能精確測量 skill 的 token 消耗，報告清晰詳細，文件齊全。但它比較複雜，對普通使用者不太友好，操作步驟多，使用門檻較高。更適合有技術背景的使用者或開發者使用。