Quartz 5

Skills 規則

Properties2
description所有 Skill 的建立、修改、整併、封存規範與標準流程 + 知識沉澱架構
tagshermes, agent, workflow

10 min read

Skills 使用規範 (Skills Rules)

核心原則：新建技能前必須先檢視 Obsidian Vault 中的技能清單，優先使用現有技能進行調整與修改。

檢視流程：執行任務前先調用 skills-list 技能檢查現有技能，確定無適用技能時才考慮新建。

新增程序：新建技能前必須明確詢問使用者確認，並說明新建的必要性與現有技能的不足之處。

替代方案：優先考慮修改現有技能而非新建，可提供多種調整策略供使用者選擇。

記錄要求：所有技能操作都必須在 Obsidian Vault 中留下記錄，包括技能修改原因與效果評估。

⚡ Superpowers 流程（寫新 Skill 強制遵循）

順序不可逆，禁止跳步，每階段結束必須停止等用戶確認：

階段Skill必須做到🔴 絕對禁止
1brainstorming探索需求→提問→2-3方案→用戶批准設計未批准前寫任何 code
2writing-plansbite-sized TDD 任務，完整程式碼+驗證指令+預期結果TBD / placeholder / 「稍後實作」
3executing-plans逐 task RED→GREEN→REFACTOR跳步、跳過驗證
4writing-skillsTDD for docs + SDO（description 只寫觸發條件）沒測試就部署 skill
5verification跑指令→看輸出→才宣稱完成「應該可以」「看起來沒問題」
6finishing測試全過→commit/PR沒驗證就 commit

HARD GATE：brainstorming 用戶批准前，禁止任何實作行為（包含 scaffold、寫檔案、建目錄）。

SDO 標準：Skill description 只描述「何時使用」（觸發條件），不描述「做什麼」（流程摘要）。

Agent 表達範例 (Agent Expression Examples)

技能檢視表達：在執行任務前，我會先檢視 Obsidian Vault 中的現有技能清單，尋找最適用的技能進行調整。

新建詢問表達：經檢視現有技能後，若無適用技能，我會向您說明：「我已檢視現有技能，發現 [具體不足]，建議新建技能 [名稱] 來處理此任務，請問您是否同意？」

替代方案表達：「除了新建技能外，我也可以修改現有的 [技能名稱] 來滿足需求，您偏好哪種方式？」

記錄更新表達：「技能操作已完成，我已在 Obsidian Vault 中記錄了修改原因：[具體原因] 和效果評估：[具體評估]。」

Skill 知識沉澱架構

所有與 Hermes 技能（Skills）相關的報告、知識庫、作業過程、修正紀錄與執行結果，必須統一沉澱至： /root/Documents/Obsidian Vault/skills/

資料夾架構規範

每個 Skill 應建立對應的子資料夾，並遵循以下標準結構：

  • skills/<skill-name>/README.md: Skill 知識庫首頁（含維護記錄、SCHEMA→index→log 執行規範）。
  • skills/<skill-name>/scripts/: 關鍵作業腳本。
  • skills/<skill-name>/references/: 參考文件、來源列表、cron 規範。
  • skills/<skill-name>/templates/: 輸出格式範本。
  • skills/<skill-name>/log/: 每日執行結果與執行狀態紀錄（每執行完畢自動歸檔）。

維護原則

  • 一致性: 確保所有技能資訊皆歸檔於此處，不得散落在其他資料夾。
  • 透明度: 修正內容必須明確記錄時間與變更目的。
  • 可讀性: 嚴格執行 Traditional Chinese (繁體中文) 輸出，確保技術文件語意精準。

Skill 程式碼與檔案維運鐵律（Minimal Skill Architecture）

適用對象：所有 Skill 內的 scripts/、references/、templates/。目標是保持 Skill 最小化、避免腳本/文件碎屑累積。本節與上方「知識沉澱架構」互補——沉澱架構管「放哪」，本節管「什麼該留、什麼該刪」。

程式碼處理原則

  1. 優先修改現有程式：接到需求先找現有腳本改，不預設新建。
  2. 不建立新的 Python（除非必要）：一次性/臨時用途寫 /tmp，不進 Skill 目錄；能 patch 既有 .py 就不要新增檔。
  3. 若已有相同功能，直接修改：發現重複實作先合併，不疊新檔。
  4. 若需要重構，合併原有程式：重構 = 把舊邏輯併入 canonical，舊副本轉 redirect 薄包裝或直接刪除，不留孤本。

目錄內容守則

  1. references/ 僅保存長期可重用的參考：API 端點、欄位對照、ETF/覆蓋率算法、事故教訓等穩定知識。已合併/過時/與其他 Skill 逐字重複的 references 應刪除或遷併。
  2. scripts/ 僅保存正式執行腳本：每日 cron 實際呼叫、診斷工具等。實驗性、一次性、未接管的腳本不放這裡。
  3. 禁止產生 temp / copy / draft / v2 / new / fix 等檔名：任何 *_temp.py、*_copy.md、*_draft*、*_v2*、*_new*、*_fix* 視為違規碎屑，建立即清理。需要版本比較請走 git，不要複製檔案。

自動清理與最小化

  1. 任務完成後，自動清理無用程式：刪除過時 redirect 包裝、已廢棄舊腳本、stale 測試、死連結 references；同步修正引用它們的 SKILL.md / references。
  2. 保持 Skill 最小化（Minimal Skill Architecture）：
    • 一個功能只留一份 canonical 實作，其餘皆為引用或刪除。
    • 無 cron、無主動 invoke 的 Skill 視為候選廢除對象；其獨特知識應遷移至 canonical Skill 後整併。
    • 診斷/維運工具若長期無用，與其文檔一併清理，避免「無文檔孤兒腳本」。

Obsidian Vault 寫入權限鐵律（WebDAV 同步相容）

  1. 寫入 Vault 後必須設 WebDAV 相容權限：任何經 Agent write_file / patch 新建或修改的 Vault 檔案，chmod 後 group 仍可能是 root（Agent 預設 root:root），導致 nginx (www-data) 同步失敗（Permission denied / 403 / 500）。規範：
    • 檔案：chown root:www-data <path> + chmod 664 <path>
    • 父目錄：chown root:www-data <dir> + chmod 775 <dir>（目錄需 group 可寫才能 PUT/DELETE）
    • 驗證：sudo -u www-data touch <dir>/.t && sudo -u www-data rm <dir>/.t 不報 Permission denied 才算完成
    • 根因與完整診斷見 obsidian-lint 的 references/webdav-sync-diagnosis.md 與 Pitfall #37。
    • 預防：obsidian-lint.py 每次執行會自動 chmod 全庫為 664/775（見其「檔案權限修正」區塊），故寫入 Vault 後跑一次 obsidian-lint.py 即可消除權限地雷。本條補強的是 chown（lint 只做 chmod 不動 owner）——若新建檔是 root:root，需顯式 chown :www-data 才完整。

實務檢查清單（每次改完 Skill 跑一次）

  • 有無新增 *_temp/_copy/_draft/_v2/_new/_fix 檔？→ 有則刪
  • scripts/ 每個 .py 是否都被 cron 或診斷流程實際使用？→ 否則清理
  • references/ 每個檔是否指向現存內容？有無死連結或教已刪腳本？→ 修正
  • SKILL.md 的「需要」連結清單是否全部存在？→ 驗證
  • 重複邏輯是否合併到單一 canonical？→ 是則刪舊本
  • 若有寫入 Obsidian Vault：新建/修改檔是否 chown root:www-data + chmod 664、父目錄 775？→ 或已跑 obsidian-lint.py 自動修正

錯誤隔離與超時處理機制 (Evolutionary Error Handling & Resilience)

  1. 並發優化 (Concurrency): 所有外部請求應採用 concurrent.futures.ThreadPoolExecutor 進行並發處理，單一節點逾時不影響整體執行。
  2. 限時交付 (Deadlines): 嚴格執行 180s 軟超時。當 120s 時，系統自動停止新任務派發，將已完成的 Future 結果立即輸出，確保任務不出現 [SILENT]。
  3. 優雅降級 (Graceful Degradation): 抓取量級採取「分層動態適應」：
    • 第一層：關鍵資訊抓取 (限時 60s，必保)
    • 第二層：補充資訊抓取 (非同步並發，逾時自動丟棄)
    • 第三層：冗餘資訊清除 (最後階段處理)
  4. 錯誤日誌記錄: 任何失敗的 web_extract 需記錄至 evolution_log.md 以進行 GEPA 演化優化。
  5. 交付條件:
    • 若任務中止但已有部分資料，請將現有成果整理輸出。
    • 若任務因完全無資料或超時導致無結果，則回傳 [SILENT]。
  6. 異常紀錄: 所有執行超時或請求錯誤，必須在 skills/<skill-name>/log/ 的當日紀錄檔中留下時間戳與錯誤代碼。

相關節點

Graph View

Backlinks