BIGboss248/nextjs-wordpress

Antigravity 自訂工具（ag-customizer）

使用此技能來自動設計、建立、配置、遷移及驗證 Google Antigravity 的工作區或全域範圍自訂功能。

---

快速導覽決策矩陣

判斷哪種自訂機制最能解決問題：

需求	機制	檔案位置	參考指南
教導代理程式多步驟操作手冊、程序或斜線指令	技能	.agents/skills/<name>/SKILL.md 或 ~/.gemini/antigravity/skills/<name>/SKILL.md	skills-guide.md
強制執行持續性約束、編碼標準或樣式規則	規則	.agents/rules/<name>.md、AGENTS.md 或 ~/.gemini/GEMINI.md	rules-guide.md
連接外部服務、本地資料庫或自訂工具	MCP 伺服器	.agents/mcp_config.json 或 ~/.gemini/config/mcp_config.json	mcp-guide.md
攔截生命週期事件（閘道指令、注入提示、停止監視）	生命週期鉤子	.agents/hooks.json 或 ~/.gemini/config/hooks.json	hooks-guide.md
將技能、規則、鉤子和 MCP 打包成可分享的套件	插件	.agents/plugins/<name>/ 或 ~/.gemini/config/plugins/<name>/	plugins-and-configs.md
註冊非標準路徑或透過版本控制分享自訂設定	JSON 配置	.agents/skills.json 或 .agents/plugins.json	plugins-and-configs.md
將已棄用的工作流程升級成現代斜線指令技能	工作流程遷移	.agents/workflows/*.md -> .agents/skills/<name>/SKILL.md	workflows-migration.md

---

操作工作流程

1. 新增技能

1. 確定範圍：
   • 工作區：.agents/skills/<name>/（簽入儲存庫供團隊使用）。
   • 全域：~/.gemini/antigravity/skills/<name>/（所有專案皆可使用）。
2. 建立目錄結構：

   <customization_root>/skills/<skill-name>/
   ├── SKILL.md             # 必要：入口點，包含 YAML 前置資料
   ├── scripts/             # 可選：輔助腳本（使用 --help 模式執行）
   ├── references/          # 可選：公開的手冊與詳細文件
   └── examples/            # 可選：範例程式碼或輸出參考
   

3. 撰寫前置資料：
   • name：小寫、以連字符分隔（例如 nextjs-otel、docker-deploy）。這也同時註冊為斜線指令（/<name>）。
   • description：以第三人稱撰寫 1-3 句話，明確說明技能的功能以及代理程式應觸發該技能的特定觸發詞/情境。
4. 應用漸進式揭露：
   • 主要 SKILL.md 應專注於操作步驟的順序和完成標準。
   • 將詳細的參考資料放在 references/<topic>.md 檔案中，並使用相對連結。
   • 結構模板請參考 skills-guide.md。
5. Obsidian 鏡像檢查：
   • 在此工作區中更新或建立技能時，請根據儲存庫準則將技能資料夾鏡像到 d:/Scripts/Obsidian/skills/<name>/。

---

2. 建立規則

1. 確定範圍與格式：
   • 工作區規則：專案根目錄下的 .agents/rules/<rule-name>.md 或 AGENTS.md。
   • 全域規則：~/.gemini/GEMINI.md。
2. 選擇啟動模式（適用於 .agents/rules/*.md）：
   • always_on：無條件注入每一輪對話。請謹慎使用以節省上下文空間。
   • model_decision：當代理程式根據描述判斷相關性時揭露。
   • glob：每當觸碰或開啟符合條件的檔案時自動啟動（例如 *.tsx、src/api/**/*.ts）。
   • manual：僅在聊天中透過 @提及 明確呼叫時載入（例如 @my-rule.md）。
3. 編寫內容：
   • 每個檔案的字元數限制為 12,000 字元。
   • 使用正面陳述來描述目標行為（例如「執行 X」、「總是照 Y 方式結構化」），避免負面禁止。
   • 如有需要，可使用 @filename 連結到相關的背景檔案。
   • 完整語法與啟動前置資料請參考 rules-guide.md。

---

3. 配置 MCP 伺服器

1. 確定檔案位置：
   • 工作區：<workspace>/.agents/mcp_config.json
   • 全域：~/.gemini/config/mcp_config.json
2. 選擇傳輸方式：
   • stdio（本地可執行檔）：

     {
       "mcpServers": {
         "my-server": {
           "command": "npx",
           "args": ["-y", "@modelcontextprotocol/server-sqlite", "app.db"],
           "env": { "SQLITE_READONLY": "true" }
         }
       }
     }
     

   • 遠端（SSE / Streamable HTTP）：

     [!IMPORTANT] 請始終使用鍵值 serverUrl。舊有的 url 或 httpUrl 鍵值不再支援。

     {
       "mcpServers": {
         "my-remote": {
           "serverUrl": "https://api.example.com/mcp/",
           "headers": { "Authorization": "Bearer YOUR_TOKEN" }
         }
       }
     }
     

3. 驗證：
   • Google 應用程式預設憑證："authProviderType": "google_credentials"（需執行 gcloud auth application-default login）。
   • OAuth："oauth": { "clientId": "...", "clientSecret": "..." } 搭配重新導向 URI https://antigravity.google/oauth-callback。
4. 工具篩選：
   • 暫時停用工具而不移除伺服器："disabledTools": ["destructive_command"]。
   • 預先建立的配置請參考 mcp-guide.md。

---

4. 設定生命週期鉤子

1. 目標檔案：.agents/hooks.json（或 ~/.gemini/config/hooks.json）。
2. 支援的事件：
   • PreToolUse：比對工具名稱（run_command、write_to_file、*）以進行閘道控管（allow、deny、ask、force_ask）或淺層覆寫引數。
   • PostToolUse：稽核輸出、執行 linter 或在工具完成後格式化程式碼。
   • PreInvocation：在模型處理該輪對話之前注入上下文或系統指令（injectSteps 搭配 ephemeralMessage）。
   • PostInvocation：強制繼續（terminationBehavior: "force_continue"）或停止。
   • Stop：檢查任務完成狀態（terminationReason、fullyIdle）並回傳 decision: "continue" 及其 reason 以阻止過早退出。
3. 合約規則：
   • 執行透過 stdin 傳遞上下文，並透過 stdout 接收回應。
   • 所有 JSON 酬載鍵值使用 camelCase（conversationId、stepIdx、toolCall 等）。
   • 指令同步執行，並在逾時（預設 30 秒）前阻斷代理程式迴圈。
   • Python、PowerShell 和 Bash 的模板請參考 hooks-guide.md。

---

5. 打包插件或 VCS 共享配置

1. 插件套件：
   • 將相關的技能、規則、鉤子和 MCP 伺服器分組到 .agents/plugins/<plugin-name>/。
   • 新增 plugin.json 資訊清單（{"name": "my-plugin"}）。
   • 在 config.json 中的 "plugins": { "<plugin-name>": { "enabled": true } } 管理啟動狀態。
2. JSON 配置（skills.json / plugins.json）：
   • 註冊外部目錄或共享團隊儲存庫。
   • 支援 entries（路徑）和 inherits（其他配置），並可搭配 include_only 和 exclude 正規表示式篩選器。
   • 完整的資訊清單範例請參考 plugins-and-configs.md。

---

6. 現代化舊有工作流程

1. 檢查是否有已棄用的 .agents/workflows/*.md 或 ~/.gemini/config/workflows/*.md。
2. 擷取操作說明並產生具有適當 YAML 前置資料的等效 SKILL.md。
3. 將原始檔案歸檔為 <name>.md.bak（安全保留）。
4. 自動化遷移手冊請參考 workflows-migration.md。

---

驗證與檢查清單

在將任何自訂視為完成之前：

• JSON 語法：確保所有 .json 檔案可以無語法錯誤或註解地正確解析。
• 前置資料檢查：驗證 SKILL.md 是否包含有效的 YAML 前置資料，並包含 name 和具描述性的 description。
• 字元數預算：確保規則的 Markdown 檔案在 12,000 字元限制內。
• MCP 連線：驗證指令二進位檔或遠端 URL 是否存在且可通過驗證。
• 鉤子合約：驗證鉤子腳本是否接受 stdin 的 camelCase JSON 並在 stdout 回傳有效的 JSON。
• Obsidian 鏡像：對於此工作區中的技能，將建立的技能資料夾同步到 d:/Scripts/Obsidian/skills/<name>/。