Skills 憲法（Skills Constitution）
一句話定位：凌駕於全部技能/工具/插件之上的元規則。所有能力調用必須先過這一關。
v2.25.0（目前） — 第五條「答覆推薦」極度省 token 改造：推薦來源從"每次全盤搜 GitHub"改為讀本地排行榜快照（
data/skill_rankings.json+scripts/recommend_skills.py—— 零網路、約 20KB、純確定性規則匹配 + 自動排除已裝）；新增scripts/update_skill_rankings.py低頻抓取權威排行榜（quemsah/awesome-claude-plugins，索引 3.6 萬+ 倉庫）重建快照，過期（>30 天）只提示不自動拉取；step5 新增推薦來源標註軟校驗（標註"本地排行榜快照"=省 token 最佳實踐）。 v2.24.0 — 隱形技能治理 + 門禁「一次三查全程放行」+ 輕量索引。實測修復五項： ①parse_frontmatter支援 YAML 塊標量（>/|及摺疊變體）——舊版把 ponytail 全套等 137 個技能的 description 解析成單個>字元，檢索永遠命中不到（典型：使用者裝了 GitHub 116k★ 的 ponytail 卻從未被調用）； ② 索引描述上限 200→2000——觸發詞（如 ponytail 的 lazy mode，位於第 400+ 字元）不再被截斷丟棄； ③ 門禁任務級通行證——任務開始時三查通過（平台注入或 step1 PASS）即全程放行，攔截前移為任務開始時的一次性提醒（使用者明確要求：任務開始已三查，中途不得再攔）； ④ 新增scripts/skill_doctor.py：隱形/損壞技能自動診斷（8 類檢查）+--fix自動修復 +--quarantine隔離損壞 +--emit-min-index輕量索引（約完整索引 20% 體積，截斷部分保留長尾觸發詞，冷門技能省 token 仍可命中）； ⑤ 圖譜錨點抽取固定用前 200 字元 + 停用詞三批擴容 + DF 上限 0.05→0.035——描述放寬後錨點暴增曾產生 752 節點巨簇，現恢復 ≤80 紀律（回歸測試 106/106）。 v2.23.0 — 技能圖譜（借鑑 GitNexus 預計算關係智能）：技能樹之上疊加確定性關係圖（skill_graph.json，隨技能樹重建自動產出）。三種邊全部零依賴確定性抽取——chains_to（registry 的輸出→輸入 schema 交集）/co_anchor（共享實體錨點，含停用詞與文件頻率過濾）/alternative（同分類高重疊替代方案）；確定性標籤傳播聚成功能簇。三處落地：① 注入塊從"整分類清單"收窄到"錨點技能的任務線圖譜"（帶"為什麼相關"溯源，更省 token）；② 門禁 step3 新增 Layer F 圖證據校驗——引用的技能必須與任務錨點圖譜連通，零連通帶簇證據判 FAIL；③ 替代邊不做放行憑證、不參與聚簇（紀律同 GitNexus 只對結構邊做社區檢測）。圖缺失時全部鏈路行為與舊版一致（只加不刪）。完整版本史見
CHANGELOG.md。
⚠️ 前置過濾：任務類型判斷（零號條款）
本憲法僅適用於"專業任務"，不適用於簡單問答。執行前先判斷：
| 任務類型 | 特徵 | 是否查技能 |
|---|---|---|
| 簡單問答 | 翻譯、潤色、解釋概念、一般知識問答 | ❌ 跳過 |
| 專業任務 | 編碼、資料抓取、檔案操作、API 調用、複雜分析 | ✅ 必須查 |
| 模糊任務 | 不確定是否需要專業工具 | ✅ 查一下（寧可不放過） |
判斷標準：
- 任務涉及檔案系統、網路請求、程式碼執行、專業工具 → 專業任務
- 任務只是文字處理、知識問答、簡單解釋 → 簡單任務
自我豁免：本憲法本身是元規則，執行憲法條款時不需要再次查技能（防止死循環）。
誤判回退（零號條款-C）：若 Agent 誤判任務類型（如把專業任務當作簡單問答跳過），使用者有權指出（"這是專業任務，你應該查技能"）。此時 Agent 必須：
- 道歉並承認誤判
- 立即回退到完整憲法流程（從查記憶開始）
- 將此次誤判記錄到記憶層（
MISJUDGMENTS），避免重複犯錯
痛點
Agent 生態最大浪費：裝了一堆 Skill 卻傻傻硬扛任務，或憑印象亂選、誤判能力、從不去搜。本憲法把"查能力→匹配→必用→搜索→推薦"變成強制流程，並用門禁（constitution-check）把"靠自覺"變成"可校驗、可攔截"。
核心概念（平台無關）
本憲法使用以下通用術語，各平台的具體對應物見【平台映射表】：
| 通用術語 | 含義 | 各平台叫法舉例 |
|---|---|---|
| 能力註冊表 | Agent 目前可用的全部技能/工具/插件清單 | available_skills / tools / plugins / extensions / Gems / MCP servers |
| 技能描述 | 每個能力的觸發條件說明 | description / trigger / when_to_use / system prompt |
| 技能索引 | 按功能分類的技能樹（預生成，加速匹配）。⚠️ 倉庫內 skill_tree.json 為作者快照/範例，使用者應運行 scripts/build_skill_tree.py 生成自己的索引 | skill_tree.json（作者快照）/ 你生成的技能樹 |
| 技能發現 | 搜索可安裝的新能力 | find-skills / GPT Store / SkillHub / MCP Registry / Extensions |
| 記憶層 | 跨會話持久化的規則儲存 | MEMORY.md / CLAUDE.md / AGENTS.md / Custom Instructions / .cursorrules |
| 技能檔案 | 定義能力的結構化文件 | SKILL.md / GPT Actions / MCP Config / Gem Instructions |
憲法條款
第零條：查記憶（Pre-Check Memory）
在執行任何任務前，必須先查閱該平台的記憶/規則層，確認有無相關約定、歷史上下文或待辦事項。
各平台記憶層路徑：
| 平台 | 記憶層路徑 |
|---|---|
| WorkBuddy | ~/.workbuddy/MEMORY.md + 項目 .workbuddy/memory/ |
| Claude Code | CLAUDE.md 或 .claude/CLAUDE.md |
| Cursor | .cursorrules + .cursor/rules/ |
| Windsurf | .windsurfrules |
| Cline | .clinerules |
| ChatGPT | Custom Instructions |
| Gemini | Gem Instructions |
| Codex | AGENTS.md |
| 通用規則 | 項目根目錄 RULES.md 或 .agent/rules.md |
查記憶順序：
- 使用者級記憶（長期偏好、硬規則）
- 項目記憶（目前項目約定、歷史決策）
- 今日流水（當天工作記錄，避免重複）
記憶層必備內容（自舉前提：讓"查記憶"真正發現技能，v2.3.0 新增）：
為了讓憲法自舉執行，記憶層中應維護以下兩類條目：
| 條目 | 內容 | 範例 |
|---|---|---|
INSTALLED_SKILLS | 已安裝技能清單（名稱 + 一句話描述） | file-ops：文件讀取/寫入工具，用於讀取技能索引 |
SKILL_INDEX_PATH | 技能索引檔案路徑（你的技能樹，非作者快照） | <你的平台技能目錄>/skill_tree.json（如 ~/.claude/skills/） |
範例：
INSTALLED_SKILLS:
- file-ops：文件讀取/寫入工具，用於讀取技能索引
- find-skills：技能搜索工具，用於發現新能力
- agent-memory：記憶管理系統
SKILL_INDEX_PATH: <你的技能目錄>/skill_tree.json
只要按此格式維護記憶層，Agent 查記憶即可"回憶"出技能清單，無需即時掃描，冷啟動問題就此解決。
第一條：先查（Pre-Check）
每次執行專業任務前，必須先查看能力註冊表，判斷有沒有能力與目前任務相關。
優化路徑（v2.2.0 新增；v2.7.0 修正指向）：
- 先查你的平台能力註冊表（可用技能/工具/插件清單，如 Claude Code
~/.claude/skills、Cursor.cursor/rules、WorkBuddy available_skills）；有本地技能樹則優先用它（運行scripts/build_skill_tree.py生成你自己的索引） - 按任務類型定位功能分支
- 在分支內匹配描述
- 未命中則全量掃描（兜底）
執行強化（v2.5.0 新增，無條件第一步；v2.11.0 強制命中清單）：
「先查技能索引」必須是無條件動作，不是"我覺得需要才查"：
- 任何專業任務（含"查安裝/查庫"類，如確認某 Python 庫是否安裝）第一步必須讀技能樹索引，禁止以"這不需要查技能"為由跳過——憑判斷跳過正是本憲法要防的行為（教訓：實際運行中查 cognee 時跳過技能樹被使用者抓包）
- 技能樹索引應包含技能（獨立 + 插件，v2.21.0）與已裝 Python 庫/工具（🧩 分類），一個入口查全
- 任務開始需顯式彙報「憲法三查」結果，讓流程可見、可被使用者監督。v2.11.0 強制：②技能樹必須列出命中的技能名清單（名稱+依據），禁止只寫"已讀技能樹"：
【憲法三查】 ① 記憶 ✅ 已查（使用者級/項目/今日流水） ② 技能樹 ✅ 已讀（命中技能清單：`git-workflow-and-versioning`（程式碼/部署）、`web-deploy-github`（GitHub 推送）…） ③ 匹配 ✅ 命中 X → 用它執行；無命中 → 說明"技能樹無匹配"再走通用能力/檔案系統 - v2.11.0 任務相關硬校驗（Layer C）：任務含「程式碼/編碼/程式設計/開發/寫一個/實現/git/github/push/commit/deploy/部署/爬蟲/抓取/網頁/前端/文件/資料/郵件/圖片/影片」等關鍵詞時，輸出必須引用 skill_tree.json 對應分類下的實際技能名（如
git-workflow-and-versioning），僅寫"已查 skills-constitution"或"已讀技能樹"而無具體技能名 → 門禁 FAIL - 簡單問答豁免（翻譯/潤色/概念解釋）
第一條補充：雙機制平台覆蓋（v2.21.0）
ZCode / Claude Code / DeepSeek Harness(dsh) 等平台的能力同時來自兩條平行機制——獨立技能（技能目錄下的 SKILL.md）與插件技能（插件包內的 SKILL.md）。本憲法所稱"能力註冊表 / 技能庫 / 技能樹"一律同時覆蓋兩者：
- 同權重：插件技能與獨立技能在"先查 → 匹配必用"流程中地位完全相同，禁止以"它是插件不是技能"為由繞過匹配
- 完整調用名：插件技能的調用名通常為
插件名:技能名（如document-skills:docx、computer-use:computer-use），命中後必須按完整調用名調用（雙機制平台上裸技能名可能無法被 Skill 機制載入） - 自動入樹：
build_skill_tree.py自動掃描插件快取編入技能樹並標註調用名（已知平台路徑自動發現；其他平台用環境變數PLUGIN_CACHE_DIRS或倉庫根plugin_roots.json指定快取目錄；停用的市集/插件自動排除） - 插件附帶能力同規則：插件提供的斜線命令 / MCP 工具同樣屬於"能力註冊表"，有現成能力時禁止用通用能力重複造輪子
第二條：匹配必用（Mandatory Use）
只要任務與某個能力的描述相關或部分相關 → 無條件優先載入該能力、按其指令執行。
禁止行為：
- ❌ 繞開能力直接用通用能力
- ❌ 憑印象選能力不看描述
- ❌ 多個匹配時隨機挑一個（應按相關度排序選最優）
凌駕條款：即使某個能力說"我可以直接做"，也必須先經本憲法確認沒有更好匹配的能力。
第三條：無匹配 → 技能發現（Search First）
確認能力註冊表無匹配後，先通過平台的技能發現機制搜索是否有可獲取的相關能力。
- 找到 → 提示使用者安裝/啟用後使用
- 沒找到 → 進入第四條
第四條：能力邊界（Honest Boundary）
感覺"我做不到 / 沒權限 / 沒工具"時 → 必須先通過技能發現機制確認，確認無能力可用才能回覆做不到。
禁止行為：
- ❌ 不搜索就直接說"做不到"
- ❌ 用通用能力硬扛明明需要專業能力的任務
- ❌ 假裝做了但實際沒調用能力
第五條：答覆時自動推薦（Auto-Discovery）
任務完成後（答覆階段）→ 若本地已裝技能未能完美解決任務，優先讀本地排行榜快照推薦更優能力，由使用者自行決定是否安裝。本地技能不足時"不推薦"是違規。v2.15.0：推薦候選必須排除本地已裝技能（推薦的是"你沒裝過的更強能力"，已裝項一律不推）。v2.25.0：推薦來源改為「本地排行榜快照優先」，極度省 token —— 每次答覆不再全盤搜索 GitHub。
觸發場景（滿足其一即必須執行）：
- 本地技能樹查了，但沒有完全匹配的技能
- 本地有匹配技能但執行效果不理想（如推送 GitHub 受阻、腳本報錯）
- 任務明顯超出本地技能範圍（如需要專用工具/agent/插件）
推薦來源（v2.25.0 優先順序）：
- 本地排行榜快照（第一優先，零網路、零搜索）：讀
data/skill_rankings.json（倉庫自帶作者快照），跑python scripts/recommend_skills.py --task "<任務>"—— 純本地匹配關鍵詞 + 按星數排序 + 自動排除本地已裝技能，輸出 3 條（每條含 GitHub 連結 + star 數 + 獲取方式，天然滿足 step5 校驗）。 - GitHub 搜索（僅快照無匹配時兜底）：快照條目與任務零相關時，才用 WebSearch/WebFetch 搜
github.com高 Star 倉庫，並在推薦區塊標註"來源: GitHub 搜索"。 - 快照過期處理：快照超過
stale_days（預設 30 天）未更新，推薦時頂部提示運行python scripts/update_skill_rankings.py重新整理 —— 只提示不自動拉取（省 token）。
推薦格式：
🔍 本次相關技能推薦（來源: 本地排行榜快照 data/skill_rankings.json, 更新於 2026-09-01）:
- 名稱：xxx — 一句話亮點 + GitHub 連結 + Star 數 + 獲取方式（是否要安裝由你決定）
（最多 3 個，避免洗版）
執行細則（v2.6.0 強化；v2.11.0 修正定位；v2.15.0 排除已裝；v2.25.0 快照優先）：
- 推薦核心：必須是 GitHub 高 Star 數 skill/tool/agent 倉庫（含 star 數 + 連結 + 獲取方式）——這是使用者決定是否安裝的依據；資料來源優先本地排行榜快照（
recommend_skills.py輸出），其次 GitHub 搜索 - 省 token 鐵律（v2.25.0）：推薦環節預設零網路——只讀本地
data/skill_rankings.json（約 20KB）跑確定性規則匹配；只有快照缺失或任務與快照零相關時，才允許發起 GitHub 搜索 - 快照重新整理（低頻）：
python scripts/update_skill_rankings.py從權威排行榜倉庫（quemsah/awesome-claude-plugins 等）抓取 Top100 重建快照；建議每次釋出會/每週跑一次，平時不跑 - 允許在推薦前簡要說明"本地已查過哪些技能、為何不足"（如"本地已裝
git-workflow-and-versioning但網路受阻"），幫助使用者理解為什麼需要新技能 - 禁止以"本地已裝技能清單"替代推薦（本地技能僅作背景說明）
- v2.15.0 排除已裝（硬性動作）：推薦前必須先核對本地已裝清單（如
ls ~/.workbuddy/skills/），候選倉庫若與本地已裝技能同名/同源，一律不推——包括"搜索結果恰好命中已裝倉庫"的情況（如 addyosmani/agent-skills 已裝時不得再推薦）。recommend_skills.py已內建該排除（含_<name>-references框架標記）；GitHub 搜索路徑同樣必須人工核對。僅可作背景說明（"本地已有 X，若需更強可看 Y"）。 - 可配合門禁
constitution-check --step 5自動校驗推薦區塊是否合規（含github.com/owner/repo連結 + star 數標記 + 獲取方式 + v2.15.0 Layer E 本地已裝排除校驗 + v2.25.0 推薦來源標註：標註"本地排行榜快照"為省 token 最佳實踐）
執行閉環（五步）
任務 → ①判類型（簡單問答豁免；專業任務必查）→ ②查記憶 → ③查技能樹（按分支定位）→ ④匹配必用/無匹配必搜 → ⑤答覆時推薦（排除已裝）。
技能樹（Skill Tree）
按功能分類，執行時按分支定位，減少掃描範圍 80%+：
技能樹/
├── 📜 元規則類（憲法/安全稽核）
├── 🧠 記憶/知識管理類（個人記憶/項目知識圖譜/會話持久化）
├── 🌐 網路/搜索類（網頁自動化/資料抓取/API/搜索）
├── 💻 開發/編碼類（程式碼生成/審查/測試/建構部署）
├── 📄 文件處理類（PDF/Word/Excel/PPT/格式轉換）
├── 🖼️ 內容生成類（圖像/影片/UI 設計）
├── 💰 業務專用類（金融/法律/電商行銷）
└── 🔧 通用工具類（檔案操作/程序管理/環境配置）
完整索引：skill_tree.json 為作者快照（範例）；使用者安裝後必須重建自己的技能樹（完整命令/平台差異/自檢見 → Load reference/skill-tree-guide.md）。精選技能：registry.json。
技能圖譜（v2.23.0）：樹是"行政區劃"（人為分類），圖譜是"自然聚落"（關係驅動）。build_skill_tree.py 重建技能樹時自動產出 skill_graph.json（也可單獨跑 scripts/build_skill_graph.py 從現有樹重建）：節點=技能，邊= chains_to（輸出→輸入 schema 銜接）/ co_anchor（共享實體錨點）/ alternative（替代方案），確定性標籤傳播聚成功能簇（如"程式碼釋出"簇 = git 工作流 + 審查 + 部署）。用途：注入按任務線收窄、門禁 Layer F 圖證據、推薦時說明技能間關係。
快速注入模板
以下模板可直接複製到各平台的規則/指令/記憶層中：
## Skills 憲法（Skills Constitution）v2.25.0
本規則優先級高於全部技能/工具/插件。任何能力調用必須先過這一關。
執行路徑：
1. 先查記憶：查閱平台記憶層（MEMORY.md/CLAUDE.md 等）確認相關規則
2. 先查技能：查看技能索引，按任務類型定位功能分支，**輸出必須列出命中的技能名清單**
（技能索引含獨立技能與插件技能（v2.21.0）：命中插件技能按其完整調用名 `插件名:技能名` 調用）
3. 匹配必用：有匹配則無條件優先使用該能力
4. 無匹配必搜：先搜索可獲取的能力，再考慮通用能力
5. 能力邊界：說"做不到"前必須先搜索確認無能力可用
6. 答覆推薦（v2.25.0 快照優先，極度省 token）：本地技能未能完美解決任務時，**優先讀本地排行榜快照** `python scripts/recommend_skills.py --task "<任務>"`（零網路、自動排除已裝、出 3 條含連結+star+獲取方式）；快照無匹配時才去 GitHub 搜索；快照過期（>30 天）跑 `python scripts/update_skill_rankings.py` 重新整理；**v2.15.0 推薦候選必須排除本地已裝技能（先核對本地已裝清單，已裝項一律不推）**
違規判定：跳過查記憶/技能清單直接幹 / 有匹配但不用 / 未搜索就拒絕 / 查技能樹但未列出命中技能名（空頭彙報）/ 本地技能不足卻不去推薦（快照優先） / **推薦了本地已裝技能（v2.15.0，Layer E 校驗 FAIL）** / **命中插件技能卻以"它是插件"為由繞過（v2.21.0）**
配套要求
對能力作者：description 是唯一匹配依據，寫準觸發條件（何時用我），遵循平台格式，分類準確。 對框架開發者：會話啟動注入憲法；能力註冊表任務前可訪問；支援預生成技能索引（skill_tree.json）加速匹配。
與其他規則的關係
優先級從高到低：
1. 🔴 系統安全規則（不可違反）
2. 📜 Skills 憲法（本規則）—— 凌駕於全部技能/工具/插件之上
3. 🔧 具體能力的執行指令
4. 🤖 Agent 通用能力
違規判定
以下行為屬於嚴重違規，使用者有權要求重做並說明理由：
| 違規行為 | 判定標準 |
|---|---|
| 跳過查記憶直接幹 | 任務完成但未查閱平台記憶層 |
| 跳過查技能清單直接幹 | 任務完成但未載入任何相關能力 |
| 有匹配但不用 | 能力註冊表中有匹配能力但未載入 |
| 空頭查技能（v2.11.0） | 只寫"已讀技能樹/已查憲法"但未列出命中的具體技能名，且任務含程式碼/git/部署等關鍵詞 |
| 查錯分支（v2.11.0） | 任務要求編碼/推送，卻引用無關分類技能（如文件類） |
| 未搜索就拒絕 | 說"做不到"但未通過技能發現機制確認 |
| 無復盤推薦（v2.11.0；v2.25.0 快照優先） | 本地技能未能完美解決任務，卻未做推薦（優先讀本地排行榜快照 recommend_skills.py） |
技術邊界說明
"無條件啟用全部能力"不可行（撐爆上下文）。正確設計是按描述匹配觸發，本憲法強制該匹配機制不被跳過。技能樹索引將全量掃描縮小到目標分支（省 80%+ token）；索引由 build_skill_tree.py 生成，禁止手寫（v2.17.0：使用者應在本機運行 SKILLS_DIR=<技能目錄> python scripts/build_skill_tree.py 生成自己的樹，替換作者快照）。
門禁證據鏈（v2.22.0）：門禁（constitution-gate）認兩種"三查已完成"證據，滿足其一即放行寫操作、收尾不重複校驗：① 本任務內 constitution-check --step 1 真實校驗通過（手動路徑）；② 平台已注入記憶+技能樹（注入上下文 ready）且本任務內實際調用過命中技能（Skill 調用由門禁自動記錄）。同任務內的追加式訊息不重置證據；門禁自身的狀態/豁免/違規檔案禁止被 Agent 篡改（篡改即攔截）。
插件技能掃描（v2.21.0）：雙機制平台（ZCode / Claude Code / DeepSeek Harness 等）上，技能樹同時編入插件快取裡的插件技能——已知平台路徑自動發現（ZCode 會進一步按其 config 的插件啟用表排除停用項）；其他平台用 PLUGIN_CACHE_DIRS 環境變數（多個目錄用系統路徑分隔符）或倉庫根 plugin_roots.json（{"cache_dirs": ["..."]}）指定快取目錄；PLUGIN_SCAN=0 可整體關閉。插件條目帶 qualified_name（完整調用名）欄位，pre-hook 注入時自動標註。
可選增強（預設未啟用）：scripts/semantic_index.py 向量語義檢索需 pip install sentence-transformers faiss-cpu（約 90MB）並 python scripts/semantic_index.py build 建構索引；SAD 寬鬆語義檢索（零依賴）已覆蓋日常檢索，不啟用不影響任何主鏈路功能。
參考文件（按需載入）
- 跨平台適配 / 平台映射表 → Load
reference/platform-mapping.md - 安裝 / 鉤子註冊 / 驗證 → Load
reference/installation.md - 門禁校驗機制（constitution-check 用法 / hooks / 設計要點）→ Load
reference/gate-details.md - 使用者建技能樹指南（完整命令 / 平台差異 / 自檢 / FAQ）→ Load
reference/skill-tree-guide.md
以上為漸進式揭露：主檔案只含核心條款，細節按需載入，控制 token。
貢獻指南
歡迎提交 Issue 和 PR：
- 功能增強：擴充分類規則、增加平台映射
- 文件優化：修正表述、增加範例
- Bug 修復：分類邏輯、腳本錯誤
License
MIT License — 隨意使用、修改、分發。
作者
jiabaobei — GitHub
如果這個規則幫你解決了 Agent 不調用能力的問題，歡迎 ⭐ Star 收藏！