gke-ai-troubleshooting-skill-creation-guide

故障排查技能创建指南

使用本指南构建高质量的故障排查技能，帮助 AI Agent 诊断 GKE 工作负载中的复杂故障。

🏗️ 技能结构标准

必需组件

1. SKILL.md：核心诊断与解决工作流。
2. README.md：面向公众的概述和“适用场景”指南。
3. references/failure_signatures.md：真实的日志／指标特征。
4. scripts/validate_queries.sh：用于自动验证所有查询语法的脚本。
5. TEST.md：供人工执行的验证计划。
6. EVAL.yaml：用于跟踪性能的评估套件。

可选组件

1. BUILD：构建定义。

🏷️ 命名约定

• 目录名称：必须使用 kebab-case（例如， gke-ai-troubleshooting-tpu-vbar-oom）。
• 技能名称：必须与目录名称一致。

🔍 诊断工作流标准

步骤 0：必需上下文

每项技能都必须从“步骤 0”开始，以获取必要的上下文。

• 必需字段：<project_id>、<location>、<cluster_name>、 <timestamp>。
• 可选／按具体情况提供的字段：<node_name>、<workload_name>、 <workload_namespace>、<nodepool_name>。
• 时间规则：拒绝相对时间（例如，“5 分钟前”）。计算 [T - 30m] 到 [T + 30m] 的时间窗口。

诊断步骤

• 明确的查询：每个步骤都必须提供可直接使用的 Cloud Logging (LQL) 或 Cloud Monitoring (PromQL) 查询。
• 占位符语法：使用尖括号，如 <project_id>，而不是花括号，以免出现模板解析错误。
• 风险分类：将每个步骤标记为 [低风险]（只读）或 [高风险]（会修改数据／具有破坏性）。
• 自动化：说明 Agent 应自动继续，还是等待用户确认。

🛠️ 准确性与验证

零幻觉

• 切勿编造示例日志或指标。
• 从真实事件中提取特征，并在必要时进行匿名化。
• 不得外推：仅包含已在源对话中验证过的步骤和查询。

安全与隐私

• 不提供原始转储：不要指示 Agent 将原始日志转储到共享空间（问题跟踪系统、聊天）。
• 仅报告关键信号：指示 Agent 总结调查结果，并仅报告高信号信息（例如，“在节点 Y 上发现特定错误模式 X”）。

自动验证

• 每项技能都必须包含一个脚本（路径为 scripts/validate_queries.sh），使用 query_logs 或 gcloud logging read ... --limit=1 验证其 LQL 查询。

📋 最佳实践

• 简洁：保持说明精炼，重点说明“做什么”和“如何验证”。
• 适合公开发布：删除所有内部备注、个人书签或特定于项目的行话。
• 错误特征：在相关诊断步骤中明确链接到 references/failure_signatures.md。