AI插件跨平台开发指南：一次编写，多平台分发实战

1. 项目概述：一个AI插件，一次编写，全平台分发

如果你和我一样，最近在折腾各种AI开发工具，比如Claude Code、Cursor、Gemini CLI，那你肯定遇到过这个头疼的问题：为每个平台写插件，就像在给不同品牌的手机做充电器，接口、协议、配置文件格式全都不一样。今天要聊的这个ai-plugin-marketplace-template项目，就是来解决这个“巴别塔”问题的。它本质上是一个元框架，或者说是一个构建系统，让你能用一套统一的代码结构和配置，生成出适配多个主流AI开发平台的插件包。

简单来说，它的核心价值是“Write Once, Distribute Everywhere”。你只需要在一个地方（plugins/<你的插件名>/目录下）按照它约定的格式编写你的技能、代理、命令、钩子等组件，然后运行几条构建命令，它就能自动为你生成出：

1. 直接能被Claude Code和Cursor识别的原生插件。
2. 符合Gemini CLI要求的独立扩展仓库。
3. 适配OpenAI Codex的插件清单。
4. 可供Kiro使用的“能力”包。
5. 以及能被Vercel Skills CLI扫描到的技能文件。

这不仅仅是简单的文件复制，它包含了平台间术语的映射、配置格式的转换（比如YAML到JSON）、以及功能组件的智能取舍。对于那些不支持某些高级特性（如子代理、命令）的平台，它会选择性地忽略或转换，而不是粗暴地塞进去导致报错。

1.1 核心要解决的问题：平台碎片化

当前AI辅助编程工具生态非常活跃，但各自为政。Claude Code有它的.claude-plugin/plugin.json， Cursor有几乎一样但命名空间不同的.cursor-plugin/plugin.json，Gemini CLI要求一个根目录的gemini-extension.json，而OpenAI Codex又有一套自己的interface元数据块。手动维护多套配置，不仅容易出错，更新一个功能点可能需要在五六个地方做同样的修改，维护成本呈指数级上升。

这个模板项目通过引入一个“超集”源格式和一个“构建流水线”来解决这个问题。你把所有功能都写在源格式里，构建流水线负责针对每个目标平台进行“编译”，输出最符合该平台原生生态的包。这有点像用TypeScript写代码，然后编译成ES5、ES6或者Node.js模块给不同环境使用。

注意：这个模板不是魔法，它不能把A平台独有的功能“模拟”到B平台上。它的策略是“优雅降级”：如果目标平台原生支持某个组件（如Skills），就用原生方式输出；如果不支持（如Codex不支持子代理），就在该平台的输出中直接省略该组件，避免兼容性问题。

2. 项目架构与核心设计思路

理解这个项目的关键是看懂它的目录结构和设计哲学。它不是一个大一统的运行时，而是一个构建时工具链。让我们深入它的仓库，看看各个部分是如何协同工作的。

2.1 仓库结构深度解析

项目根目录的结构清晰地划分了“源”、“构建逻辑”和“输出”。

ai-plugin-marketplace-template/ ├── .claude-plugin/ # Claude Code 市场注册表 ├── .cursor-plugin/ # Cursor 市场注册表 ├── .agents/ # OpenAI Codex 市场注册表 ├── plugins/ # 【核心】所有插件的源代码目录 │ └── <plugin-name>/ │ ├── .claude-plugin/ # Claude 单插件清单 │ ├── .cursor-plugin/ # Cursor 单插件清单 │ ├── .codex-plugin/ # Codex 单插件清单（含UI元数据） │ ├── gemini-extension.json # Gemini 扩展清单 │ ├── POWER.md # Kiro 能力入口文件 │ ├── GEMINI.md # Gemini CLI 上下文文件 │ ├── .mcp.json # MCP配置 (Claude/Cursor/Codex) │ ├── mcp.json # MCP配置 (Kiro) │ ├── skills/ # 通用技能定义 (SKILL.md) │ ├── agents/ # 子代理定义 (.md) │ ├── rules/ # 规则文件 │ ├── steering/ # Kiro 引导文件 │ ├── commands/ # 命令定义 │ ├── hooks/ # 钩子定义源文件 (claude.yaml) │ └── ... (README, LICENSE) ├── src/ # 构建脚本源代码 ├── schemas/ # JSON Schema，用于验证配置文件 ├── templates/ # 脚手架模板 └── dist/ # 【输出】生成的独立仓库 ├── gemini/ # 给Gemini CLI的独立扩展 └── kiro/ # 给Kiro的独立“能力”包

设计思路解读：

1. 隔离与聚合：plugins/目录是开发者唯一需要关心的“源”区域。每个插件自成一体，包含其全部功能组件。而平台特定的根目录配置（如.claude-plugin/marketplace.json）则负责聚合所有插件，告诉对应工具“我这个仓库里有哪些插件可用”。这种设计支持在一个Git仓库里管理多个插件，方便集中维护和版本控制。
2. 配置即代码：大量的功能通过配置文件（JSON, YAML, MD）来定义，而非硬编码在脚本里。这使得功能易于增删改查，也便于通过schemas/目录下的JSON Schema进行严格校验，提前发现配置错误。
3. 构建产出分离：dist/目录是纯粹的输出目录，由构建脚本生成。对于Gemini CLI和Kiro这种要求独立仓库的平台，这里就是准备好的、可以直接提交或发布的包。对于Claude Code、Cursor、Codex，它们直接读取源目录，因此dist/里没有它们的输出。

2.2 平台兼容性矩阵与“保真度”分级

项目将支持的平台分为了三个“保真度”等级，这是一个非常务实的设计：

保真度等级解读：

• Tier 1 (富插件)：包括Claude Code, Cursor, Gemini CLI, OpenAI Codex。这些平台支持完整的插件概念，可以捆绑技能、代理、MCP等多种组件。模板会为它们生成最丰富的原生表示。例如，为Gemini CLI生成独立的扩展仓库，并完成工具名映射（Read->read_file）。
• Tier 2 (独立导出)：以Kiro为代表。它期望一个独立的仓库根目录配置。构建过程会将插件转换为Kiro能理解的格式（如将代理的.md文件转换为.kiro/agents/*.json），并打包成独立的dist/kiro/<name>/目录。
• Tier 3 (有损回退)：特指Vercel Skills CLI。它只做一件事：递归扫描仓库中的所有SKILL.md文件。因此，对于这个平台，插件中的所有其他高级组件（代理、命令、钩子、MCP）都会被忽略。只有当你的插件的核心价值完全由技能承载时，这个分发渠道才有意义。

这个矩阵是开发者的决策地图。当你设计一个插件功能时，可以快速查阅哪些平台支持它。如果不支持，你就需要思考：这个功能是否是核心的？能否通过其他方式（如技能描述）间接实现？还是说可以接受在某些平台上该功能缺失？

3. 核心组件详解与实操要点

要高效使用这个模板，必须理解其中每个目录和文件的作用。我们以创建一个“代码审查”插件为例，拆解每个核心组件。

3.1 技能：插件的基石

skills/目录是插件的核心，存放SKILL.md文件。这是目前跨平台兼容性最好的组件。一个典型的SKILL.md包含YAML Frontmatter和技能描述。

--- name: code-review description: 对指定文件或代码块进行安全检查、风格检查和最佳实践建议。 input: 一个文件路径或一段代码。 output: 结构化的审查报告，包含问题、严重级别和建议修复方法。 tags: [security, linting, best-practices] --- # 代码审查技能 此技能会分析提供的代码，检查以下方面： 1. **安全漏洞**：如SQL注入、XSS、路径遍历的潜在风险。 2. **代码风格**：是否符合项目约定的缩进、命名规范等。 3. **性能与最佳实践**：是否存在低效循环、未关闭的资源、过时的API调用等。 请提供需要审查的代码。

实操要点：

• 命名清晰：name字段要能准确反映技能功能，避免使用skill1这种无意义的名字。
• 描述具体：description和正文描述要清晰说明技能的输入（它需要什么）、处理（它会做什么）、输出（它返回什么）。模糊的描述会导致AI模型无法正确调用它。
• 标签有用：tags可以帮助在插件市场中进行分类和筛选。
• 一个文件一个技能：虽然技术上可以把多个技能写在一个文件里，但强烈建议每个SKILL.md只定义一个技能，这样更利于维护和平台索引。

3.2 代理：复杂任务的分解者

agents/目录存放子代理定义文件（.md）。子代理是Claude、Cursor等平台的高级功能，允许你定义具有特定系统指令和工具的“专家”，供主会话调用。这在模板中通过.md文件定义。

agents/ └── security-reviewer.md

security-reviewer.md内容示例：

你是一个专注于安全的代码审查专家。你的知识库涵盖OWASP Top 10、常见语言（如Java/Python/JS）的安全陷阱和最新的CVE信息。 ## 工具 你可以使用以下工具： - `read_file`: 读取指定文件的内容。 - `search_web`: 搜索最新的安全公告和漏洞信息。 - `run_static_analysis`: 对代码运行基础的静态分析。 ## 规则 - 始终优先检查用户输入验证和输出编码。 - 对发现的高危漏洞，必须提供具体的修复代码示例。 - 在不确定时，应注明“需要进一步手动确认”，而非给出可能错误的判断。

注意事项：

• 工具映射：注意，在构建给Gemini CLI的独立包时，构建脚本 (src/build-standalone.ts) 会自动将Claude风格的工具名（如Read）映射为Gemini风格（read_file）。你只需要在源文件中使用一种风格（通常是Claude的），构建过程会处理兼容性。
• 平台差异：OpenAI Codex目前不支持子代理概念，因此agents/目录下的内容在生成Codex插件时会被忽略。Kiro则通过构建脚本，将这些.md文件转换为其专属的.kiro/agents/*.json格式。

3.3 清单与配置：插件的身份证

每个平台都需要一个清单文件来识别插件。这是配置最分散的部分，也是模板价值最大的地方。

• Claude Code & Cursor：它们在plugins/<name>/下各有自己的目录（.claude-plugin/,.cursor-plugin/），里面是一个plugin.json。内容几乎完全相同，主要区别在于id和name可能包含的平台前缀。根目录的marketplace.json则列出了仓库中所有可用的插件。
• OpenAI Codex：清单在plugins/<name>/.codex-plugin/plugin.json。关键区别是它包含一个interface块，用于在Codex的插件商店UI中展示，如displayName,shortDescription,logo,brandColor等。这是纯元数据，不影响功能，但对用户体验很重要。
• Gemini CLI：使用plugins/<name>/gemini-extension.json。这个文件更丰富，定义了MCP服务器、上下文文件(GEMINI.md)、要排除的工具以及扩展设置。
• Kiro：入口是POWER.md文件，这是一个Markdown格式的“能力”描述文件。同时，它使用mcp.json（注意没有前导点）来配置MCP服务器。

配置技巧：

• 利用脚手架：最省事的方法是使用pnpm run scaffold my-plugin，它会基于templates/目录生成所有必要的清单文件骨架，你只需要填充具体信息。
• 保持ID唯一：确保不同插件的id和name在整个生态中是唯一的，避免冲突。
• 精心设计UI元数据：对于Codex插件，花点时间设计interface块，好的图标、描述和分类能极大提高插件的安装率。

3.4 命令、钩子与规则：增强交互与控制

• 命令：commands/目录下的文件定义了用户可以手动触发的操作。Claude/Cursor用.md文件，Gemini CLI用.toml文件。例如，一个commands/run-review.toml可以定义一个触发代码审查流程的命令。
• 钩子：hooks/目录用于定义事件触发的自动化操作。源文件是claude.yaml（一种YAML格式），构建脚本 (src/build-hooks.ts) 会将其转换为各个平台所需的JSON格式（如Claude的claude.json，Gemini的hooks.json）。钩子可以用在提交代码前自动审查、或在创建新文件后自动添加版权头等场景。
• 规则：rules/目录下的文件（Claude用.md，Cursor用.mdc）定义了AI在会话中应遵循的高级指导原则或约束。例如，可以设置“所有生成的代码必须包含单元测试”或“避免使用已弃用的库”。

重要提示：命令、钩子和规则是平台特异性很强的功能。在规划插件功能时，务必对照“平台兼容性矩阵”。如果你重度依赖钩子来实现核心逻辑，那么你的插件在Codex和Vercel Skills CLI上将几乎无法工作，因为这两个平台不支持钩子。此时你需要考虑是否将钩子的逻辑转移到技能描述中，或者接受功能降级。

4. 完整工作流：从零创建一个多平台插件

理论说了这么多，我们来走一遍完整的实操流程。假设我们要创建一个名为awesome-linter的插件，它提供一个代码检查和基础修复的技能。

4.1 初始化与脚手架

首先，确保你已克隆模板仓库并安装依赖。

git clone <模板仓库地址> cd ai-plugin-marketplace-template pnpm install # 或 npm install, yarn install

使用脚手架命令创建新插件骨架。这是最关键的一步，能避免手动创建大量配置文件。

pnpm run scaffold awesome-linter

执行后，你会发现在plugins/目录下新生成了一个awesome-linter文件夹，里面已经包含了所有平台所需的清单文件模板、以及skills/,agents/等空目录。脚手架工具 (src/scaffold.ts) 的工作就是复制templates/中的文件，并替换其中的插件名等占位符。

4.2 编写核心功能

现在，我们开始填充内容。

1. 创建核心技能： 在plugins/awesome-linter/skills/下创建lint-and-fix.md。

--- name: lint-and-fix description: 对提供的代码进行 lint 检查，并尝试自动修复可修复的问题。支持 JavaScript/TypeScript 和 Python。 input: 一段代码或一个文件路径。请指定语言。 output: 检查报告，列出所有问题（错误、警告）、严重级别、位置，以及修复后的代码（如果可自动修复）。 tags: [linting, formatting, javascript, typescript, python] --- # Lint 与自动修复 我是一个代码质量助手。我会使用对应语言的最佳实践规则（如 ESLint 对于 JS/TS，Ruff 或 Black 对于 Python）来分析你的代码。 ## 我能做什么 1. **语法与风格检查**：识别未使用的变量、错误的缩进、不规范的命名等。 2. **潜在错误检测**：检查可能为 `null` 或 `undefined` 的访问、错误的比较等。 3. **自动修复**：对于诸如缺少分号、引号不一致、简单的语法转换等问题，我会直接提供修复后的代码。 4. **建议**：对于无法自动修复的复杂问题，我会提供修改建议和原因。 ## 如何使用 直接粘贴你的代码，或者告诉我文件路径（如果我在可以访问的上下文中）。请务必指明代码的语言（如“这是一段TypeScript代码”）。

2. （可选）创建专用代理： 如果我们想让 lint 更专业，可以创建一个 linter 代理。在plugins/awesome-linter/agents/下创建professional-linter.md。

你是一个严格且专业的代码清洁工。你的唯一目标是让代码变得清晰、高效、符合规范。 ## 原则 - 可读性高于聪明的技巧。 - 严格遵守传入代码所属语言和项目的流行风格指南（如 Airbnb JavaScript Style Guide, Google Python Style Guide）。 - 对于有争议的格式问题，优先采用更保守、更广泛接受的方案。 ## 工具 你将拥有代码读取、静态分析工具。对于无法自动决定的问题，你应该与用户讨论权衡利弊，而不是强行应用规则。

3. 配置 MCP 服务器： 如果我们的 linter 需要连接到一个真实的、外部的 linting 服务（例如一个自定义的 Language Server），我们需要配置 MCP。编辑plugins/awesome-linter/.mcp.json。

{ "mcpServers": { "awesome-linter-server": { "command": "node", "args": [ "/path/to/your/linter-server/index.js" ], "env": { "API_KEY": "${env:MY_LINTER_API_KEY}" } } } }

同时，需要为 Kiro 准备一份mcp.json（无前导点），内容类似。为 Gemini 扩展配置，则需要在gemini-extension.json的mcpServers字段中添加相应配置。

4.3 更新平台市场清单

新插件创建后，需要“注册”到各个平台的市场中，这样它们才能在插件列表里看到它。你需要手动编辑三个根目录文件：

1. .claude-plugin/marketplace.json：在plugins数组中添加一项。

   { "plugins": [ // ... 其他已有插件 ... { "id": "awesome-linter", "name": "Awesome Linter", "path": "./plugins/awesome-linter" } ] }

2. .cursor-plugin/marketplace.json：进行同样的添加。
3. .agents/plugins/marketplace.json：这是给 OpenAI Codex 的。

   { "plugins": [ // ... 其他已有插件 ... { "name": "awesome-linter", "source": { "source": "local", "path": "./plugins/awesome-linter" }, "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" } } ] }

注意：pnpm run validate命令会检查这些清单的完整性和正确性，但不会自动添加新条目。这是一个需要手动完成的步骤。未来或许可以通过脚手架脚本自动更新，但目前需要开发者自己维护。

4.4 验证与构建

在发布或测试前，必须进行验证和构建。

# 1. 验证所有配置和清单的格式是否正确 pnpm run validate

如果看到成功信息，说明配置没问题。如果报错，请根据错误信息修正，通常是JSON格式错误或缺少必填字段。

# 2. 构建独立导出包（针对 Gemini CLI 和 Kiro） pnpm run build:standalone

这个命令 (src/build-standalone.ts) 会执行以下操作：

• 读取plugins/awesome-linter/下的源文件。
• 为 Gemini CLI：创建一个dist/gemini/awesome-linter/目录，复制并转换所有必要文件（如将agents/下的.md文件中的工具名进行映射，将hooks/claude.yaml转换为hooks/hooks.json）。
• 为 Kiro：创建一个dist/kiro/awesome-linter/目录，进行类似的转换（如生成.kiro/agents/下的JSON文件）。
• 对于 Claude Code, Cursor, Codex，它们直接读取源目录，因此不需要独立的构建产物。

4.5 测试与分发

构建完成后，就可以在不同平台测试了。

• Claude Code / Cursor：确保你的开发工具指向这个本地仓库。在Claude Code中，通常可以通过“添加本地插件源”并选择仓库根目录来实现。之后，你应该能在插件列表里看到Awesome Linter。
• Gemini CLI：进入dist/gemini/awesome-linter/目录，将其作为一个独立的Git仓库初始化、提交，并推送到GitHub。然后可以通过gemini extensions add <github-repo-url>来安装。
• OpenAI Codex：在Codex的设置中，添加一个“用户源”，指向这个本地仓库的.agents/plugins/marketplace.json文件。之后在聊天中输入/plugins应该能看到你的插件。
• Kiro：将dist/kiro/awesome-linter/作为一个独立仓库发布，然后在Kiro中添加这个“能力”仓库。
• Vercel Skills CLI：在任何地方，只要运行npx skills add <你的GitHub用户名>/<ai-plugin-marketplace-template仓库名>，它就会扫描整个仓库的SKILL.md文件，从而找到awesome-linter的技能。

5. 常见问题、排查技巧与进阶思考

在实际使用中，你肯定会遇到各种问题。下面是我在多次实践中总结的一些坑和解决方案。

5.1 验证失败：JSON Schema 不匹配

问题：运行pnpm run validate时，报错提示某个plugin.json不符合 schema。

排查：

1. 检查必填字段：最常见的原因是缺少了某个平台的必填字段。例如，OpenAI Codex的plugin.json必须包含interface对象，而Claude的则不需要。仔细对比脚手架生成的模板和示例插件skill-evaluator的配置。
2. 检查数据类型：确保字段值是正确的类型。例如，category应该是字符串，capabilities应该是数组。
3. 使用VS Code辅助：如果你在schemas/目录下关联了JSON Schema（例如在VS Code的settings.json中配置json.schemas），编辑器会直接给你红线提示，这是最快的排查方式。

5.2 插件在某个平台不显示或无法加载

问题：在Claude Code里能看到插件，但在Cursor里看不到，或者反之。

排查：

1. 检查根目录 marketplace.json：确认两个平台的marketplace.json文件都正确添加了你的插件条目。路径 (path) 必须正确指向plugins/<你的插件名>。
2. 检查插件清单路径：确认plugins/<你的插件名>/.claude-plugin/plugin.json和.cursor-plugin/plugin.json文件存在且内容有效。虽然它们内容几乎一样，但必须存在于各自平台指定的目录下。
3. 平台缓存：AI开发工具有时会缓存插件列表。尝试重启工具，或者清除其本地数据（具体方法因工具而异）。
4. 查看工具日志：Claude Code和Cursor通常有开发者控制台或日志文件。打开它们，搜索你的插件ID或名称，看是否有加载错误信息。

5.3 技能或代理在 Gemini/Kiro 上行为异常

问题：在Claude上工作正常的技能，到了Gemini CLI或Kiro上无法被调用或结果不对。

排查：

1. 工具名映射：这是最常见的问题。你的代理.md文件中如果引用了Read,Write等工具，在构建给Gemini时，src/build-standalone.ts脚本会将其映射为read_file,write_file。请检查dist/gemini/<插件名>/agents/下生成的.md文件，确认映射是否成功。如果没有，可能是脚本的映射表需要更新。
2. 功能不支持：确认你使用的功能在目标平台上是否被支持。例如，你在源文件中定义了复杂的钩子 (hooks/)，但Gemini CLI的钩子系统可能更简单，或者Kiro的钩子实现方式不同。构建脚本可能无法完美转换所有逻辑。此时需要查阅目标平台的官方文档，调整你的源实现，或者接受功能限制。
3. 独立仓库结构：对于Gemini和Kiro，务必确保dist/下的目录是一个完整的、正确的仓库。特别是gemini-extension.json或POWER.md必须在根目录。检查构建脚本是否遗漏了关键文件。

5.4 性能与维护考量

问题：当插件数量增多、功能变复杂后，构建时间变长，仓库变得臃肿。

优化建议：

1. 增量构建：目前的build:standalone似乎是全量重建。对于大型项目，可以考虑修改构建脚本，只针对发生变化的插件进行构建。可以通过比较文件哈希来实现。
2. 模块化插件：将大型插件拆分为多个小型、专注的插件。例如，将“代码审查”拆分为“安全审查”、“性能审查”、“风格审查”三个独立插件。这样用户可以根据需要安装，也利于单独更新和测试。
3. CI/CD 集成：将pnpm run validate和pnpm run build集成到GitHub Actions或GitLab CI中。确保每次推送到主分支或发布标签时，自动验证配置并生成最新的dist/产物，供自动化部署使用。
4. 版本管理：模板本身没有强制规定插件版本管理。一个良好的实践是在每个插件的plugin.json中维护version字段，并在根目录的marketplace.json中或许可以增加版本信息，以便工具能检测到更新。

5.5 扩展模板：支持新平台

场景：一个新的AI编程工具X-Studio发布了，你想让你的插件也支持它。

步骤：

1. 研究新平台：仔细阅读X-Studio的插件开发文档，弄清楚它的插件结构、清单格式、支持哪些组件（技能、代理、命令等）。
2. 在模板中添加支持：
   • 在src/build-standalone.ts中增加一个新的构建目标（如果X-Studio需要独立导出）。
   • 或者，在plugins/<name>/下创建新的配置目录（如.xstudio-plugin/），如果它像Claude一样直接读取源文件。
   • 在src/validate.ts中增加对新平台清单文件的JSON Schema验证。
   • 在templates/目录下更新脚手架模板，使其能生成X-Studio的配置文件。
   • 更新根目录的README.md和平台兼容性矩阵。
3. 处理差异：这是最复杂的部分。你需要决定如何将现有的“超集”组件映射到X-Studio的模型上。可能需要进行功能裁剪、格式转换或行为模拟。

这个过程正是ai-plugin-marketplace-template项目核心思想的体现：将平台差异抽象为构建时的转换问题。随着更多平台加入，这个模板的构建流水线会变得越来越复杂，但也越来越有价值。

最后，我个人最深的体会是，使用这个模板前期需要投入时间理解其设计理念和各个平台的差异，但一旦跑通，后续的插件开发和维护效率会得到质的提升。它迫使你以一种更结构化、更声明式的方式思考AI插件的功能，这本身也是对插件设计的一种锻炼。在AI工具快速演进的今天，这种面向“适配层”的开发思路，或许是应对生态碎片化的一种有效策略。