skill-stocktake — 技能品質稽核
對已安裝的技能進行全面性、在同一個上下文環境中的評估，並為每個技能賦予一個
評定結果：保留 / 改善 / 更新 / 淘汰 / 合併。此技能不執行改善工作——一旦
產出評定結果，它會交接給 skill-creator（改善引擎）。這個界線是關鍵：stocktake
是品質關卡，skill-creator 是修復者。
設計備註：舊版本會 shell 出去執行掃描腳本，並將評估拆分為每次約 20 個技能的 子代理批次處理。在擁有 1M 上下文的環境中，這樣做不僅不必要，而且有害—— 批次處理會讓每個子代理看不到其他批次的技能，因此會錯過跨技能的重疊。 現在我們使用 Glob 列舉，並將每個技能讀入同一個上下文。重疊偵測依賴於此單一 上下文的視角。
模式 ($ARGUMENTS)
| 引數 | 行為 |
|---|---|
無 / full | 讀取並評估每個技能（預設） |
changed | 僅重新評估其 SKILL.md 修改時間晚於 results.json 中 evaluated_at 的技能；其餘技能從記錄中沿用之前的評定 |
changed 模式透過內聯方式偵測變更（無需腳本）：
find ~/.claude/skills -name SKILL.md -newermt "$(jq -r .evaluated_at ~/.claude/skills/skill-stocktake/results.json)"
階段 1 — 盤點
使用 Glob 列舉技能定義檔案（無需腳本）：
~/.claude/skills/*/SKILL.md~/.claude/skills/learned/*.md- 若當前工作目錄有
.claude/skills/，也包含{cwd}/.claude/skills/*/SKILL.md（專案技能）
由於 Glob 僅針對
SKILL.md/learned/*.md，因此.venv或.pytest_cache下的依賴 markdown 會被結構性地排除（無需修剪）。舊版find -name "*.md"會拉入的雜訊 不會發生。
使用次數統計：內聯讀取 ~/.claude/metrics/skill-usage.jsonl（PostToolUse 鉤子
log-skill-usage.sh 會寫入此檔案——這是一個獨立的計量層），並統計每個技能在
7 / 30 / 90 天內的事件次數。每行 JSON 格式為 {ts,event,skill,path,project}；
計算 invoke 和 read 事件。使用一次性 python3/jq 指令聚合，而非手動計數——
日誌會隨時間增長，手動計數每次執行都會浪費一次工具呼叫。
- 如果日誌不存在或其第一個事件距今少於 90 天，則將使用次數顯示為
—（未測量）。 切勿將其顯示為 0——未測量與未使用是兩種不同的事實。
一開始就說明掃描結果：掃描了哪些路徑、找到多少技能、以及使用次數是否可測量。
階段 2 — 評估（完全內聯、全面性）
讀取每個目標技能的內容，並在同時看到整個技能集的情況下逐一評估。檢查清單：
- 與其他技能的內容重疊（有文件的編排器/子技能拆分不算是重疊——例如 paper-ecosystem → 其檢閱者，citation-sync → release-doi/wikidata。區分 有意的分層與真正的重複）
- 與 MEMORY.md / CLAUDE.md / 規則的重疊
- 技術參考的新鮮度（如果 CLI 標誌 / API / 工具名稱看起來過時，請使用 WebSearch 確認）
- 使用頻率（當未測量時忽略此訊號）
評估是全面性的判斷，而非數字評分表。指導面向： 可操作性（可據以行動的具體範例/步驟）、範圍符合度（名稱、觸發條件與內容一致—— 不太寬也不太窄）、獨特性（無法被 MEMORY / 其他技能取代）、時效性（參考資料在目前 環境中可作用）。
聚合成本（技能集合層級，非每個技能）： 即使某個技能本身沒問題，保留它也不是 免費的。技能的好處是脆弱的——一個龐大、未經整理的技能庫會降低代理選擇正確技能的 能力，並將行為拉回沒有技能的基線。因此，保留的門檻會隨著技能庫規模而提高： 當技能集合很大時，一個僅僅尚可的技能（使用率低、獨特性低、與其他技能高度相鄰） 僅因聚合稀釋的緣故就成為淘汰/合併的候選對象——與技能本身的任何缺陷無關。 這是一個判斷輸入，而非配額；不要為了達到某個數字而淘汰技能。
| 評定 | 意義 |
|---|---|
| 保留 | 有用、符合時效、具有獨特價值 |
| 改善 | 值得保留，但需要特定的改進 |
| 更新 | 引用的技術已過時（使用 WebSearch 驗證） |
| 淘汰 | 品質低、過時、或成本不對稱 |
| 合併至 [X] | 與另一個技能有顯著重疊；指定目標技能名稱 |
零使用規則：當使用日誌的第一個事件距今至少 90 天，且某個技能的 use_90d == 0
時，必須將其標示為淘汰候選對象（最終決定權在用戶手中）。當日誌距今少於 90 天時，
此規則不會觸發，評定將回歸到全面的判斷。
評估是不分來源的：不要根據 ECC / 自編寫 / 自動提取進行分支。相同的檢查清單 適用於每個技能。
階段 3 — 摘要
產出一個表格：技能 | 7 天 | 90 天 | 評定 | 原因。
階段 4 — 彙整
- 淘汰 / 合併：針對每個檔案，呈現 (1) 發現的具體缺陷，(2) 什麼內容可以替代 相同需求（淘汰：哪個現有技能/規則；合併：目標技能以及要整合的內容），(3) 移除的 影響（依賴此技能的技能、MEMORY 中的引用）。僅在用戶確認後才執行。
- 改善 / 更新：主動提議交接——「將
<技能>交給 skill-creator 改善？」 ——並在獲得批准後，以目標技能為參數呼叫skill-creator。Stocktake 本身 從不執行改善工作。 - 更新記錄：讀取
results.json→ 合併本次執行的評定結果 → 寫回檔案 （evaluated_at= 使用date -u +%Y-%m-%dT%H:%M:%SZ取得的真實 UTC 時間）。 在changed模式下，保留您未重新評估之技能的先前評定結果。 - 如果 MEMORY.md 超過 100 行，建議壓縮。
原因品質（必要）
每個 reason 都必須是自足的——單獨就能做出決策。禁止僅使用「unchanged」；
始終重新陳述證據。
- 淘汰：說明缺陷 + 替代方案。錯誤：
"Superseded"/ 正確："disable-model-invocation: true 已設定；continuous-learning-v2 涵蓋相同模式並增加信心評分。已無任何獨特內容保留。" - 合併：指定目標技能 + 要整合的內容。錯誤：
"Overlaps with X"/ 正確："42 行精簡內容；chatlog-to-article 的步驟 4 已涵蓋此工作流程。將其中的 '文章角度' 提示整合為一則註解。" - 改善：哪個章節、什麼變更（如相關，包含目標大小）。錯誤：
"Too long"/ 正確："276 行；'Framework Comparison'（L80–140）與 ai-era-architecture-principles 重複。刪除該部分以達到約 150 行。" - 保留（在
changed模式中僅修改時間變更）：重新陳述原始理由。錯誤："Unchanged"/ 正確："內容未變更。由 rules/python/ 明確匯入的唯一 Python 參考；無重疊。"
results.json（精簡記錄）
{
"evaluated_at": "2026-06-24T11:09:00Z",
"skills": {
"<skill-name>": {
"path": "~/.claude/skills/<name>/SKILL.md",
"verdict": "Keep",
"reason": "...",
"mtime": "2026-01-15T08:30:00Z"
}
}
}
此記錄僅用於儲存評定歷史和上次稽核的時間戳記。使用 Read/Write 內聯更新， 而非腳本。僅包含全域技能（專案技能每次從 cwd 重新讀取，不在此快取中）。
相關技能
skill-creator— 改善引擎；將改善/更新工作交接給它。config-gc— 對技能存在性以及整個 ~/.claude（鉤子/權限/MCP/快取）進行垃圾回收；stocktake 則評定技能品質。harness-sync— 使用它將此技能同步到其公開儲存庫。- 使用次數計量：
~/.claude/hooks/log-skill-usage.sh→~/.claude/metrics/skill-usage.jsonl（獨立於 stocktake 的計量層）。