1. 基本信息
| 项目 | 内容 | 数据来源 |
|---|---|---|
| 名称 | elasticsearch-esql（所属仓库自述名称为 “Elastic Agent Skills”，与正式名称不一致，故单列记录） | GitHub API / 仓库 README |
| 作者/维护者 | Elastic（elastic/agent-skills 官方仓库） |
GitHub API |
| 来源链接 | https://github.com/elastic/agent-skills/tree/main/skills/elasticsearch/elasticsearch-esql | — |
| 许可证 | 仓库整体 Apache License 2.0；该技能 package.json 另单独声明 license 字段为 “Elastic-2.0”（源码可见但非 OSI 认可的完全开源许可，对作为托管服务转售有限制）——两层 License 口径不完全一致 |
GitHub API + 仓库文件 |
| GitHub Stars / Forks | 所属仓库 535★ / 41 forks（注：该数字属整个技能合集，不代表本技能个体热度，仅供了解所属仓库规模） | GitHub API |
| 最新版本 | SKILL.md 标注 v0.3.0（2026-05-28 发布） | 仓库文件 |
| 安装方式 | 推荐 npx skills add elastic/agent-skills --skill elasticsearch-esql 精确安装单个技能；亦可通过 Claude Code / GitHub Copilot 插件市场安装整组 Elasticsearch 技能 |
仓库文档 |
2. 功能介绍与亮点
elasticsearch-esql 是 Elastic 官方出品的技能，教 Claude Code 等 agent 正确生成 ES|QL（Elasticsearch 管道式查询语言）查询：
- 强制 Schema 探查：执行查询前必须先用配套 CLI（
scripts/esql.js）列出 index、探查字段结构，杜绝凭空猜测字段名 - 按意图匹配生成规则：日志过滤、时间序列聚合（
TS/TBUCKET/RATE）、日志模式聚类（CATEGORIZE）、异常检测（CHANGE_POINT）、全文检索（MATCH/QSTR/KQL）、多表关联（LOOKUP JOIN）均有专门的生成指引与示例 - PromQL 兼容命令：内置
PROMQL源命令（9.4+ 预览版），可直接执行 Prometheus 风格语法并接入 ES|QL 管道做二次处理，方便从 Prometheus/Grafana 迁移过来的团队 - 版本感知：自动识别 Serverless / 自托管 / Snapshot 集群类型，按各版本 ES|QL 特性可用性调整生成策略，避免生成目标集群不支持的语法
亮点：官方出品、配套 10 份专项参考文档；README 专辟安全考量章节，主动提示 prompt injection 风险。
3. 适用场景
固定分类：数据分析与可视化
- 已在生产或本地环境运行 Elasticsearch/Kibana、想让 Claude Code 直接查日志、聚合指标而不必手写 ES|QL 语法的团队
- 从 Prometheus/Grafana 迁移到 Elastic 可观测性栈、需要把已有 PromQL 查询转成 ES|QL 的 SRE
- 需要用自然语言驱动生成时间序列分析（异常检测、日志模式聚类）的数据分析师
- 从 SQL 或 Kibana Query DSL 背景转向 ES|QL、担心 LLM 按 SQL 语感生成“看起来对但解析失败”查询的开发者
4. 跨 Agent 兼容性
- Claude Code：原生支持——官方插件市场一条命令安装（
claude plugin install elasticsearch@elastic-agent-skills） - Codex：支持——官方博客与文档将 Codex 列为兼容运行时之一，第三方安装工具
npx skills亦提供--agent codex参数 - OpenClaw：未验证——Elastic 官方材料未提及，但技能遵循开放的 Agent Skills 标准，第三方安装工具在目录结构上支持该平台
- Hermes Agent：未验证——同上，官方材料未提及，仅第三方安装工具在结构上支持
（仅基于已抓取材料判断，未为兼容性单独发起搜索）
5. 推荐理由
ES|QL 管道语法与 SQL、传统 Query DSL 都不同，LLM 常凭 SQL 语感生成“看起来合理但解析失败”的查询。这个官方技能通过强制 schema 探查、按查询意图匹配专门生成规则，把“生成语法正确的 ES|QL”系统化，还内置了 PromQL 到 ES|QL 的语法桥接。对已用 Elastic 做日志或指标分析、想省去查文档时间的团队，这是官方给出的最短路径。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 9 | Elastic 为搜索与可观测性领域一线上市公司（NYSE: ESTC）官方出品；所属技能合集仓库 535 stars / 41 forks 为整体数据，不代表本技能个体热度，评分不依赖该数字 |
| 可用性 | 8 | SKILL.md 长达 400 余行，含错误处理与 10 份专项参考文档；v0.3.0 发布于 2026-05-28，仓库最近一次提交 2026-07-01；但仓库明确标注 “Technical Preview” 仍在快速迭代，且必须自行配置 Elasticsearch 连接凭据，非纯复制即用 |
| 安全性 | 8 | 见下方安全检查清单 |
| 综合评分 | 8.3 | 三项均值 |
安全检查清单：
| 检查项 | 结果 |
|---|---|
| ① Shell 命令执行 | 仅执行本地 Node 脚本（scripts/esql.js），用于连接用户自行配置的 Elasticsearch 集群并执行查询，权限范围明确 |
| ② 运行时联网外发 | 仅连接用户在环境变量中指定的 Elasticsearch 集群（自托管或 Elastic Cloud），未见向未声明的第三方外发数据 |
| ③ API key/凭据 | 需要 Elasticsearch 连接凭据，官方文档给出 4 种标准配置方式，均通过环境变量传递，不涉及硬编码 |
| ④ 可疑指令 | SKILL.md 与脚本全文未见 prompt injection 或越权指令；官方 README 专辟安全考量章节，主动提示 agent 处理的数据可能含攻击者构造字符串，需做好威胁建模 |
| ⑤ 作者/组织信誉 | Elastic 官方（elastic.co，纽交所上市公司 ESTC） |
| ⑥ License | 仓库整体 Apache License 2.0（GitHub API 确认）；但该技能 package.json 单独声明 license 字段为 “Elastic-2.0”，两层口径不完全一致，使用前建议留意 |
| ⑦ 维护时间 | 子技能最近一次功能性发布为 2026-05-28（v0.3.0），仓库最近一次提交为 2026-07-01，均在近 3 个月窗口内，维护活跃 |
7. 跟同类 Skills 相比的优势
| 项目 | 定位 | 差异点 |
|---|---|---|
| elasticsearch-esql（本推荐） | Elastic 官方：生成正确的 ES|QL 查询，覆盖日志、指标、时序、全文检索等多种数据形态 | 核心价值在“语法正确率”——强制 schema 探查 + 按查询意图匹配专门生成规则，还内置 PromQL 到 ES|QL 的语法桥接 |
| redis-search（Redis 官方） | Redis 官方：FT.SEARCH/FT.AGGREGATE 查询、向量检索与 RAG 管道搭建指引 |
聚焦 Redis 自身的索引设计与混合检索（词法 + 向量），定位是“帮你在 Redis 里搭好搜索/RAG”，而非跨数据形态的通用查询语言生成 |
| promql（Grafana 官方） | Grafana 官方：PromQL 查询编写、p95 排障、告警与基数排查等可观测性运维场景 | 专攻 Prometheus 生态的指标查询与故障排查，定位是“运维时的 PromQL 速查手册”；elasticsearch-esql 反而内置了兼容命令，可直接执行 PromQL 语法后接入 ES|QL 管道做二次处理 |
| firebase-firestore（Firebase 官方） | Google Firebase 官方：Firestore 文档数据库建模、安全规则与客户端 SDK 查询 | 面向 NoSQL 应用后端开发，聚焦“如何设计数据模型与写查询代码”，而非日志/指标类的分析型查询场景 |
差异化总结：以上均为一线厂商官方出品的“查询/检索”类技能，但服务的数据库与数据形态不同——elasticsearch-esql 覆盖日志、指标、全文检索等多种分析场景并打通 PromQL 语法，是唯一强调“跨可观测性生态互通”的一款。
8. 用户评价
该技能目前在第三方平台尚无具名用户评价：公开渠道可查到 Elastic 官方技术博客（Search Labs、Observability Labs、Security Labs 三篇）对该技能合集的介绍，以及若干技能市场的功能索引页，但未见可直接引用的独立用户评价原文。
9. 其他补充
elasticsearch-esql 所属的 elastic/agent-skills 合集还包含 Elasticsearch 认证授权、Kibana 仪表盘、可观测性、安全告警等共 45 个其他技能，可按需搭配安装。
10. 安装使用方式
- 方式一（推荐，精确安装单个技能）：
npx skills add elastic/agent-skills --skill elasticsearch-esql - 方式二（Claude Code 插件市场，安装整组 Elasticsearch 技能）：先执行
claude plugin marketplace add https://github.com/elastic/agent-skills，再执行claude plugin install elasticsearch@elastic-agent-skills - 方式三（GitHub Copilot CLI）：
copilot plugin marketplace add elastic/agent-skills，再copilot plugin install elasticsearch@elastic-agent-skills - 方式四（手动）：clone 仓库后把
skills/elasticsearch/elasticsearch-esql子目录复制到自己项目的技能目录 - 安装后建议重启 Claude Code 会话（官方 README 提示
/reload-plugins可能不会立即生效，属已知问题） - 使用前必须先配置 Elasticsearch 连接凭据（
ELASTICSEARCH_URL/ELASTICSEARCH_API_KEY等环境变量，4 种连接方式二选一），否则技能内置的连接测试会失败并提示配置步骤
11. 注意事项
- 仓库仍处于“Technical Preview”阶段，API 与技能内容可能随版本变化，生产环境使用前建议先在测试集群验证
- 需要用户自行拥有并配置一个可访问的 Elasticsearch 集群（自托管或 Elastic Cloud），技能本身不提供集群
- 与 OpenClaw、Hermes Agent 的兼容性未经官方验证，实际运行效果建议自行测试
- 技能包声明的 License 字段（Elastic License 2.0）比仓库整体的 Apache 2.0 更严格，计划封装进面向他人的托管产品前建议先确认条款