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

1. 项目概述一个AI插件一次编写全平台分发如果你和我一样最近在折腾各种AI开发工具比如Claude Code、Cursor、Gemini CLI那你肯定遇到过这个头疼的问题为每个平台写插件就像在给不同品牌的手机做充电器接口、协议、配置文件格式全都不一样。今天要聊的这个ai-plugin-marketplace-template项目就是来解决这个“巴别塔”问题的。它本质上是一个元框架或者说是一个构建系统让你能用一套统一的代码结构和配置生成出适配多个主流AI开发平台的插件包。简单来说它的核心价值是“Write Once, Distribute Everywhere”。你只需要在一个地方plugins/你的插件名/目录下按照它约定的格式编写你的技能、代理、命令、钩子等组件然后运行几条构建命令它就能自动为你生成出直接能被Claude Code和Cursor识别的原生插件。符合Gemini CLI要求的独立扩展仓库。适配OpenAI Codex的插件清单。可供Kiro使用的“能力”包。以及能被Vercel Skills CLI扫描到的技能文件。这不仅仅是简单的文件复制它包含了平台间术语的映射、配置格式的转换比如YAML到JSON、以及功能组件的智能取舍。对于那些不支持某些高级特性如子代理、命令的平台它会选择性地忽略或转换而不是粗暴地塞进去导致报错。1.1 核心要解决的问题平台碎片化当前AI辅助编程工具生态非常活跃但各自为政。Claude Code有它的.claude-plugin/plugin.json Cursor有几乎一样但命名空间不同的.cursor-plugin/plugin.jsonGemini 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的独立“能力”包设计思路解读隔离与聚合plugins/目录是开发者唯一需要关心的“源”区域。每个插件自成一体包含其全部功能组件。而平台特定的根目录配置如.claude-plugin/marketplace.json则负责聚合所有插件告诉对应工具“我这个仓库里有哪些插件可用”。这种设计支持在一个Git仓库里管理多个插件方便集中维护和版本控制。配置即代码大量的功能通过配置文件JSON, YAML, MD来定义而非硬编码在脚本里。这使得功能易于增删改查也便于通过schemas/目录下的JSON Schema进行严格校验提前发现配置错误。构建产出分离dist/目录是纯粹的输出目录由构建脚本生成。对于Gemini CLI和Kiro这种要求独立仓库的平台这里就是准备好的、可以直接提交或发布的包。对于Claude Code、Cursor、Codex它们直接读取源目录因此dist/里没有它们的输出。2.2 平台兼容性矩阵与“保真度”分级项目将支持的平台分为了三个“保真度”等级这是一个非常务实的设计功能组件Claude CodeCursorGemini CLICodexKiroSkills CLI保真度等级111123技能 (SKILL.md)原生原生原生原生通过引导原生子代理 (.md)原生原生原生—转换后使用—规则.md.mdc——steering/—钩子claude.jsonclaude.jsonhooks.json—.kiro/hooks/—命令.md.md/.mdc.toml———MCP 服务器.mcp.json.mcp.jsongemini-extension.json.mcp.jsonmcp.json—UI 元数据———interface 块POWER.md—保真度等级解读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.mdsecurity-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.jsonGemini的hooks.json。钩子可以用在提交代码前自动审查、或在创建新文件后自动添加版权头等场景。规则rules/目录下的文件Claude用.mdCursor用.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/TSRuff 或 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 更新平台市场清单新插件创建后需要“注册”到各个平台的市场中这样它们才能在插件列表里看到它。你需要手动编辑三个根目录文件.claude-plugin/marketplace.json在plugins数组中添加一项。{ plugins: [ // ... 其他已有插件 ... { id: awesome-linter, name: Awesome Linter, path: ./plugins/awesome-linter } ] }.cursor-plugin/marketplace.json进行同样的添加。.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。排查检查必填字段最常见的原因是缺少了某个平台的必填字段。例如OpenAI Codex的plugin.json必须包含interface对象而Claude的则不需要。仔细对比脚手架生成的模板和示例插件skill-evaluator的配置。检查数据类型确保字段值是正确的类型。例如category应该是字符串capabilities应该是数组。使用VS Code辅助如果你在schemas/目录下关联了JSON Schema例如在VS Code的settings.json中配置json.schemas编辑器会直接给你红线提示这是最快的排查方式。5.2 插件在某个平台不显示或无法加载问题在Claude Code里能看到插件但在Cursor里看不到或者反之。排查检查根目录 marketplace.json确认两个平台的marketplace.json文件都正确添加了你的插件条目。路径 (path) 必须正确指向plugins/你的插件名。检查插件清单路径确认plugins/你的插件名/.claude-plugin/plugin.json和.cursor-plugin/plugin.json文件存在且内容有效。虽然它们内容几乎一样但必须存在于各自平台指定的目录下。平台缓存AI开发工具有时会缓存插件列表。尝试重启工具或者清除其本地数据具体方法因工具而异。查看工具日志Claude Code和Cursor通常有开发者控制台或日志文件。打开它们搜索你的插件ID或名称看是否有加载错误信息。5.3 技能或代理在 Gemini/Kiro 上行为异常问题在Claude上工作正常的技能到了Gemini CLI或Kiro上无法被调用或结果不对。排查工具名映射这是最常见的问题。你的代理.md文件中如果引用了Read,Write等工具在构建给Gemini时src/build-standalone.ts脚本会将其映射为read_file,write_file。请检查dist/gemini/插件名/agents/下生成的.md文件确认映射是否成功。如果没有可能是脚本的映射表需要更新。功能不支持确认你使用的功能在目标平台上是否被支持。例如你在源文件中定义了复杂的钩子 (hooks/)但Gemini CLI的钩子系统可能更简单或者Kiro的钩子实现方式不同。构建脚本可能无法完美转换所有逻辑。此时需要查阅目标平台的官方文档调整你的源实现或者接受功能限制。独立仓库结构对于Gemini和Kiro务必确保dist/下的目录是一个完整的、正确的仓库。特别是gemini-extension.json或POWER.md必须在根目录。检查构建脚本是否遗漏了关键文件。5.4 性能与维护考量问题当插件数量增多、功能变复杂后构建时间变长仓库变得臃肿。优化建议增量构建目前的build:standalone似乎是全量重建。对于大型项目可以考虑修改构建脚本只针对发生变化的插件进行构建。可以通过比较文件哈希来实现。模块化插件将大型插件拆分为多个小型、专注的插件。例如将“代码审查”拆分为“安全审查”、“性能审查”、“风格审查”三个独立插件。这样用户可以根据需要安装也利于单独更新和测试。CI/CD 集成将pnpm run validate和pnpm run build集成到GitHub Actions或GitLab CI中。确保每次推送到主分支或发布标签时自动验证配置并生成最新的dist/产物供自动化部署使用。版本管理模板本身没有强制规定插件版本管理。一个良好的实践是在每个插件的plugin.json中维护version字段并在根目录的marketplace.json中或许可以增加版本信息以便工具能检测到更新。5.5 扩展模板支持新平台场景一个新的AI编程工具X-Studio发布了你想让你的插件也支持它。步骤研究新平台仔细阅读X-Studio的插件开发文档弄清楚它的插件结构、清单格式、支持哪些组件技能、代理、命令等。在模板中添加支持在src/build-standalone.ts中增加一个新的构建目标如果X-Studio需要独立导出。或者在plugins/name/下创建新的配置目录如.xstudio-plugin/如果它像Claude一样直接读取源文件。在src/validate.ts中增加对新平台清单文件的JSON Schema验证。在templates/目录下更新脚手架模板使其能生成X-Studio的配置文件。更新根目录的README.md和平台兼容性矩阵。处理差异这是最复杂的部分。你需要决定如何将现有的“超集”组件映射到X-Studio的模型上。可能需要进行功能裁剪、格式转换或行为模拟。这个过程正是ai-plugin-marketplace-template项目核心思想的体现将平台差异抽象为构建时的转换问题。随着更多平台加入这个模板的构建流水线会变得越来越复杂但也越来越有价值。最后我个人最深的体会是使用这个模板前期需要投入时间理解其设计理念和各个平台的差异但一旦跑通后续的插件开发和维护效率会得到质的提升。它迫使你以一种更结构化、更声明式的方式思考AI插件的功能这本身也是对插件设计的一种锻炼。在AI工具快速演进的今天这种面向“适配层”的开发思路或许是应对生态碎片化的一种有效策略。