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 包含带有 name 和描述性 description 的有效 YAML 前置元数据。
• 字符预算：确保规则 Markdown 文件在 12,000 字符限制内。
• MCP 连接：验证命令二进制文件或远程 URL 是否存在并能够认证。
• 钩子契约：验证钩子脚本接受标准输入上的 camelCase JSON，并在标准输出上返回有效 JSON。
• Obsidian 镜像：对于此工作区中的技能，将创建的技能文件夹同步到 d:/Scripts/Obsidian/skills/<name>/。