作者：来自 Elastic Sean Story
将你的 Claude 插件指向 main 分支，每次合并都会发布一个新版本，而这竟然是从提交到上线期间最不令人意外的一件事。
Elasticsearch 原生集成了业界领先的生成式 人工智能 工具和服务提供商。欢迎观看我们的网络研讨会，了解如何借助 Elastic 向量数据库超越检索增强生成的基础应用，或构建可用于生产环境的应用。
要为你的使用场景构建最佳搜索解决方案，立即开始免费云端试用，或在你的本地计算机上试用 Elastic。
以前，如果你在 Claude 中寻找 Elastic，你是找不到我们的：
我们想改变这种情况！这篇博客讲述了我们发布一款插件的故事，它将 Elastic 的能力带入开发者日常使用的工作环境。我们已经有了 elastic/agent-skills 代码仓库，也为这些技能撰写了博客和编写了文档，但官方 Claude 插件能让我们的客户更轻松地使用这些技能。
走到这一步并不容易。一路上，我们学到了很多，也想分享我们的经验。
从首次提交代码到正式上线，我们花了三周时间。Claude 文档帮我们完成了其中的 80%，剩下的 20% 则涉及文档中未提及的审核标准，以及一种每次提交都会发布新版本的版本管理模式。至于插件何时会出现、会出现在哪里，我们能了解到的信息十分有限。
以下是我们的收获：
Agent 技能与 Claude 插件：为什么我们两者都需要
在查阅所有参考资料的过程中，我们意识到，我们的 agent 技能只是 Claude 插件可以包含的一部分内容。虽然 agent 技能是一项通用的开放标准，已被主要的 agent 厂商和生态系统采用，但 Claude 插件可以包含的内容要丰富得多；不过，其中一些内容可能无法同样通用于各个平台。Claude Code 文档中的一个示例：
这里包含的内容远不止技能，我们也希望为日后扩展这些功能留出空间。
因此，我们决定为 Claude 插件新建一个代码仓库。这样，所有 Claude 专属功能就都有了归属，也能与我们的通用 agent 技能分开管理。elastic/claude-plugin 代码仓库就此诞生。
向 Claude 目录提交插件
Claude 的文档很详尽，我就不在这里一一赘述了，不过，你可以参考以下文档：
我们仔细阅读了上述文档，并确保完成了检查清单中的所有事项。但当我尝试在 App unavailable in region | Claude by Anthropic 提交插件时，却收到了以下提示：
我是一名工程师，一名独立贡献者。对于一个大多数 Elastic 员工都在使用的软件工具，我实在不该担任其账户的 "所有者"。但负责管理该账户的信息技术团队并不会维护和支持这款面向外部用户的插件。
这是我们遇到的第一个阻碍，但也让我们学到了第一条经验：如果你在 Anthropic 有联系人，就充分利用这一资源。Elastic 此前已与 Anthropic 建立了合作关系，因此遇到这个问题时，我们直接给对接人发了消息，对方很快就回复了我们：
获得所需权限后，填写提交表单就相对简单了：
虽然操作简单，但我们在这里犯了最初的两个错误。
选择插件路径：为什么_不应_使用代码仓库根目录
如上方截图所示，Anthropic 会在这个文件夹中查找你的 .claude-plugin/plugin.json 文件。它也是 Anthropic 自动化系统扫描的根目录。
我们最初使用默认的"代码仓库根目录"作为插件路径，但这是个错误，因为供我们内部开发使用的文件也放在代码仓库根目录下。其中包括供工程师维护插件时使用的 CLAUDE.md，以及 持续集成 流水线、测试和 package-lock.json 文件。
扫描这些文件可能导致验证过程意外受阻：
需要说明的是，Anthropic 团队并没有让这个问题阻碍进展，而是在人工审核后忽略了这些警告。
Claude 插件版本管理：为什么我们不再指向 main
软件版本管理或发布并没有唯一"正确"的方式。但在 Elastic，我们通常遵循以下惯例：
- 在功能分支上进行开发，有时也会在派生仓库中开发。
- 拉取请求以
main为目标分支。 - 使用语义化版本号，格式为"主版本号.次版本号.修订号"。
- 从发布分支（
MAJOR.MINOR，即"主版本号.次版本号"）创建发布版本，并添加标签（vMAJOR.MINOR.PATCH，即"v主版本号.次版本号.修订号"）。
初次阅读 Claude 的插件版本管理文档时，我就知道这个代码仓库需要采用不同的机制。我们同一时间只提供一个线上版本，无须同时维护多个主版本和次版本。因此，我们原本打算直接使用 main，并在插件元数据中指定 version（版本号）。我们会像往常一样，将拉取请求合并到 main，等到准备发布时，再递增这个 version，并创建一个 Git 标签。很简单。
但实际机制并非如此：
最初的做法实际上产生了许多个版本号同为 v0.0.1 的插件"版本"，每个合并提交都会生成一个。
在 Anthropic 联系人的帮助下（细心的读者会发现，他们的帮助贯穿始终），我们得到了以下解释：
意识到这一点后，我们将插件改为指向专用的 stable 分支。现在，我们可以照常将代码合并到 main，只有在准备好发布一批变更并更新版本号时，才将 main 合并到 stable。这样，我们的流程就变成了：
提交 Claude 插件后会发生什么
等待。
首次提交后，我们只看到了以下内容：
在我们撰写这篇博客期间，Anthropic 对用户界面做了一些调整，让提交状态更加清晰。现在，提交界面看起来更像这样：
即便如此，我们首次提交插件的审核仍花了大约一周时间，而这可能已经比正常情况更快，因为我们能够直接联系 Anthropic 的解决方案架构师和客户经理（再次强调，这种关系非常有价值）。我们得到的粗略估计是，平均审核时间约为九天。
当时我们无法看到具体情况，但后来得知，审核延迟的部分原因是，我们提交的插件向 Anthropic 审核团队触发了多项警告：
自动审核中的政策警告
回头来看，能看到更多审核信息是件好事；但在当时，这可能会让我做出许多不必要的修改。Anthropic 团队最终豁免了所有这些警告。这里的经验是，先等待审核人员提出具体的操作要求，不要急着解决每一条政策警告，即使它们听起来很严重。
| 警告 | 触发原因 | 处理结果 |
|---|---|---|
| 使用用户计算机上的凭据 | 示例 curl 命令通过环境变量引用凭据。 |
人工审核后豁免，属于误报。 |
| 缺少图标 | 提交时，文档中尚未说明 icon 字段，而且缺少该字段也能通过 claude plugin validate --strict 验证。 |
已豁免。文档现已说明该字段。 |
| 包含下载并运行的命令 | 技能中的指令要求 agent 调用应用程序编程接口并解读响应。 | 人工审核后豁免。 |
警告：使用用户计算机上的凭据
凭据警告指向了一些包含示例 curl 命令的技能，这些命令使用环境变量语法作为凭据的占位符。Elastic 命令行工具经过专门设计，确保凭据绝不会暴露给发起调用的 agent，因此，这份报告起初让我们相当警觉，发现这些都是误报后，我们才松了一口气。
警告：缺少图标
图标警告也让我们感到意外。当时，文档并未说明清单中可以包含 icon 字段，而且我们的持续集成流程已运行过 claude plugin validate --strict .，所以我们知道，即使没有该字段，清单也是有效的。
如今，插件清单：字段参考中_确实_已经说明了 icon 字段。我们认为，这表明 Anthropic 显然正在持续改进插件体验。新字段会不断出现，但 Anthropic 不会因此追溯性地阻止此前未包含这些字段的提交。
警告：包含下载并运行的命令
"下载并运行"警告起初听起来也令人担忧，但仔细检查后发现，它似乎针对的是我们技能中类似下面这样的指令，其中建议调用应用程序编程接口，并说明如何解读响应：
**验证 Kibana 的连通性。**调用 GET kbn:/api/status。如果调用失败，停止操作并显示错误 --- 不要猜测端点或凭据。读取 version.number，确认集群满足 9.4 及以上版本的要求。
意外之喜：你的 Claude 插件已上线
Anthropic 完成审核后，插件立即就对外可见了。我们无须额外确认，也没有预发布区域。我们也没有收到任何上线通知。这确实让我们很意外。我们的插件在某个星期四晚些时候发布，但我星期五没有查看。直到接下来的星期一，我们才意识到它已经上线并对外可见了。对我们来说，这没有造成任何问题（这些技能早在几个月前就已公开），但如果你发布的内容尚未经过充分的实际检验，一定要在提交_之前_完成测试。
你的 Claude 插件究竟会出现在哪里
发布插件并不意味着它会进入所有 Claude 目录。开发者至少可能在以下四个地方查找插件：
| 目录 | 发布后是否可见？ | 如何进入 |
|---|---|---|
| Claude 应用中的设置 > 插件 > 发现界面 | 是 | 在 App unavailable in region | Claude by Anthropic 提交你的插件。 |
| Claude 插件市场（Plugins | Claude Marketplace | Claude by Anthropic、Claude Marketplace | Claude by Anthropic） | 否 | 发布后，由 Anthropic 单独进行验证。 |
| anthropics/claude-plugins-community 代码仓库 | 否 | 发布后，由 Anthropic 单独进行筛选。 |
| anthropics/claude-plugins-official 代码仓库 | 否 | 合作伙伴插件可通过 Anthropic 联系人安排收录。 |
首次发布时，你的插件只会以未经验证的状态出现在 Anthropic 目录中，并标记为"社区"。而且，前提是你的许可或账户设置没有排除未经验证的插件。这起初在我们内部引发了一些困惑（我们的信息技术部门将 Claude 企业版设置为隐藏"社区"插件）；只有不使用工作账户登录时，我们才能看到自己的插件。
要进入其他目录和市场，插件还需要经过单独的"验证"或"标记"流程。与 Anthropic 合作伙伴私下沟通再次发挥了很大作用：
Elastic 的 Claude 插件下一步计划
我们仍在努力让插件通过网页插件市场的验证，并将其安装到 Elastic 自己的 Claude 组织中，让我们的工程师能够在日常工作中试用。这个插件还处于起步阶段，我们想添加的功能还有很多。
但如果我希望你从这篇文章中记住一件事，那就是这个过程中最困难的部分并非技术问题，而是预期与实际情况之间的落差，而每一处落差最终都是通过与真人沟通来弥合的。工具正变得越来越智能，但围绕这些工具建立的社区，依然靠人与人之间的互助来运转。
如果你在发布自己的插件时遇到困难，可以通过我们的 Elastic Stack 社区 Slack 联系我们，或在领英上找到我。也欢迎分享你的经验。插件市场见。
原文：How to publish a Claude plugin: What the docs don't cover | Elasticsearch Labs