1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | promql（收录于 Grafana 官方 grafana/skills 合集仓库） |
| 作者/维护者 | Grafana Labs（grafana 官方组织，本子技能主要提交者为 Grafana 员工 Jára Benc） |
| 来源链接 | https://github.com/grafana/skills/tree/main/skills/grafana-core/promql |
| 许可证 | Apache-2.0（GitHub API 获取） |
| GitHub Stars / Forks | 合集仓库整体 200 / 17（GitHub API 获取；该数字属整个合集仓库，不代表本技能自身热度，本技能自身热度评估见第 6 章） |
| 最新版本 | 无独立版本号，按仓库提交历史追踪，最近一次改动为 2026 年 7 月初（GitHub API 获取） |
| 安装方式 | npx skills add grafana/skills 或 Claude Code 插件市场 claude plugin install grafana-core@grafana-skills |
2. 功能介绍与亮点
promql 是一份专门教 agent 写对 PromQL（Prometheus 查询语言）的参考技能。核心内容覆盖：
rate/irate/increase的适用场景与常见误用（如未满足“时间窗口 ≥ 4 倍抓取间隔”这条黄金法则）- 标签匹配与正则、
sum / avg / topk / by / without等聚合写法 - 经典与原生
histogram_quantile的正确写法（p95/p99 延迟计算最常出错的地方） - 除零保护的错误率计算、
absent/changes判断数据缺失、时间偏移与predict_linear趋势预测 - 把慢查询固化成 recording rule 的完整操作步骤，含验证方法
- 一份专门的“高基数排查”速查表（认路径见第 9 章）
亮点：由 Grafana Labs 官方维护，文档把“常见 bug 现象 → 根因”直接列成对照表（如“histogram_quantile 返回 NaN → 忘记在内层聚合里保留 by (le)”），агent 可以直接对照现象定位，而不是从零推导 PromQL 语法。
3. 适用场景
所属分类：DevOps 与基础设施。
适合已经在用 Prometheus、Grafana Mimir 或 Grafana Cloud Metrics 做监控的团队。典型场景包括：写一条新的监控查询、修正算错的 p95/p99 延迟、搭建错误预算告警（SLO burn-rate）、排查“这条查询为什么很慢”、揪出把 Mimir/Grafana Cloud 账单撑爆的高基数标签，或者把仪表盘里的慢查询迁移成 recording rule。使用者以 DevOps 工程师、SRE 为主，也适合刚接手 Prometheus 监控栈、还不熟悉 PromQL 语法细节的初中级工程师。
4. 跨 Agent 兼容性
- Claude Code：✅ 原生支持。仓库 README 提供专门的插件市场安装命令（
claude plugin marketplace add grafana/skills+claude plugin install grafana-core@grafana-skills）。 - Codex：✅ 原生支持。README 说明 Codex 等遵循 Agent Skills 标准的工具可通过
.agents-plugin/marketplace.json清单自动发现技能，无需手动配置。 - OpenClaw：❓ 未验证。README 仅泛称“兼容任何遵循 Agent Skills 开放标准的工具”，未点名 OpenClaw，也未给出专门适配说明。
- Hermes Agent：❓ 未验证。抓取到的材料中未提及。
5. 推荐理由
PromQL 语法灵活但陷阱多——聚合顺序错一步、by/without 用反、忘记时间窗口下限，都会让延迟或错误率算出一个“看起来正常但完全错误”的数字。这份技能由 Prometheus 生态的官方厂商 Grafana Labs 维护，把最容易踩的坑整理成“现象 → 根因 → 正确写法”的直接对照，agent 可以照着核对而不是凭经验猜测，能实质性减少监控查询里的静默错误。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | Grafana Labs 官方出品，仓库有 14 位贡献者持续提交；该技能自身作为独立子技能，尚未见第三方独立讨论 |
| 可用性 | 9 | 一条命令或一次插件安装即可用；SKILL.md 含完整可复制的查询示例与配套参考文档；最近一次改动为 2026 年 7 月初；无需任何付费依赖，对接开源 Prometheus 或 Grafana Cloud 均可 |
| 安全性 | 9 | 纯查询与配置参考，示例命令均为只读的指标查询（用户自行指定自己的监控端点），未发现可疑指令或数据外发；License 明确；维护活跃 |
安全检查清单：①权限范围——示例仅涉及只读的 curl/promql 查询命令，无破坏性操作；②联网外发——查询目标是用户自己配置的 Prometheus/Grafana 端点，非第三方黑盒服务；③凭据存储——Grafana Cloud 场景下的 basic auth 由用户自行提供并直接用于自己的端点，未见凭据落盘或转发行为；④可疑指令——通读全文未发现混淆代码或隐蔽指令；⑤作者信誉——主要提交者为 Grafana 官方员工，账号自 2011 年持续活跃；⑥License——Apache-2.0，明确；⑦维护时间——2026 年 7 月初仍有提交，活跃。
综合评分（三项均值）：8.3
7. 跟同类 Skills 相比的优势
| Skill | 定位 | 与 promql 的差异 |
|---|---|---|
| dt-dql-essentials（Dynatrace 官方） | 教 agent 写 Dynatrace 专有查询语言 DQL 的语法与省成本技巧 | 服务对象是 Dynatrace 这一商业可观测性平台的用户；promql 面向开源 Prometheus/Grafana 生态，两者语法体系完全不同，不存在替代关系，各自绑定不同技术栈 |
| elasticsearch-esql（Elastic 官方） | 教 agent 写 Elasticsearch 的 ES|QL 查询语言 | 定位于日志与全文检索场景下的查询生成；promql 定位于指标类时序数据的查询与告警调优，两者面向的数据模型（日志 vs 指标）不同 |
| grafana-oss（同仓库姊妹技能） | 覆盖 Grafana OSS 的仪表盘、数据源、RBAC、服务器配置等整体使用 | 是更宽泛的 Grafana 使用入门技能；promql 只聚焦查询语言本身的正确写法与排障，两者可以搭配使用而非互斥 |
8. 用户评价
该技能目前尚无具名用户评价；第三方技能目录网站收录了该技能的条目信息，但未附带用户评论。
9. 其他补充
同仓库还提供 prometheus-label-strategy（标签设计预防）、adaptive-metrics（后置聚合降本）、dpm-finder（按量计费分析）等配套技能，均可与 promql 搭配处理不同阶段的可观测性问题。
10. 安装使用方式
- 通用方式（推荐）：
npx skills add grafana/skills，随后按需只启用promql子技能 - Claude Code：
claude plugin marketplace add grafana/skills claude plugin install grafana-core@grafana-skills - Cursor：同样使用
npx skills add grafana/skills，技能会写入项目内的.cursor/skills/ - Codex 及其他遵循 Agent Skills 标准的工具：技能通过仓库自带的
.agents-plugin/marketplace.json清单自动发现，无需手动配置
安装后无需重启，agent 在用户提出“计算错误率”“p99 延迟”“为什么这条查询很慢”等相关请求时会自动匹配加载。
11. 注意事项
- 使用前提是已有可访问的 Prometheus、Grafana Mimir 或 Grafana Cloud Metrics 端点；技能本身不提供监控数据源
- 技能聚焦查询语言本身，仪表盘搭建、告警渠道配置等更宽泛的 Grafana 使用需求需配合同仓库的
grafana-oss、alerting-irm等姊妹技能 - 作为官方合集仓库中的独立条目，其收录与维护节奏跟随
grafana/skills仓库整体版本节奏，暂无独立于合集之外的发布计划