manage-project-skills — 專案技能選擇與審計
0. 規則層級（優先閱讀）
- 授權（最高，無例外）：未經使用者明確許可，不得安裝/更新/移除技能，也不得寫入專案檔案；已批准的 ledger 寫入是唯一例外。批准必須包含：特定技能 + 來源 + 範圍；"管理我的技能" 未授權任何個別動作。
- 流程：遵循所選模式（T0/T1/T2/審計）；「禁止」步驟不得因效率原因跳過。
- 指導原則：本地優先、克制——若有偏離須說明理由。
核心：缺少的比錯誤安裝的好 —— 撤回約耗 1 分鐘；錯誤安裝則會永久佔用上下文並引發觸發器競爭。克制、強制說明理由、本地優先。
1. 模式
需求不明確 ⇒ 完整需求無法得知 ⇒ 啟動時不得大量安裝。
- T0 · 啟動庫存（唯讀）：執行步驟 1-2 + 對話報告（"已涵蓋 / 正在安裝"）。零安裝/寫入；ledger 初始化 = 需另外批准的寫入。覆蓋矩陣僅包含從專案堆疊可推斷的需求。快速路徑：ledger 存在且未討論技能 ⇒ 僅讀取 ledger。需要重新盤點的情況：技能目錄 / AGENTS.md / lockfile / agent 變更 ∥ ledger ≠ 磁碟 ∥ 使用者要求。
- T1 · 缺口驅動（任務進行中）：先分類。一次性答案（API 細節、單一命令）⇒ 查詢，不安裝。可重複使用（此儲存庫會再次遇到的工作流程/標準/工具鏈）⇒ 拉取一個技能 ⇒ 記錄。由 AGENTS.md 規則（請見 MAINTENANCE.md）決定，而非模型自我評估。
- T2 · 計畫確定後：批次安裝，每個候選技能須以已確認的計畫為理由。完整執行步驟 1-7。
- 審計：使用者要求審查/修剪/清理 ⇒ 請參閱末尾。
所有模式共享專案 ledger .agents/skills-rationale.md（若已批准）；請先讀取它。
2. 流程
1. 剖析專案
讀取（若存在，不猜測）：清單（package.json / pyproject.toml / go.mod / Cargo.toml / *.csproj）；佈局 + monorepo 信號（workspaces、turbo.json）；基礎架構（.github/workflows、Dockerfile、vercel.json、wrangler.toml）；README 開頭、docs/agents/。
2. 庫存覆蓋（本地優先；拉取前先去重）
順序：專案安裝 → 全域 → 註冊表。兩種分類：
- 個人技能：全域、跨專案。不要在專案中重複安裝；記錄目標 agent。全域存在不等於宣告為專案依賴。
- 專案關鍵技能：工作流程/交付依賴於它。記錄來源 + 版本/提交 + 還原路徑 —— 即使已全域安裝；新機器不會繼承全域技能。
掃描：專案目錄（.agents/skills、.opencode/skills、.claude/skills = 常見範例，請依 agent 文件確認；無法存取 ⇒ "未檢查"，絕不報告 "無技能"）；透過 npx skills ls -g 掃描全域；掃描來源清單與 skills-lock.json（若存在則同步）。
輸出：覆蓋矩陣（需求 → 由誰滿足 / 缺口）。
3. 從可靠來源填補缺口
信任層級：供應商官方（anthropics/skills、openai/skills、supabase/agent-skills）> 原始作者（mattpocock/skills、cursor/plugins）> 社群 > 不可驗證（提高審查標準）。否則使用 npx skills find <kw> —— 安裝次數僅供參考，非信任指標。無符合項 ⇒ 說明情況並建議使用 skill-creator；不接受近似 hack。
4. 預算：無硬上限，需求驅動
- 每個候選技能需要一個具體理由（"專案有 X ⇒ 需要 Y"）；無理由 ⇒ 放棄。
- 超過 ~10 個候選 = 分析錯誤 ⇒ 重新審計步驟 1-2。
- 邊際效益低 ⇒ 放入「延遲」清單（撤回成本低）。
- 去重 ≠ 自動修剪：描述重疊 ⇒ 候選群組 ⇒ 比較觸發器/IO/副作用/依賴/版本 ⇒ 僅在有替代證據且使用者批准時合併/移除；否則保留兩者，標記為「待比較」。
5. 安全關卡：安裝前，需使用者批准
審查整個套件，不僅是 SKILL.md：
- 完整閱讀 SKILL.md 以及所有引用的檔案/腳本/配置/依賴；對每個腳本檢查：執行 / 網路 / 寫入 / 憑證。
- 記錄掃描證據：掃描器 + 判決 + 匹配版本 + 日期。未掃描 = 未知，非安全。掃描器結果不一致 ⇒ 列出，不取平均值。
- 無掃描的私有來源 ⇒ 手動完整檔案審查取代關卡，標記為 "未掃描"。
- 中高風險或無法解釋的行為 ⇒ 由使用者決定；情況不明確前不得安裝任何技能。
6. 安裝
# 自動偵測 agent（向使用者報告偵測結果）；多 agent 機器：傳遞 --agent
npx skills add <owner/repo>@<skill> --copy -y
- 通道 2——版本鎖定 / npm 無法存取的備用方案：
gh skill install <owner/repo> <skill[@version]> --agent opencode（預覽版；複製檔案，不更新 skills-lock ⇒ ledger 記錄來源+版本；務必傳遞 --agent——非互動模式預設為 github-copilot）。每個技能一個通道——不要混用。 --copy= 快照隔離，非版本鎖定：無法上游同步，無版本標識，重新安裝會變更。可重現性 ⇒ ledger 記錄：來源 + 路徑 + 版本/提交（+雜湊值）。- 專案關鍵工作流程技能：使用
--copy，絕不使用符號連結（符號連結會追蹤上游）。 - 會產生
skills-lock.json⇒ 提交（還原：npx skills experimental_install）；確保.agents/未被 gitignore。 - 效果因 agent 而異：OpenCode 可熱載入（已驗證）；其他 agent 可能需要重新啟動 ⇒ 提示使用者重新啟動並重新驗證。
- GitHub 無法存取 ⇒ 報告並建議使用本地快取；絕不靜默跳過。
7. 驗證與記錄（四層；缺少任一一層 = "未驗證"）
- 檔案：存在、路徑正確、參考完整
- 清單：
npx skills ls與 lockfile 及磁碟一致（可見 ≠ 可載入） - 載入：目標 agent 確實載入了該技能
- 行為：一個代表性的正向任務可正常工作
- 將決策（內容/原因/延遲/驗證對象）寫入 →
.agents/skills-rationale.md - 移除：優先使用
npx skills remove <name> -y（參數請見npx skills --help）；絕不單純刪除目錄（會導致 lockfile 不同步）；刪除前記錄來源+版本；若無法恢復則備份並詢問；刪除後重新檢查四層驗證。
3. 審計模式
包含此技能本身。報告 → 使用者批准 → 執行。檢查項目：
- 重複：將描述分群 ⇒ 候選群組 ⇒ 比較觸發器/IO/副作用/依賴/版本；有替代證據且使用者批准 ⇒ 合併/移除；否則保留兩者（待比較）。絕不因相似性而刪除。
- 衝突：相同場景下的矛盾 ⇒ 記錄引文 + 範圍 ⇒ 由使用者裁決。
- 臃腫：無使用量遙測——"從未觸發" 由使用者提供。可衡量：描述與功能的膨脹程度、與更高頻率技能的重疊。降級 ⇒ 記錄狀態還原路徑。
- 失效參考：必要輸入（缺少 = 阻塞）/ 可選依賴（不存在 = 跳過）/ 預期輸出（執行時建立；不存在 ≠ 錯誤）。失效參考 ⇔ 必要輸入缺失且無法恢復。
報告：證據 → 建議 → 影響 → 授權。刪除前：確認可恢復性（
npx skills find）；不可恢復 ⇒ 備份並詢問。結論 → 寫入 ledger。
4. 維護與強制執行
AGENTS.md 規則範本、觸發器失敗診斷迴圈、15 種情境測試集、發布流程 → MAINTENANCE.md —— 編輯此技能前/後執行。