1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | cloud-monitoring-promql-query-google-skills |
| 作者/维护者 | Google（google/skills 官方仓库） |
| 来源链接 | https://github.com/google/skills/tree/main/skills/cloud/cloud-monitoring-promql-query |
| 许可证 | Apache-2.0（GitHub API 获取，适用于整个仓库） |
| GitHub Stars | 18,987（GitHub API 获取；该数字属整个 google/skills 合集仓库，不代表本技能自身热度） |
| Forks | 1,528（GitHub API 获取，同为合集整体数据） |
| 最新版本 | 无独立版本号；最近一次更新提交于 2026-08-26（GitHub API 获取） |
| 安装方式 | npx skills add google/skills 后勾选本技能，或手动复制 skills/cloud/cloud-monitoring-promql-query 目录 |
2. 功能介绍与亮点
这是一个把 Google Cloud Monitoring 的指标描述符（metric descriptor）翻译成合法 PromQL 查询语句的技能。核心能力包括：
- 描述符到 PromQL 的结构映射：按指标的
metricKind（GAUGE/DELTA/CUMULATIVE）与valueType（INT64/DOUBLE/DISTRIBUTION/BOOL）自动选择聚合函数（rate、sum、histogram_quantile等），并给出资源过滤字段（monitored_resource）的组装规则。 - 内置校验脚本：自带
scripts/validate_promql.py及配套单元测试validate_promql_test.py，生成查询后本地跑一遍语法与结构校验，出错时对照references/promql_error_recovery.md逐项修复，而不是把未经验证的查询直接丢给用户。 - 两份参考文档：
references/basic_aggregations.md（13KB，聚合规则速查表）与references/promql_error_recovery.md（5.2KB，常见报错排查），内容深度在同类监控查询技能中处于前列。 - 可组合性：与同仓库的
cloud-monitoring-metric-selection（模糊查询先定位指标）衔接使用，形成“选指标→生成查询→校验”的完整链路。
3. 适用场景
所属分类：DevOps 与基础设施
适用于已经在用 Google Cloud Monitoring 做可观测性建设的团队：需要为 Compute Engine、GKE 等资源手写监控图表、告警策略或仪表盘查询,但不熟悉 PromQL 语法细节的运维/SRE 人员,可以直接描述监控诉求（如“某实例 CPU 使用率”），由该技能产出并本地校验通过的 PromQL 语句,免去查文档试错的过程。
4. 跨 Agent 兼容性
| Agent | 结论 | 依据 |
|---|---|---|
| Claude Code | 原生支持 ✅ | SKILL.md 遵循 Agent Skills 规范（YAML frontmatter + references//scripts/ 子目录），该规范由 Claude Code 率先定义并读取 |
| Codex | 原生支持 ✅ | Codex CLI 读取同一 SKILL.md 目录结构,属公开标准的通用兼容对象 |
| OpenClaw | 原生支持 ✅ | OpenClaw 采用相同的 AgentSkills SKILL.md 规范（name/description frontmatter），结构可直接迁移 |
| Hermes Agent | 原生支持 ✅ | 遵循 agentskills.io 开放标准，跨兼容框架可移植 |
⚠️ 技能正文提到可选调用一个名为 google-cloud-monitoring:list_metric_descriptors 的 MCP 工具获取指标标签；该工具未配置时,正文本身给出了直接调用 Cloud Monitoring REST API 的兜底路径，不影响核心功能在任一 Agent 上的可用性。
5. 推荐理由
它把“看着 Cloud Monitoring 指标描述符现查 PromQL 语法”这件事变成了结构化的自动生成加本地校验，比对着文档手写查询更省时间也更不容易出低级语法错误；配套的错误恢复文档和单元测试覆盖的校验脚本，在同类监控查询生成类技能中内容深度靠前，且随 Google Cloud 官方更新保持较高维护频率。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | 由 Google 官方发布；本技能自身在第三方平台尚无独立评价或可查的采用数据 |
| 可用性 | 8 | 步骤清晰，SKILL.md 含完整工作流与校验脚本；需要预先配置 gcloud 认证与 pip install promql-parser；最近一次更新为 2026-08-26 |
| 安全性 | 9 | 见下方检查清单 |
安全检查清单：
| 检查项 | 结果 |
|---|---|
| ① Shell 命令执行范围 | 调用 gcloud config get-value project、gcloud auth print-access-token 获取项目与令牌，范围明确、用途透明 |
| ② 运行时联网外发 | 仅访问 Google Cloud Monitoring 官方 REST API,外联目标透明 |
| ③ 凭据处理 | 使用 gcloud 本地应用默认凭据（ADC）,不落盘存储额外密钥 |
| ④ 可疑指令 | 未发现 prompt injection 或夹带无关推广内容 |
| ⑤ 作者信誉 | Google 官方仓库,无造假迹象 |
| ⑥ License | Apache-2.0，明确 |
| ⑦ 最近维护 | 2026-08-26，活跃 |
综合评分：8.0（三项均值）
7. 跟同类 Skills 相比的优势
| 技能 | 定位 | 与本技能的差异 |
|---|---|---|
| cloud-monitoring-chart-generation（同仓库姊妹技能） | 把 Cloud Monitoring 指标直接生成可视化图表配置 | 产出物是图表而非查询字符串，服务于仪表盘搭建场景，与本技能面向告警策略/命令行查询的场景互补而非替代 |
| cloud-logging-query-generation（同仓库） | 生成 Cloud Logging 的日志查询语句 | 面向日志检索而非指标监控，语法体系（Logging Query Language）与 PromQL 完全不同 |
Prometheus 官方 promtool |
校验 PromQL 语法的命令行工具 | 只做语法校验，不负责把 Cloud Monitoring 的指标描述符翻译成正确的 PromQL 结构，也不理解 Cloud Monitoring 特有的资源过滤规则 |
8. 用户评价
该技能于 2026-08-26 刚合入 google/skills 仓库，目前在 GitHub Issues、Reddit、Hacker News 等平台尚无具名第三方用户评价。
9. 其他补充
无。
10. 安装使用方式
方式一（推荐）：
npx skills add google/skills运行后在交互列表中勾选 “Cloud Monitoring PromQL Generator”（即 cloud-monitoring-promql-query）。
方式二（手动）：
git clone https://github.com/google/skills.git
cp -r skills/skills/cloud/cloud-monitoring-promql-query ~/.claude/skills/安装后注意事项：
- 需已安装并登录
gcloudCLI（gcloud auth application-default login）。 - 需要
python3 -c "import promql_parser" || pip install promql-parser安装校验脚本依赖。 - 使用前需明确目标 Google Cloud 项目 ID；技能正文规定项目 ID 缺失且
gcloud无法解析时必须停止并向用户确认，不会用占位符生成查询。
11. 注意事项
- 生成的查询默认假设用户已在 Cloud Monitoring 中启用了对应资源的指标采集，技能本身不负责排查指标缺失问题。
- 技能正文包含一条可选的 MCP 工具调用路径（用于获取指标标签），该工具未配置时会自动回退到直接调用 REST API，不影响功能完整性。
- 仅覆盖 Cloud Monitoring 与 Managed Service for Prometheus 场景，不涵盖第三方 Prometheus 自建环境的指标转换。