plugin-forge

plugin-forge skill 概览

plugin-forge 是一项面向 Claude Code 插件作者的构建与维护 skill，适合那些希望一次把目录结构、manifest 文件和 marketplace 注册都做对，而不是自己重新摸索整套流程的人。它真正解决的问题并不是“写一点 JSON”，而是“交付一个脚手架正确、版本一致、并且能在 marketplace 工作流里顺利安装的插件”。

plugin-forge 最适合哪些人

如果你符合以下情况，建议使用 plugin-forge skill：

• 从零开始创建一个新的 Claude Code 插件
• 给插件补充 commands/、agents/、skills/ 或 hooks/ 等组成部分
• 需要同时更新 .claude-plugin/plugin.json 和 marketplace 元数据
• 在发布前先进行本地插件测试
• 维护一个包含多个插件、采用 marketplace 风格的插件仓库

对于希望获得可重复、可维护结构，而不只是一次性生成内容的开发者来说，它尤其有价值。

plugin-forge 与通用提示词的区别

通用提示词当然也能生成一个插件骨架，但 plugin-forge 额外提供了更实用的约束和护栏：

• 明确的插件目录布局
• 清晰指定 manifest 的位置和字段预期
• marketplace schema 参考
• 本地安装与测试的工作流
• 用于脚手架生成和版本升级的自动化脚本

这组能力之所以重要，是因为插件最常见的失败点往往不是代码质量，而是结构不一致或元数据对不上。

plugin-forge 实际覆盖了什么

从仓库内容来看，plugin-forge 的核心主要围绕以下内容展开：

• scripts/create_plugin.py：用于创建新插件脚手架
• scripts/bump_version.py：用于同步更新版本号
• references/plugin-structure.md：说明目录和 manifest 布局
• references/marketplace-schema.md：说明 marketplace 条目规则
• references/workflows.md：说明创建、测试和发布流程

所以它更像是“实现指南 + 辅助工具”，而不是一份泛泛而谈的理论文档。

plugin-forge 在 Code Generation 场景下什么时候特别合适

当你希望模型生成的文件必须准确落进正确的插件结构中时，plugin-forge for Code Generation 会特别有用，例如：

• 生成一个带合法元数据的新插件骨架
• 往现有插件里新增 command 或 skill
• 更新 plugin.json 的同时同步修改 marketplace 条目
• 为发布做准备，包括 semantic version 升级

如果你的核心需求只是给一个已经正常工作的插件补业务逻辑代码，那么 plugin-forge 的帮助通常不如更垂直的领域编码 skill 明显。

如何使用 plugin-forge skill

plugin-forge 的安装上下文

上游的 SKILL.md 没有直接提供自己的安装命令，因此具体安装方式取决于你当前环境是怎样加载 skills 的。如果你使用的是该仓库提供的 skill bundle，一个常见写法是：

npx skills add softaworks/agent-toolkit --skill plugin-forge

安装之后，当你的任务涉及插件创建、manifest、marketplace 注册、本地测试或版本管理时，就可以调用 plugin-forge。

先读这些文件，能最快上手 plugin-forge

如果你想尽快进入可用状态，建议按这个顺序阅读：

1. skills/plugin-forge/SKILL.md
2. skills/plugin-forge/references/plugin-structure.md
3. skills/plugin-forge/references/marketplace-schema.md
4. skills/plugin-forge/references/workflows.md
5. skills/plugin-forge/scripts/create_plugin.py
6. skills/plugin-forge/scripts/bump_version.py

这条路径能让你先知道“这个 skill 是干什么的”，再理解预期的文件布局、marketplace 约定，最后再看可以直接运行的辅助脚本。

plugin-forge 需要你提供哪些输入

当你提供的是具体的仓库和发布上下文，而不是一句“给我做个插件”时，plugin-forge 的效果会明显更好。至少应当说明：

• 插件名称，使用 kebab-case
• marketplace 根路径
• 插件用途
• 作者姓名和邮箱
• 初始关键词
• 分类
• 是否需要 commands、agents、skills、hooks 或 MCP 配置
• 这是新插件，还是对现有插件做更新

如果缺少这些信息，模型依然能产出草稿，但通常还需要不少手工收尾。

把模糊目标改写成更强的 plugin-forge 提示词

较弱的提示词：

Create a Claude Code plugin for my project.

更强的提示词：

Use plugin-forge to scaffold a new Claude Code plugin named schema-audit inside /repos/internal-marketplace. Author is Jane Doe <jane@example.com>. Description: “Validate JSON and OpenAPI schemas in CI.” Keywords: schema,openapi,json,validation. Category: developer-tools. Include commands/ and skills/, but no hooks yet. Generate the expected folder layout, plugins/schema-audit/.claude-plugin/plugin.json, the matching .claude-plugin/marketplace.json entry, and a short README. Follow the marketplace and plugin structure references.

第二种写法给了 plugin-forge 足够完整的信息，生成出来的文件会更接近可直接使用的状态。

想要更快，就直接用脚手架脚本

如果你的元数据已经明确，与其手工搭初始目录，不如直接使用辅助脚本：

python scripts/create_plugin.py plugin-name \
  --marketplace-root /path/to/marketplace \
  --author-name "Your Name" \
  --author-email "your.email@example.com" \
  --description "Plugin description" \
  --keywords "keyword1,keyword2" \
  --category "productivity"

如果你更在意“先把结构搭正确”，而不是手工精雕每个脚手架细节，这是最快的路径。

用版本脚本避免 manifest 漂移

plugin-forge 最实用的一点之一，就是它考虑了同步版本管理。skill 内置了 scripts/bump_version.py，会同时更新：

• plugins/<plugin-name>/.claude-plugin/plugin.json
• .claude-plugin/marketplace.json

示例：

python scripts/bump_version.py plugin-name patch \
  --marketplace-root /path/to/marketplace

这很关键，因为这两个文件版本号不一致，是插件维护中非常常见的失误。

按照 plugin-forge 的实际工作流来走

一个更稳妥的 plugin-forge 使用流程通常是：

1. 先生成插件脚手架
2. 检查生成的 plugin.json
3. 核对 .claude-plugin/marketplace.json 里的 marketplace 条目
4. 再补充 command、skill 等组件
5. 通过 marketplace 安装流程做本地测试
6. 迭代修改
7. 发布前执行版本升级

相比用一个超长提示词一次性把所有事都丢给模型，这种流程更可靠。

本地测试流程要尽早纳入规划

参考文档里给出了明确的本地测试路径：

/plugin marketplace add /path/to/marketplace-root
/plugin install plugin-name@marketplace-name

这意味着你在设计提示词时，就应该让 plugin-forge 输出“可安装的路径和元数据”，而不是只生成描述性文件。只要源路径或插件名不一致，测试会立刻失败。

plugin-forge 常会修改的关键文件

在真实使用中，可以预期 plugin-forge 会创建或编辑这些内容：

• plugins/<plugin-name>/.claude-plugin/plugin.json
• .claude-plugin/marketplace.json
• plugins/<plugin-name>/README.md
• plugins/<plugin-name>/commands/
• plugins/<plugin-name>/agents/
• plugins/<plugin-name>/skills/
• plugins/<plugin-name>/hooks/hooks.json
• plugins/<plugin-name>/.mcp.json

这一点对评审安排很有帮助，因为 plugin-forge 往往不是改一个文件，而是一次生成一组跨文件变更。

提升 plugin-forge 输出质量的实用技巧

你可以明确要求 plugin-forge：

• 严格保留现有插件名称和路径
• 所有标识符统一使用 kebab-case
• 同时展示插件 manifest 和 marketplace 条目
• 对无法推断的必填字段单独说明
• 把“generated files”和“manual follow-up”分开列出
• 校验不同 manifest 里的版本号和名称是否一致

这些要求能明显降低“看起来完整、实际上不能安装”的产出概率。

plugin-forge skill 常见问题

如果我本来就很会写提示词，还值得用 plugin-forge 吗？

值得，前提是你的主要风险在于结构正确性。只要你需要 manifest、一致的 marketplace 条目和标准目录布局，plugin-forge 通常就比普通提示词更有价值。反过来说，如果你只是想在现有插件里补一个 command 文件，它的优势就没有那么明显。

plugin-forge 对新手友好吗？

大体上是友好的。plugin-forge 能给新手一条比较具体的插件创建和测试路径。问题在于，新手仍然需要搞清楚自己的 marketplace 根目录、命名规范，以及到底需要哪些组件。它更擅长帮你把结构搭对，而不是替你做产品设计。

什么情况下不该用 plugin-forge？

以下场景建议跳过 plugin-forge：

• 你构建的不是 Claude Code 插件
• 你不使用 marketplace 风格的分发方式
• 你只需要通用的 Python 或 JavaScript 代码生成
• 你的仓库有一套刻意不同于文档约定的自定义插件布局

在这些情况下，plugin-forge 反而可能把你往错误的结构上带。

plugin-forge 会自动处理发布吗？

不会完全自动化。它对发布前准备工作支持得很好，包括脚手架、manifest、marketplace 注册、本地测试指引以及版本更新。但它不是一套端到端的发布平台。你仍然需要自己审查文件、做本地测试，并执行自己的发布或分发流程。

最大的采用门槛是什么？

通常是仓库上下文不完整。plugin-forge 默认你知道 marketplace 根目录在哪里，也知道插件应该归到哪个分类。如果这些问题你答不上来，那么输出结果大概率仍然只是草稿级，而不是可直接投产的版本。

plugin-forge 和手动编辑 manifest 相比怎么样？

如果只是偶发的一次性修改，手动编辑当然可行。但如果你追求可重复性，或者想避免 plugin.json 和 marketplace.json 之间逐渐失配，plugin-forge 会更合适。它附带的脚本，就是最直接的实际优势。

如何改进 plugin-forge skill 的使用效果

给 plugin-forge 提供带仓库上下文的输入

最有效的改进方式，就是提供精确路径和当前文件状态。不要只说“做一次版本升级”，而可以这样说：

Use plugin-forge to bump schema-audit in /repos/internal-marketplace from its current version using a minor change. Check both plugins/schema-audit/.claude-plugin/plugin.json and .claude-plugin/marketplace.json, then show the diff.

这种写法会把 skill 推向“可验证的具体改动”，而不是泛泛建议。

让 plugin-forge 按文件输出，而不只是给摘要

当你要求的是明确交付物，而不是概括说明时，plugin-forge 的表现会更好，例如：

• 完整的 plugin.json
• 精确的 marketplace 条目
• 建议的目录树
• README 初稿
• 本地测试的后续命令

这一点对 plugin-forge for Code Generation 尤其关键，因为它的价值就在于生成“可以直接落地”的文件。

提前防住最常见的失败模式

使用 plugin-forge 时，重点检查这些问题：

• 插件名在不同文件中不一致
• marketplace 的 source 路径与实际目录布局不匹配
• 版本只更新了一个 manifest，另一个没改
• 元数据里引用了可选组件，但实际没有创建
• 生成结构里漏掉 .claude-plugin/plugin.json

只要快速对照一下 references/plugin-structure.md 和 references/marketplace-schema.md，大多数这类问题都能及时发现。

用两轮工作流，plugin-forge 通常会更稳

实践中，一个更强的 plugin-forge 使用方式是：

1. 第一轮：生成结构和 manifest
2. 第二轮：生成插件组件并改进 README

如果你试图在一个提示词里同时完成脚手架、业务逻辑、文档、测试配置和发布说明，质量通常会下降。plugin-forge 最擅长的，仍然是先把结构做对。

首轮输出后，用定向修正继续迭代

不要只说“修一下”。更有效的做法是给出明确修复指令，例如：

• “Regenerate marketplace.json entry so source points to ./plugins/schema-audit.”
• “Add skills/ to the tree and keep manifest fields unchanged.”
• “Update only version fields; do not rewrite descriptions or keywords.”
• “Align the plugin name to kebab-case everywhere.”

这种带约束的迭代方式，会让 plugin-forge 可靠得多。

把 plugin-forge 和参考文档配合使用，而不是相互替代

想提升 plugin-forge 输出质量，最好的办法之一，是在提示词里明确要求它引用或遵循仓库内的参考文档。你可以直接提到：

• references/plugin-structure.md：用于约束目录结构
• references/marketplace-schema.md：用于约束 marketplace 字段
• references/workflows.md：用于约束安装与测试流程

这样能让 skill 锚定在仓库实际采用的约定上，而不是退回到泛化的插件假设。