1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | api-gateway-openapi-spec-authoring-google-skills |
| 作者/维护者 | Google(官方) |
| 来源链接 | https://github.com/google/skills/tree/main/skills/cloud/api-gateway-openapi-spec-authoring |
| 许可证 | Apache-2.0 |
| GitHub Stars / Forks | 21,805 / 1,861(所属仓库整体数字,不代表本技能自身热度;GitHub API,2026-11-08 读取) |
| 最新版本 | 技能内标注 1.0.0;仓库主分支最近一次提交 2026-11-06 |
| 安装方式 | 把技能目录复制进 agent 的 skills 目录;命令经 gcloud 执行 |
数据来源:上述数字取自 GitHub API;功能与评分依据来自技能正文与官方文档。
2. 功能介绍与亮点
一句话:给 Google Cloud API Gateway 写、迁移、修 OpenAPI 规格——尤其是 2.0 到 3.x 迁移时的扩展结构差异。
- 迁移路径清楚:OpenAPI 2.0 的
x-google-backend与 3.x 的结构不同,技能列出了对照关系。 - 3.x 的根块:
x-google-api-management必须声明后端;JWT 迁到x-google-auth,配额与指标并入根块。 - 修常见报错:
gcloud api-gateway api-configs create失败时的典型错误(如在 2.x 之外用了扩展)以及改法。 - 配额不生效:
x-google-quota写了却没拦住请求,技能给出排查顺序。 - 路径参数错位:后端收到的是 query 而不是 path 参数时的修正方式。
- 边界清楚:MCP 工具、后端封锁与限流、Endpoints、Apigee、GKE Gateway 都指向其他技能。
3. 适用场景
所属分类:集成与工作流自动化。
- 要把老 Swagger 2.0 规格迁到 OpenAPI 3.x 的后端工程师;
- 用 API Gateway 暴露服务、却被 api-configs 创建失败卡住的人;
- 配了配额却不生效、需要快速定位的运维;
- 想按 Google 扩展规范重写规格、避免踩坑的团队。
4. 跨 Agent 兼容性
| Agent | 结论 | 依据 |
|---|---|---|
| Claude Code | 原生支持 | 技能目录安装,按描述触发 |
| Codex | 需适配 | 技能正文通用,gcloud 调用需按平台调整 |
| OpenClaw | 需适配 | 需要平台支持技能目录并允许执行本地命令 |
| Hermes Agent | 未验证 | 未找到该平台的接入示例 |
5. 推荐理由
API Gateway 的规格问题很磨人:扩展写法在 2.0 与 3.x 之间变了、配额静默失效、路径参数跑到 query 里,报错信息还不直接指向原因。这份技能把这些具体坑和改法列清楚,对要迁移或刚接 API Gateway 的人,能省掉反复试错。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | Google 官方出品;所属仓库 21,805 stars 是整个合集热度,不代表本技能自身热度 |
| 可用性 | 8 | 迁移对照、报错修法与边界都写清楚了;前置是 gcloud 与项目权限 |
| 安全性 | 9 | 见下方清单;官方开源,命令范围限于用户自己的项目 |
安全性检查清单:
| 项 | 结果 |
|---|---|
| ① 执行 shell 与权限 | 通过 gcloud 操作用户自己的 API Gateway 配置 |
| ② 联网外发 | 只与 Google Cloud 端点通信 |
| ③ 凭据 | 使用既有 gcloud 凭据,不要求写进对话 |
| ④ 可疑指令 | 未见注入或夹带推广 |
| ⑤ 作者信誉 | Google 官方仓库,Apache-2.0 |
| ⑥ License | Apache-2.0,全文可查 |
| ⑦ 维护时间 | 2026-11-06 仍在更新 |
扣分点:需要 GCP 项目与网关配置;规格本身的质量仍取决于后端接口设计。
7. 跟同类 Skills 相比的优势
| 技能 | 定位 | 与本技能的差异 |
|---|---|---|
| api-gateway-mcp-server-google-skills | 把 API 发布成 MCP 工具 | 面向 agent 工具;本技能面向网关的规格本身 |
| api-gateway-backend-security-and-rate-limiting-google-skills | 后端封锁与限流 | 管安全与 429;本技能管规格能否正确创建与生效 |
| apigee-agent-gateway-governance-google-skills | Apigee 做 agent 网关治理 | 面向 Apigee;本技能面向 API Gateway 的 OpenAPI 配置 |
核心差异:同类各管网关的一角,它专治「规格写不对、配置建不出来、写了也不生效」。
8. 用户评价
该技能目前在第三方平台尚无具名用户评价(2026-11-08)。
9. 其他补充
- 技能内标注 1.0.0,随官方仓库更新。
- 属于
google/skills合集(180 个技能),可按需只装这一条。
10. 安装使用方式
git clone https://github.com/google/skills
mkdir -p ~/.claude/skills
cp -r skills/skills/cloud/api-gateway-openapi-spec-authoring ~/.claude/skills/
装好后说「把这个 Swagger 2.0 规格迁到 OpenAPI 3.x 给 API Gateway 用」,它会按扩展结构给出改写。
11. 注意事项
- 2.0 与 3.x 的扩展结构不同,别直接复制官方示例里的片段。
- 配额不生效先查规格位置与网关配置,再怀疑后端。
- 需要 GCP 项目与相应权限。
- 修改生产配置前先在测试项目验证。