1. 基本信息
| 项目 | 内容 | 数据来源 |
|---|---|---|
| 名称 | agent-platform-troubleshooting-google-skills（SKILL.md 自述名称：“Agent Platform Troubleshooting”） | GitHub 仓库 + SKILL.md |
| 作者/维护者 | Google（官方 google/skills 仓库） |
GitHub API |
| 来源链接 | https://github.com/google/skills/tree/main/skills/cloud/agent-platform-troubleshooting | — |
| 许可证 | Apache License 2.0 | GitHub API 实测 |
| GitHub Stars / Forks | 所属仓库 15,349 / 1,201（整仓库口径——google/skills 是 Google 官方发布的多技能合集，星数不代表单个技能自身热度） |
GitHub API 实测（2026-07-31） |
| 最新版本 | 无独立版本号，子目录首次提交即最近提交，2026-07-29 新增 | GitHub commits API 实测 |
| 安装方式 | npx skills add google/skills --skill agent-platform-troubleshooting，或手动复制子目录到对应 agent 的 skills 目录 |
官方 README 实测 |
2. 功能介绍与亮点
该技能为 Google Cloud Gemini Enterprise Agent Platform（原 Vertex AI 之上的企业级 Agent 托管层）提供结构化故障诊断能力，覆盖 Agent Gateway、Agent Registry、Agent Identity、Policies、Model Armor、Identity-Aware Proxy（IAP）等组件：
- 只诊断、不动手：技能明确定位为生成“诊断报告”，不代替用户执行 Terraform 变更或任何有破坏性的 gcloud 命令，全程只读检查——这是该技能与同系列其他 Agent Platform 管理类技能（可创建/删除资源）最大的区别
- 9 条前置判断规则：动手排查前先匹配请求类型，命中特定场景时直接给出标准答案而非现查现编，例如 PSC 子网耗尽场景强制只跑 4 条固定命令（禁止跨区域遍历导致超时）、拒绝为“发现资源”编写自定义脚本（避免消耗过多轮次并超时）、拒绝处理与本技能范围无关的通用 GCP IAM/GCS 权限问题
- 假设驱动的诊断流程：要求先提出至多 3 个失败假设并关联“最近变更”，再针对性收集证据，而非无差别扫描；诊断步骤覆盖 Agent 日志→网关日志→IAP 日志→注册表状态→IAM 绑定→Authz 扩展→基线角色→PrincipalSet 校验共 8 步
- 6 份配套参考文档（field-manual/known-issues/agent-gateway/agent-identity/agent-registry/policies，合计约 200KB）沉淀了具体已知问题编号（如 “BKI 21”“BKI 23”）与逐条命令，诊断报告需按固定模板输出（上下文、证据、根因假设、修复建议、验证步骤、未决问题）
3. 适用场景
所属分类：DevOps 与基础设施
适合已经在 Google Cloud Gemini Enterprise Agent Platform 上部署 Agent、且遇到网关 403（尤其是“未授权出站”）、Agent Runtime 查询 500、IAP/网关日志出现权限拒绝等问题的平台工程师与运维人员，帮助他们在不了解 Gateway→IAP→Authz 扩展→IAM 分层放行模型细节的情况下，按结构化流程定位问题所在层级。
4. 跨 Agent 兼容性
google/skills 仓库通过 npx skills 通用安装器（vercel-labs/skills）分发，该安装器 README 的 Supported Agents 表格逐一列出各 agent 的安装路径：
| Agent | 项目路径 | 全局路径 |
|---|---|---|
| Claude Code | .claude/skills/ |
~/.claude/skills/ |
| Codex | .agents/skills/ |
~/.codex/skills/ |
| OpenClaw | skills/ |
~/.openclaw/skills/ |
| Hermes Agent | .hermes/skills/ |
~/.hermes/skills/ |
四个生态均为原生支持——技能本身是标准 SKILL.md + Markdown 参考文档，不依赖 Claude Code 专属机制，配合上表安装路径即可在任一生态中使用。技能正文要求的工具能力（gcloud/curl 只读调用、日志查询）也未绑定任何特定 agent 的专属工具协议。
5. 推荐理由
Agent Gateway、IAP、Agent Registry 之间的分层放行模型（“default-deny，每层都要放行”）对不熟悉该产品内部架构的人并不直观，常见故障（如主机名不匹配、PAB 覆盖了正确的 IAM 绑定、IAP 处于 DRY_RUN 未生效）容易被误诊。该技能把这些“部落知识”固化为强制性的前置规则与分步诊断流程，并且始终停留在只读诊断阶段、不代替用户执行任何变更——既降低了排查门槛，也避免了 Agent 在陌生生产环境里越权动手的风险。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | 官方 Google 出品，隶属仓库整体 15,349 stars 的官方技能合集；该数字属整个合集，不代表本技能自身热度——本子目录 2026-07-29 才随一次提交整体加入，尚无外部 issue/PR 提及 |
| 可用性 | 8 | 6 份参考文档、固定诊断模板与命令示例齐备，无需额外 Python 环境或 SDK 安装；但需要用户已具备 Google Cloud 项目访问权限与 gcloud 认证，且要求使用者能提供项目号、区域、Agent/网关标识等上下文信息 |
| 安全性 | 9 | 见下方检查清单 |
| 综合 | 8.0 | 三项均值 |
安全检查清单：
① Shell 命令及权限范围：仅涉及 gcloud（describe/list/logging read 等只读子命令）与 curl 对 IAP/NetworkSecurity 等 REST API 的只读调用，正文明确写明“Stay in diagnosis mode. Don’t apply Terraform changes or run destructive gcloud commands”，无写入/删除类操作。
② 联网外发：仅与用户自己的 Google Cloud 项目（Cloud Logging、IAM、Agent Registry API）通信，无向第三方地址外发数据的迹象。
③ 凭据处理：复用用户已有的 gcloud 认证会话，技能本身不创建、存储或传输任何新凭据。
④ 可疑指令：通读 SKILL.md 全文与 6 份参考文档，未发现隐藏指令、混淆代码或异常数据外发；文中多处“不得执行破坏性命令”“不得跨区域循环扫描”的强制性表述，是主动的风险控制设计。
⑤ 作者信誉：Google 官方仓库出品，无造假迹象。
⑥ License：Apache License 2.0，明确清晰。
⑦ 最近维护：子目录 2026-07-29 新增，仓库整体保持日更（2026-07-30 仍有提交）。
7. 跟同类 Skills 相比的优势
| 对比对象 | 定位 | 与本技能的差异 |
|---|---|---|
| google/skills 同仓库的 gcloud 通用技能 | 覆盖 Google Cloud CLI 全域操作的通用参考技能 | 面向广泛的 gcloud 命令行使用场景，不针对特定产品线的已知故障模式；本技能专精 Agent Platform 网关/身份/策略栈，内置该产品线的已知问题编号库与假设驱动诊断流程 |
| fcakyon/claude-codex-settings 的 Gcloud Usage 技能 | 通用 GCP 可观测性参考（日志格式、指标告警、多产品调试工作流） | 定位是通用可观测性最佳实践速查手册，不特定于 Agent Platform 产品架构；本技能围绕 Agent Gateway→IAP→Authz 扩展→IAM 的分层放行模型给出结构化根因假设与验证步骤，并强制产出统一格式的诊断报告 |
8. 用户评价
该技能目前在第三方平台尚无具名用户评价。GitHub 仓库层面该子目录尚无外部开发者提交的功能性 issue 或 PR 讨论。
9. 其他补充
该技能是 google/skills 仓库“Agent Platform”系列的一员，同系列还包含端点管理（agent-platform-endpoint-management）、RAG 引擎管理（agent-platform-rag-engine-management）、模型调优管理（agent-platform-tuning-management）等技能，均围绕 Google Cloud 上的 Agent 全生命周期管理展开，可按需组合安装。
10. 安装使用方式
- 通过安装器：
npx skills add google/skills --skill agent-platform-troubleshooting，安装器会将技能放入当前 Agent 对应的 skills 目录（见第 4 章路径表） - 手动安装：克隆或下载
google/skills仓库后，将skills/cloud/agent-platform-troubleshooting/整个目录（含references/子目录）复制到目标 agent 的 skills 目录下 - 安装后：需先完成
gcloud auth login与gcloud auth application-default login，并准备好待排查的项目 ID/区域/Agent 标识；无需重启 Agent，直接在对话中描述报错现象即可触发（如“我的 Agent 调用外部 API 报 403 egress 未授权”）
11. 注意事项
- 该技能只产出诊断报告与修复建议，不会代为执行任何变更，实际修复仍需用户自行确认并操作
- 强制要求先收集齐 Project ID、Location、Agent/Gateway 标识与准确报错信息，信息不全时会在报告中标注“未知项”而非臆测
- 技能强绑定 Google Cloud Gemini Enterprise Agent Platform 的网关/注册表/IAP 体系，不适用于通用 GCP IAM 或与该产品线无关的网络问题（技能正文明确要求遇到此类问题时直接拒绝并说明超出范围）
- 子目录刚于 2026-07-29 加入仓库，尚缺乏外部社区的长期实战验证