SuperAPI AI 工具集

plugin-structure

编程与开发

查看项目

更新于 11-10 16:24

技能介绍

Google Antigravity 插件采用标准化目录结构,并支持组件自动发现。掌握该结构有助于创建组织良好、易于维护且能无缝集成的插件。

一、核心概念 插件使用约定式目录布局进行自动发现;通过 .claude-plugin/plugin.json 进行清单驱动配置;组件按类型组织(命令、代理、技能、钩子);插件内部路径引用使用 ${ANTIGRAVITY_PLUGIN_ROOT} 保证可移植性;组件加载支持显式指定与自动发现两种方式。

二、目录结构 每个插件遵循以下组织模式: plugin-name/ ├── .claude-plugin/ │ └── plugin.json # 必需:插件清单 ├── commands/ # 斜杠命令(.md 文件) ├── agents/ # 子代理定义(.md 文件) ├── skills/ # 代理技能(子目录) │ └── skill-name/ │ └── SKILL.md # 每个技能必需 ├── hooks/ │ └── hooks.json # 事件处理器配置 ├── .mcp.json # MCP 服务器定义 └── scripts/ # 辅助脚本与工具

关键规则:plugin.json 清单必须位于 .claude-plugin/ 目录;所有组件目录(commands、agents、skills、hooks)必须位于插件根目录,不能嵌套在 .claude-plugin/ 内;仅为插件实际使用的组件创建目录;所有目录与文件名使用 kebab-case。

三、插件清单(plugin.json) 清单定义插件元数据与配置,位于 .claude-plugin/plugin.json。必需字段为 name,需使用 kebab-case 格式,在已安装插件中唯一,不得含空格或特殊字符,例如 code-review-assistant、test-runner、api-docs。

推荐元数据包括:name、version(遵循语义化版本 MAJOR.MINOR.PATCH)、description、author(name、email、url)、homepage、repository、license、keywords(用于插件发现与分类)。

组件路径配置:可在清单中为组件指定自定义路径,例如 commands、agents(支持数组)、hooks、mcpServers。自定义路径补充默认目录而非替换,默认目录与自定义路径中的组件都会加载。路径规则:必须相对于插件根目录、必须以 ./ 开头、不能使用绝对路径、支持数组指定多个位置。

四、组件组织

  1. 命令:位于 commands/ 目录,格式为带 YAML frontmatter 的 Markdown 文件,commands/ 下所有 .md 文件自动加载。文件格式包含 name、description 等 frontmatter,后接命令实现说明。命令在 Google Antigravity 中集成原生斜杠命令。
  2. 代理:位于 agents/ 目录,格式为带 YAML frontmatter 的 Markdown 文件,自动加载。frontmatter 可包含 description、capabilities 等,后接详细代理指令与知识。用户可手动调用代理,或由 Google Antigravity 根据任务上下文自动选择。
  3. 技能:位于 skills/ 目录,每个技能一个子目录,其中必须包含 SKILL.md;技能子目录中所有 SKILL.md 自动加载。SKILL.md 的 frontmatter 包含 name、description、version 等,后接技能说明与指导。技能可包含 scripts/、references/、examples/、assets/ 等支持文件。Google Antigravity 根据任务上下文与描述匹配自主激活技能。
  4. 钩子:位于 hooks/hooks.json 或内联在 plugin.json 中,格式为定义事件处理器的 JSON。插件启用时钩子自动注册。配置示例包含 PreToolUse 事件、matcher、hooks 数组(type、command、timeout)。可用事件包括 PreToolUse、PostToolUse、Stop、SubagentStop、SessionStart、SessionEnd、UserPromptSubmit、PreCompact、Notification。钩子响应 Google Antigravity 事件自动执行。
  5. MCP 服务器:位于插件根目录的 .mcp.json 或内联在 plugin.json 中,格式为 MCP 服务器定义的 JSON。插件启用时服务器自动启动。示例包含 mcpServers 对象,内含 command、args、env。MCP 服务器与 Google Antigravity 工具系统无缝集成。

五、可移植路径引用 插件内部所有路径引用应使用 ${ANTIGRAVITY_PLUGIN_ROOT} 环境变量。插件安装位置因安装方式(市场、本地、npm)、操作系统约定和用户偏好而异,因此必须使用该变量。适用于钩子命令路径、MCP 服务器命令参数、脚本执行引用、资源文件路径。禁止使用硬编码绝对路径、相对于工作目录的路径或家目录快捷方式。 路径解析规则:在清单 JSON 字段(hooks、MCP 服务器)中使用 ${ANTIGRAVITY_PLUGIN_ROOT}/scripts/tool.sh;在组件文件(命令、代理、技能)中引用 ${ANTIGRAVITY_PLUGIN_ROOT}/scripts/helper.py;在执行脚本中可将其作为环境变量使用,例如 source "${ANTIGRAVITY_PLUGIN_ROOT}/lib/common.sh"。

六、文件命名约定 命令使用 kebab-case 的 .md 文件,如 code-review.md 对应 /code-review。代理使用描述角色的 kebab-case .md 文件,如 test-generator.md、code-reviewer.md。技能使用 kebab-case 目录名,如 api-testing/、database-migrations/。支持文件:脚本使用描述性 kebab-case 名称及合适扩展名,如 validate-input.sh、generate-report.py;文档使用 kebab-case Markdown 文件;配置使用标准名称 hooks.json、.mcp.json、plugin.json。

七、自动发现机制 插件启用时读取 .claude-plugin/plugin.json;扫描 commands/ 获取 .md 文件;扫描 agents/ 获取 .md 文件;扫描 skills/ 获取包含 SKILL.md 的子目录;从 hooks/hooks.json 或清单加载钩子配置;从 .mcp.json 或清单加载 MCP 服务器配置。发现时机:插件安装时组件注册,插件启用时组件可用,无需重启,更改在下一个 Google Antigravity 会话生效。清单中的自定义路径补充而非替换默认目录。

八、最佳实践 组织方面:将相关组件逻辑分组;保持清单精简,仅在必要时指定自定义路径,标准布局依赖自动发现;为插件根目录、组件目录、脚本目录编写 README。命名方面:跨组件保持一致命名;使用描述性名称表明用途;命令控制在 2-3 个词,代理清晰描述角色,技能聚焦主题。可移植性方面:始终使用 ${ANTIGRAVITY_PLUGIN_ROOT},在 macOS、Linux、Windows 上测试,记录依赖的工具与版本,避免系统特定功能。维护方面:发布时更新 plugin.json 版本,优雅弃用旧组件,记录破坏性变更,变更后充分测试。

九、常见模式 最小插件:仅一个命令,清单只含 name 字段。全功能插件:包含命令、代理、技能、钩子及脚本、.mcp.json、共享脚本。技能聚焦插件:仅提供 skills/ 下多个技能目录。

十、故障排查 组件未加载:检查文件目录与扩展名、YAML frontmatter 语法、技能是否有 SKILL.md、插件是否在设置中启用。路径解析错误:用 ${ANTIGRAVITY_PLUGIN_ROOT} 替换硬编码路径,确认清单中路径以 ./ 开头且文件存在,在钩子脚本中用 echo 测试变量。自动发现失效:确认目录位于插件根目录而非 .claude-plugin/ 内,检查命名约定,确认清单自定义路径,重启以重新加载配置。插件冲突:使用唯一描述性组件名,必要时用插件名为命令加命名空间,在 README 中记录潜在冲突,考虑为相关功能加命令前缀。更多示例与高级模式见 references/ 和 examples/ 目录(该资料未展开具体文件内容)。

本资料未提供插件的收费、价格、平台限制或效果数据。