plugin-dev

1. 使命

此元技能確保 AI 生態系統的完整技術治理：設計、建立並持續優化共享的技能 (.agents/skills/)、黃金規則與永久指令 (.agents/rules/)，以及套件的持續知識累積檔案 ([套件名稱]_IA_CONTEXT.md)。

不可違背的基本原則：

• 單一事實來源 (SSOT)： 所有規則、規格或指令只能存在於一個權威位置。嚴格禁止將指令複製到多個檔案中。
• 不重複原則 (DRY)： 絕不重寫或複製任何現有指令。技能或文件應透過引用或連結來利用現有規則。
• 系統性地套用 Anthropic 參考模式 (feature-dev、claude-code-setup、pr-review-toolkit)，確保規則之間不互相矛盾，記錄新的工作流程，並將反饋整理為 YAML 格式的 incident 記錄。

2. 觸發條件與限制

• 何時啟用：
  • 對話結束 / 工作階段回顧： 由 /plugin-dev 呼叫，針對當前處理的套件提出 [套件名稱]_IA_CONTEXT.md 檔案及相關技能的豐富計畫，記錄工作階段中學到的發現、陷阱和機制。
  • 要求建立新技能時（例如：「建立一個管理自動化測試的技能」、「新增一個設計架構的技能」）。
  • 根據經驗回饋優化或修正現有技能時（例如：「修改 feature-dev 技能以禁止 X」）。
  • 建立、更新或審計行為規則時（例如：「新增一條規則來顯示已使用的技能」、「修改 critical-rules.md 中關於遷移的關鍵規則」）。
  • 記錄新的工作流程。
  • 審計技能合規性、指令一致性、消除重複 (DRY/SSOT) 以及 SemVer 控制。
• 何時不應啟用：
  • 撰寫或簡化教學文件 ➔ 使用 tutorial-writer。
  • 開發 Jekyll 元件或樣式 ➔ 使用 dev-jekyll。
  • 同步共享技術基礎 (Core Theme) ➔ 使用 sync-theme。
  • 代理初始化或專案診斷 ➔ 使用 project-setup。

3. 輸入與需載入的資源

• 優先順序 1： .agents/skills/plugin-dev/resources/anthropic-skill-patterns.md (封裝的 Anthropic 官方模式)。
• 優先順序 2： 規則檔案：
  • .agents/rules/critical-rules.md (不可變的關鍵規則)。
  • .agents/rules/*.md (執行與風格指令)。
• 優先順序 3： .agents/templates/generic-skill.md (10 個章節的範本) 與 .agents/templates/workflow-blueprint.md (流程模型)。
• 優先順序 4： 全域中心的 catalog.yaml 與 CHANGELOG.md 註冊表。

4. 約束與不可違背的規則

• SSOT (單一事實來源) 與 DRY 核心原則：
  • 任何慣例、指令或規格只能存在於一個位置。
  • 行為規則位於 .agents/rules/[名稱].md。技能絕不應複製這些規則的文字，而應直接引用它們。
• 套件上下文檔案的標準格式：
  • 套件上下文檔案必須命名為 modules/[套件名稱]/[套件名稱]_IA_CONTEXT.md (例如：PkgTaskExecution_IA_CONTEXT.md)。
• .agents/references/ 的嚴格最小化 (單一技能封裝)：
  • 跨技能的 .agents/references/ 目錄應包含最少數量的檔案，僅保留給至少 2 個技能共用的慣例和標準。
  • 任何僅被單一技能使用的方法檔案、指南、目錄或範本必須移至並封裝在 <技能>/resources/ 下 (Anthropic 的漸進式揭露原則)。
• 強制 inspiration 區塊： 任何新建或修改的技能必須在其 YAML frontmatter 中包含 inspiration: 元數據，並標明其來源、參考外掛和模式。
• 嚴格遵守 10 個章節： 如果技能缺少 10 個標準章節中的任何一個，則不得發布。
• 規則的層級與不矛盾：
  • 本地規則 (.agents/rules/) 優先於一般建議，但未經明確裁決，不得違反安全關鍵規則 (critical-rules.md)。
  • 每條規則必須簡潔、明確，並包含明確的觸發條件 (trigger: always_on 或條件式)。
• 自動驗證： 任何技能修改都必須通過 node scripts/validate-skills.js 驗證。
• YAML 格式的錯誤報告： 因代理錯誤而進行的任何修正都必須在 tests/feedbacks/INC-xxx.yaml 中產生一份報告。

5. 逐步程序 (設計與優化工作流程)

路徑 A：建立新技能

1. 步驟 1：需求分析與 Anthropic 模式選擇：
   • 查閱 resources/anthropic-skill-patterns.md 以選擇最接近的模式 (feature-dev、setup、review 等)。
2. 步驟 2：撰寫 SKILL.md：
   • 填寫 10 章節的範本。
   • 以第三人稱撰寫描述，並明確說明啟用和排除條件。
   • 填寫 YAML 區塊 inspiration。
   • 將技能專屬的配套資源封裝在其 resources/ 子目錄中。
3. 步驟 3：確定性檢查：
   • 執行 node scripts/validate-skills.js。
4. 步驟 4：在目錄中註冊：
   • 在 catalog.yaml 中新增條目，並在 CHANGELOG.md 中記錄。

路徑 B：優化現有技能

1. 步驟 1：診斷與 YAML 報告：
   • 建立 tests/feedbacks/INC-[編號].yaml，包含上下文、觀察到的行為和目標修正。
2. 步驟 2：精準修正：
   • 在章節 #4 (約束) 中新增規則，或在章節 #8 (檢查清單) 中新增二元測試。
3. 步驟 3：SemVer 版本遞增：
   • 更新版本號 (例如 1.0.1) 並在 CHANGELOG.md 中記錄。

路徑 C：建立或修改規則

1. 步驟 1：規則層級判定：
   • 全域工程 / 安全規則 ➔ 新增至 .agents/rules/critical-rules.md 或 .agents/rules/general-principles.md。
   • 專案代理行為規則 ➔ 新增至 .agents/rules/[規則名稱].md。
2. 步驟 2：簡潔且不可違背的撰寫：
   • 使用明確的命令式語句 (例如：「代理必須...」、「嚴格禁止...」)。
   • 提供預期格式的直接範例。
   • 遵守 SSOT 原則：如果規則已存在，絕不重複。
3. 步驟 3：同步與通知：
   • 將修改反映到中心或本地專案，並在 CHANGELOG.md 中記錄變更。

路徑 D：對話結束時的持續知識累積 (/plugin-dev)

1. 步驟 1：回顧與識別發現：
   • 識別最近工作階段中處理的一個或多個套件。
   • 提取代理必須調查或推導出的特定機制：
     • 涉及的資料表與模型、關聯與業務鉤子。
     • ViewStateService 或資料表過濾器的特性。
     • 新引入的服務、定時任務、jobs 或 observers。
     • 已解決的陷阱或邊界案例 (例如：因忽略父過濾器而導致計算錯誤)。
2. 步驟 2：評估文件差距：
   • 將這些發現與 modules/[套件名稱]/[套件名稱]_IA_CONTEXT.md 的現有內容進行比較。
   • 檢查技能 (feature-dev) 或規則是否需要額外指令。
3. 步驟 3：提出豐富計畫：
   • 向設計者提交一份清晰、結構化的計畫，詳細說明建議的新增內容：
     • 針對 [套件名稱]_IA_CONTEXT.md (新增服務、關鍵過濾器、陷阱與建議章節)。
     • 如適用的話，也針對技能本身。
4. 步驟 4：驗證後執行：
   • 一旦獲得驗證，立即豐富 [套件名稱]_IA_CONTEXT.md 檔案，以便任何未來的維護工作階段都能立即利用這些累積的知識。

6. 模糊情況的處理與決策

• 資源位置裁決 (技能 vs 代理)：
  • 如果資源僅由特定技能使用 (例如：編輯器的範本、技術目錄) ➔ 強制位置：<技能>/resources/[檔案].md (在技能的章節 3 中按需載入)。
  • 如果資源定義了由 2 個或更多技能共用的跨工程標準 ➔ 位置：.agents/references/conventions/ 或 .agents/references/architecture/。
• 技能 vs 規則裁決：
  • 如果指令是永久約束或跨領域防護 (例如：顯示技能、回覆風格、禁止遷移) ➔ 建立規則 (.agents/rules/)。
  • 如果指令描述了一個結構化序列，包含按需觸發、輸入、逐步邏輯和交付物 ➔ 建立技能 (SKILL.md)。
• 如果請求的規則僅適用於 Solicode LMS：請勿修改全域中心標準，而是將其記錄在 .agents/rules/ 和 .agents/references/conventions/project-conventions.md 中。

7. 輸出格式與交付物

• 完整的 SKILL.md 檔案或規則檔案 (.agents/rules/*.md)。
• 更新後的 catalog.yaml 和 CHANGELOG.md。
• validate-skills.js 指令碼的執行結果 (0 錯誤)。

8. 品質控制 (二元檢查清單)

• 技能的 YAML frontmatter 是否包含完整的 inspiration 區塊 (來源、外掛、模式)？
• 描述是否為第三人稱，並明確說明何時啟用與何時不啟用？
• 所有 10 個標準章節是否都存在並已填寫？
• 是否遵守 SSOT (單一事實來源) 原則和 DRY 規則 (檔案之間無重複指令)？
• .agents/references/ 目錄是否最小化，且不包含任何單一技能資源？
• 單一技能資源是否嚴格封裝在 <技能>/resources/ 中？
• 如果是規則，是否簡潔、與 critical-rules 不矛盾，並附有清晰的範例？
• node scripts/validate-skills.js 指令碼是否成功執行？

9. 常見錯誤處理

典型錯誤	原因	立即解決方案
將特定資源放在代理層級	封裝粒度不足	將檔案移至 <技能>/resources/ 下，並作為內部資源引用
為一個簡單的被動規則建立技能	混淆規則與結構化流程	將指令移至 .agents/rules/
忘記 inspiration 元數據	疏忽	始終在 frontmatter 中新增 inspiration 區塊
本地規則與中心標準衝突	缺乏事前審計	在正式制定規則前，先審計 .agents/rules/critical-rules.md

10. 具體範例 (Few-Shot)

範例 A (技能) 呼叫： 「建立一個受 content-authoring 啟發的 tutorial-writer 技能。」 行為： 代理載入 anthropic-skill-patterns.md，提取結構化撰寫模式，撰寫 10 個章節，並包含 inspiration: { plugin: "content-authoring" }，將教學範本隔離在 tutorial-writer/resources/ 中，並在 catalog.yaml 中註冊該技能。

範例 B (規則) 呼叫： 「新增一條規則，要求在每條訊息末尾顯示已使用的技能。」 行為： 代理應用 plugin-dev 的路徑 C，撰寫 .agents/rules/display-skills.md，更新 .agents/rules/critical-rules.md，並立即套用所需的格式。