devetai/better-plugin-gen

Better Plugin Generator (better-plugin-gen)

此技能帮助用户创建一个插件：一个打包了 skill、agent、hook、MCP 服务器等多个组件（component）的目录，以便通过一条命令安装到编码代理中。技能支持三个主机（加载插件的代理工具）：Claude Code、Codex 和 Antigravity。每个主机有各自的 manifest；技能使用统一的 skills/ 目录，并为所选主机生成对应的 manifest。

下文中的所有路径 template.md、references/、examples/、scripts/ 均相对于包含 SKILL.md 文件的目录。

---

1. 核心原则

1. 先问后写。 所有选择都通过结构化提问工具向用户询问（如果会话支持）；否则，列出带编号的选项、标明推荐选项，并等待用户回复。每次提问前，简要说明：即将创建的插件有何用途、问题是什么以及为什么会有这个问题。不得自行填写不明确的点并生成文件。
2. 不猜测主机规范。 文件位置、manifest 格式以及 MCP 配置以 references/hosts.md 为准。对于标注为“未经核实”的点，必须告知用户。
3. 主要逻辑放在 skill 中。 Skill 是唯一能在三个主机上运行的组件。Agent、command、hook、LSP 仅在用户需要且主机支持时添加。
4. 最小可运行框架。 生成的每个组件必须能立即运行，但要尽量简洁。如果项目中有 better-skill-gen 或 better-agent-gen 技能，建议用户在插件运行后使用它们来完善 skill 或 agent。
5. 自动验证。 仅当 scripts/validate.sh 返回退出码 0 时，插件才能交付。
6. 无外部副作用。 技能仅写入目标插件目录（如果用户选择创建 marketplace，则在仓库根目录写入 marketplace 文件）。不执行 git commit、git push，不安装插件，不修改用户主机配置；仅打印让用户自行执行的命令。

---

2. 输入

• 必填： 插件的用途（一句话即可），或已有插件目录的路径（如需添加组件）。从用户需求中获取。
• 若未提供则询问： 目标主机、目录位置、组件列表、是否创建 marketplace、插件名称、作者、许可证。
• 信息缺失： 按照第 3 节步骤 2 进行询问；无回复则等待。

---

3. 流程

步骤 1：确定模式并读取当前状态

• 新建： 用户描述插件，尚无目录。
• 添加组件 / 添加主机： 用户提供包含 .claude-plugin/plugin.json、.codex-plugin/plugin.json 或 plugin.json 的路径。读取所有 manifest，列出已有组件，运行 shell 命令 bash scripts/validate.sh <dir> 以了解在修改前已存在的错误。
• 创建 marketplace： 用户已有插件，仅需发布。如上读取插件，然后转到步骤 6。
• 读取 references/hosts.md。如果 验证日期 超过 30 天，或者插件需要文件中尚未有的功能：访问该文件第 6 节中列出的网络来源，更新文件并修改验证日期，然后告知用户所做的更改。

步骤 2：询问用户

总结已理解的内容（插件用途、谁用它、何时运行），然后进行第一轮提问，跳过用户已明确回答的问题：

问题	类型	选项（推荐排首位）
插件在哪个主机上运行？	多选	Claude Code; Codex; Antigravity。如果插件仅包含 skill 和 MCP，建议选全部三个；如果需要 hook、LSP 或 userConfig，仅选 Claude Code
插件放在哪里？	单选	独立仓库，插件位于根目录（./<名称>/）；在 marketplace 仓库内（plugins/<名称>/）；在当前项目中用于测试
插件包含哪些组件？	多选	Skill; Agent; Hook; MCP 服务器; Command; LSP; userConfig
是否需要创建 marketplace 用于发布？	单选	需要，针对所选主机；暂时不需要，仅在本地测试

第二轮（如需）：插件名称（建议根据描述生成 kebab-case 名称）、作者和 GitHub 仓库所有者、许可证、每个组件的详细信息（skill 做什么、agent 可使用哪些工具、hook 在什么事件下运行、哪个 MCP 服务器以及是否需要令牌）。

询问规则：

• 用户为非 Claude Code 的主机选择了 hook：预先提示 references/hosts.md 第 4 节中的冲突，询问是否保留 hook。
• 插件需要令牌或密码：询问提供方式（Claude Code：userConfig 中设置 sensitive: true；其他主机：在 README 中记录环境变量）。绝不允许将秘密值写入任何文件。
• 名称与 Claude Code 的禁用名称冲突（references/hosts.md 第 2.1 节）：建议其他名称。
• 目标目录已有文件：列出将被覆盖的文件，并在写入前询问。

步骤 3：确认设计

在聊天中撰写简要总结：名称、主机、位置、将创建的目录树（标注每个文件所属的主机）、每个组件在哪些主机上运行、agent 自动设置的值、未经核实的点。如果回答产生了新的不明确点，则继续提问，暂不生成文件。

步骤 4：生成文件

1. 读取 template.md（每个文件的框架）和 references/components.md（每个组件的格式）。阅读 examples/sample.md 以了解期望的详细程度。
2. 为每个所选主机生成 manifest。name、version、description 在所有 manifest 中相同。
3. 将组件放在插件根目录，而不是 .claude-plugin/ 或 .codex-plugin/ 内：
   • Skill：skills/<名称>/SKILL.md，frontmatter 只包含 name 和 description，以便所有主机读取。
   • MCP：Claude Code 和 Codex 使用 .mcp.json；Antigravity 使用 mcp_config.json（远程服务器使用 serverUrl）。两个文件包含相同的服务器列表。
   • Hook：hooks/hooks.json 包含在 "hooks" 键中，始终包含 matcher，使用 "${CLAUDE_PLUGIN_ROOT}"（Claude Code 的变量）调用脚本。脚本放在 scripts/ 中，带有 shebang。
   • Agent、command、LSP、userConfig：按照 references/components.md。
4. 使用文件 8 的框架生成 README.md，至少 40 个字，包含按主机划分的组件表格以及针对每个主机的安装命令（references/publishing.md 第 5 节）。
5. 添加组件模式：仅添加新文件，并修改 manifest 中需要修改的键；如果插件已发布，则增加所有 manifest 的 version（补丁版本）。

步骤 5：自动验证

1. 运行 shell 命令 HOSTS="<所选主机>" bash scripts/validate.sh <插件目录或仓库>。例如 HOSTS="claude codex antigravity"。
2. 脚本运行 check_plugin.py（检查 manifest、名称、路径、MCP、hook、skill、agent、marketplace、占位符、类似秘密的字符串），然后如果机器上有 claude plugin validate 和 agy plugin validate 命令，则依次运行它们。
3. 如果存在 [FAIL] 或 CLI 报错：修改文件，重新运行直到退出码为 0。
4. 阅读每个 [WARN]：如果可修复则修复；如果保留（例如已告知用户的多主机 hook 警告），则在交付报告中记录原因。
5. 如需临时文件，则写入用户指定的临时目录，否则使用操作系统临时目录；验证完成后立即删除。

步骤 6：Marketplace（如果选择）

• Claude Code：在仓库根目录创建 .claude-plugin/marketplace.json（文件 9 的框架）。
• Codex：在仓库根目录创建 .agents/plugins/marketplace.json（文件 10 的框架）。
• Antigravity：无需文件；在 README 中添加 agy plugin install 命令及 GitHub 仓库 URL，例如 https://github.com/phucbui/pr-review-kit。
• 使用仓库根目录重新运行步骤 5，验证 marketplace。

步骤 7：交付

按照 template.md 末尾的“交付报告”框架打印报告：目录、主机、验证结果、文件列表、未经核实的点、在本地测试的命令、供用户自行执行的发布命令（references/publishing.md 第 3 至 6 节）。如果项目中有 better-skill-gen 或 better-agent-gen，提供一行如何使用它们完善组件的建议。

---

4. 约束

• 必须：
  • 在生成文件之前询问主机、位置、组件和 marketplace；不得自行决定不明确的点。
  • 仅写入目标插件目录和仓库根目录中的 marketplace 文件；不得在其他地方创建示例文件。示例仅存放在本技能的 examples/ 目录中。
  • 不执行 git commit、git push、claude plugin install、agy plugin install、codex plugin marketplace add；仅打印命令。
  • 不得将令牌、密码、API 密钥写入任何文件。
  • 仅当 scripts/validate.sh 退出码为 0 时才能交付。
• 应该：
  • 为插件、skill、agent 使用 kebab-case 命名；初始版本为 0.1.0。
  • 保持插件专注于一个目的；如果用户将不相关的功能打包在一起，建议拆分。
  • 在 README 中明确说明哪些组件运行在哪些主机上。
• 不应：
  • 不要将包含 Claude Code 专有字段的 SKILL.md 直接复制到用于 Codex 或 Antigravity 的插件中。
  • 不要在 manifest、hook、MCP 中使用绝对路径或 ..。
  • 不要在插件根目录放置 CLAUDE.md；如果需要在加载时提供指导，将其放入 skill 中。