把Elasticsearch塞进Claude插件有多坑？80%问题靠文档解决，20%暗坑靠人脉，每次合并都自动发版

以前，如果您在 Claude 中搜索 Elastic，是找不到我们的：

在将 Claude 插件发布到目录之前，Claude Marketplace 中搜索 Elastic 没有返回任何插件

我们想要改变这一状况！这篇博客讲述的是一个插件的发布历程——它把 Elastic 的能力带到了开发者日常工作的环境中。我们之前已经有 elastic/agent-skills 仓库，并且既写过相关博客，也提供了相应文档，但官方 Claude 插件能让我们的客户更便捷地使用这些技能。

Elastic 插件出现在 Claude 应用的插件设置中，通过搜索 Anthropic 目录中的 elastic 找到

走到这一步实属不易。一路上我们学到了很多经验，也想借此机会分享出来。

从第一次提交到正式上线，我们花了三周时间。Claude 的文档解决了我们 80% 的问题，其余 20% 则是文档中未提及的审核标准，以及一个每次提交都会触发新发布的版本模型。插件会在何时、何地出现，我们几乎没有可见性。

以下是我们学到的经验：

Agent Skills 与 Claude 插件：为什么两者都需要

在通读所有参考资料的过程中，我们意识到我们的 Agent Skills 只是 Claude 插件所能包含内容的一部分。虽然 Agent Skills 是一个被主要智能体厂商和生态系统广泛采用的通用开放标准，但 Claude 插件可以包含更多内容；不过，其中有些内容可能无法在不同平台上通用。以 Claude Code 文档中的一个示例为例：

Claude 插件文件夹结构，显示 .claude-plugin/plugin.json 以及 skills、commands、agents 和 hooks

这里面包含的内容远不止 skills，而且我们希望为这些功能留出扩展空间。

因此我们决定为 Claude 插件新建一个独立的仓库。这样，我们就有了一个专门存放所有 Claude 特定功能的地方，与我们的通用 Agent Skills 分开管理。elastic/claude-plugin 仓库由此诞生。

向 Claude 目录提交插件

Claude 的文档非常详尽，我在此不再赘述，但供您参考，可以阅读以下内容：

• 发布到目录
• 插件提交前检查清单
• 构建您的第一个插件

我们按照上述文档逐一核对了检查清单上的所有项目。但当我尝试在 https://claude.ai/directory/manage 提交插件时，却收到了以下提示：

Claude 错误信息：您没有访问组织设置的权限，导致无法提交 Claude 插件目录

我是一名工程师，一名普通研发人员。我没有资格成为这个被大多数 Elastic 员工使用的软件工具的账户“所有者”。然而，负责管理该账户的 IT 团队却不负责维护和支持这个面向外部的插件。

这是我们的第一处摩擦，但也给我们带来了第一个教训：如果您有 Anthropic 的联系人，一定要好好利用。 Elastic 此前已经与 Anthropic 建立了合作伙伴关系，所以当我们遇到这个问题时，只需给联系人发个消息，对方很快就回复了我们：

Anthropic 在 Slack 上的回复，解释了为插件提交配置具有目录管理权限的自定义角色

拿到正确权限后，填写提交表单就相对简单了：

Claude 插件提交流程表单字段：仓库、插件路径以及目录所跟踪的分支或标签

尽管表单很简单，但正是在这里，我们犯了前两个错误。

选择插件路径：为什么 不 用仓库根目录

如上面的截图所示，这里就是 Anthropic 查找您的 .claude-plugin/plugin.json 的文件夹，也是 Anthropic 自动化系统将要扫描的根目录。

我们一开始使用了默认的 仓库根目录 作为插件路径，但这是一个错误，因为用于我们内部开发目的的文件也在仓库根目录下。其中包括我们的工程师可以用来维护插件的 CLAUDE.md，以及我们的持续集成（CI）流水线、测试文件和 package-lock.json。

扫描这些文件可能会导致验证过程中出现意外的卡顿：

Claude 目录策略对 package-lock.json 的保留提示，标记了从锁文件安装的依赖

需要说明的是，Anthropic 团队并没有让这成为阻塞项，经过人工审核后，这些警告被豁免了。

Claude 插件版本管理：为什么我们不再指向 main 分支

软件的版本管理和发布方式没有统一的“标准答案”。但在 Elastic，我们通常遵循以下约定：

• 开发在功能分支上进行（有时在 fork 中）。
• Pull Request（PR）合并到 main 分支。
• 版本管理使用 SemVer（MAJOR.MINOR.PATCH）。
• 发布从发布分支（MAJOR.MINOR）拉出，并打上标签（vMAJOR.MINOR.PATCH）。

在我初次阅读 Claude 的插件版本管理文档时，我就知道这个仓库需要一套不同的体系。我们同一时间只维护一个线上版本，而不是同时维护多个主版本和次版本。所以我们计划直接使用 main 分支配合插件元数据中的特定 version 字段。像平常一样将 PR 合并到 main，准备发布时再更新 version 并创建 Git 标签。简单明了。

但实际运行起来并非如此：

Claude 插件版本列表，显示每次提交的定时检查导致的重复 v0.0.1 策略保留

这种初始做法实际上产生了许多 v0.0.1“版本”的插件——每次合并提交都对应一个版本。

在 Anthropic 联系人的帮助下（细心的读者应该已经注意到，这已经成为一个主题了），我们得到了如下澄清：

Anthropic 解释 version 字段并不会选择提交点，建议使用发布分支而非 main 分支

意识到这一点后，我们修改了插件配置，将其指向一个专用的 stable 分支。现在我们可以照常合并代码到 main，但只有在准备好发布一批变更并更新版本号时，才会将 main 合并到 stable。这样我们的流程就变成了：

Claude 插件分支模型：功能分支合并到 main，main 合并到 stable 分支并为发布打上标签

提交 Claude 插件之后会发生什么

等待。

我们第一次提交后，看到的内容只有这些：

Claude 插件仪表板，显示 Elastic 插件在提交十分钟后处于已提交待审核状态

在我们撰写这篇博客的过程中，Anthropic 对界面做了一些调整，提供了更多可见性。现在提交界面看起来更像是这样：

更新后的 Claude 插件仪表板，显示了已提交、安全扫描、已批准和已发布的审核时间线

即便如此，我们首次插件提交的审核大约花了一周时间，而之所以这么快，可能是因为我们能直接联系到 Anthropic 的解决方案架构师和客户经理（再次强调这种关系有多么宝贵）。对方给出的平均审核时间大约是九天。

我们当时看不到原因，但后来才知道，部分延误是因为我们的提交向 Anthropic 审核团队触发了大量警告：

Claude 插件审核日志，显示针对凭据、缺失图标和下载并运行命令的策略警告

自动化审核产生的策略警告

回过头来看，这些额外的可见性确实不错；但在当时，我可能已经因此做了一堆不必要的修改。Anthropic 团队最终豁免了所有这些警告。这里要吸取的教训是：等待审核人员的明确指示，而不是一看到策略警告就急着去解决所有问题，哪怕这些警告听起来很严重。

警告：使用了用户机器上的凭据

凭据警告指向的是包含示例 curl 命令的技能，其中凭据以环境变量语法进行了模板化。Elastic CLI 经过特别设计，确保凭据永远不会暴露给智能体调用方，因此我们起初对这个报告非常警觉，后来发现是误报，这才松了一口气。

警告：缺少图标

图标警告同样让我们感到意外。当时，没有任何文档说明 icon 字段可以作为 manifest 的一个选项，而且我们的 CI 已经运行了 claude plugin validate --strict .，所以我们清楚没有该字段的 manifest 也是有效的。

如今，插件 manifest：字段参考确实记录了 icon。我们认为这标志着 Anthropic 正在明显迭代插件体验。新字段不断出现，但 Anthropic 不会追溯性地阻止未使用这些字段的提交。

警告：包含下载并运行的命令

下载并运行警告最初听起来也很让人担忧，但仔细检查后发现，它针对的是我们技能中的一些指令——这些指令建议调用 API，并指导如何解析响应，例如：

**验证 Kibana 连接。**调用 `GET kbn:/api/status`。如果调用失败，请停止并返回错误信息——不要猜测端点或凭据。读取 `version.number` 以确认集群满足 9.4+ 版本要求。

惊喜：您的 Claude 插件已上线

Anthropic 完成审核后，插件立即变为可见状态。这不需要我们额外的确认步骤，也没有暂存区域。我们同样没有收到任何上线通知。这让我们感到非常意外。我们的插件是在周四晚上发布的，但周五我没有去查看。直到下周一我们才意识到插件已经上线且可见了。在我们的案例中这没有造成什么损害（这些 skills 已经公开了好几个月），但如果您发布的不是经过充分打磨的内容，请务必在提交之前完成所有测试工作。

您的 Claude 插件实际出现在哪里

发布并不意味着您的插件会出现在每个 Claude 目录中。开发者可能会在至少四个地方寻找插件：

当插件最初发布时，它只会以未验证状态出现在 Anthropic 目录中，并被标记为“社区版”。这只适用于您的许可证或账户未配置为排除未验证插件的情况。这在我们内部引发了一些困惑（我们的 IT 部门将 Claude Enterprise 设置为隐藏“社区”插件）；只有当我们未使用工作账号登录时，才能看到我们自己的插件。

要进入其他目录和市场，插件需要通过单独的“验证”或“标记”流程。在这里，与 Anthropic 合作伙伴的私信交流再次发挥了极大作用：

Anthropic 在 Slack 上的回复，解释 claude.com/marketplace 只列出被标记为已验证的 Claude 插件

Elastic Claude 插件的后续计划

我们仍在努力推进插件的 Web 市场验证，并计划将其安装到 Elastic 自己的 Claude 组织中，以便我们的工程师进行内部试用（dogfooding）。这个插件还很年轻，我们希望能添加许多新功能。

但如果您要从这篇文章中带走一个信息，那就是：这个过程中最困难的部分并非技术问题。而是预期与现实之间的差距，而每一个这样的差距都是通过与真实的人交流来弥合的。工具越来越智能，但围绕这些工具的社区仍然是靠人与人之间的互助运转的。