googlecloudplatform/gke-ai-troubleshooting-skill-creation-guide
skills/gke-ai-troubleshooting-skill-creation-guide/SKILL.md
Expert instructions for building high-quality GKE troubleshooting skills. Codifies Step 0 context rules, zero-hallucination signatures, and explicit LQL/PromQL query requirements.
$ install --global
skillsauthnpx skillsauth add googlecloudplatform/gke-mcp gke-ai-troubleshooting-skill-creation-guideInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Jun 11, 2026, 2:55 AM51.2s1 file scanned
SKILL.md
- name:
- gke-ai-troubleshooting-skill-creation-guide
- description:
- >
Troubleshooting Skill Creation Guide
Use this guide to build high-quality troubleshooting skills that enable AI agents to diagnose complex failures in GKE workloads.
🏗️ Skill Structure Standard
Mandatory Components
SKILL.md: The core diagnostic and resolution workflow.README.md: Public-facing overview and "When to use" guide.references/failure_signatures.md: Authentic log/metric signatures.scripts/validate_queries.sh: Automatic syntax validator for all queries.TEST.md: Manual verification plan for humans.EVAL.yaml: Evaluation suite for performance tracking.
Optional Components
BUILD: Build definition.
🏷️ Naming Conventions
- Directory Name: MUST be
kebab-case(e.g.,gke-ai-troubleshooting-tpu-vbar-oom). - Skill Name: MUST match the directory name.
🔍 Diagnostic Workflow Standards
Step 0: Mandatory Context
Every skill MUST begin with a "Step 0" to acquire necessary context.
- Mandatory Fields:
<project_id>,<location>,<cluster_name>,<timestamp>. - Optional/Case-by-Case Fields:
<node_name>,<workload_name>,<workload_namespace>,<nodepool_name>. - Time Rule: Reject relative time (e.g., "5 minutes ago"). Calculate a
window of
[T - 30m]to[T + 30m].
Diagnostic Steps
- Explicit Queries: Every step MUST provide a ready-to-use Cloud Logging (LQL) or Cloud Monitoring (PromQL) query.
- Placeholder Syntax: Use angle brackets like
<project_id>instead of curly braces for placeholders to avoid template resolution errors. - Risk Categorization: Label every step as [Low Risk] (Read-only) or [High Risk] (Mutative/Destructive).
- Automation: Specify if the agent should proceed automatically or wait for user confirmation.
🛠️ Accuracy & Validation
Zero Hallucination
- Never synthesize example logs or metrics.
- Source signatures from real incidents and anonymize where necessary.
- DO NOT EXTRAPOLATE: Only include steps and queries that were verified in the source conversation.
Security & Privacy
- No Raw Dumps: Do not instruct the agent to dump raw logs into shared spaces (bugs, chat).
- Signal Only: Instruct the agent to summarize findings and report only high-signal information (e.g., "Found specific error pattern X on node Y").
Automated Validation
- Every skill MUST include a script (at
scripts/validate_queries.sh) that usesquery_logsorgcloud logging read ... --limit=1to verify its LQL queries.
📋 Best Practices
- Conciseness: Keep instructions lean. Focus on "what to do" and "how to verify".
- Public Ready: Remove all internal notes, personal bookmarks, or project-specific jargon.
- Error Signatures: Explicitly link to
references/failure_signatures.mdin relevant diagnostic steps.
Related Skills
googlecloudplatform/gke-ai-troubleshooting-jobset-interruption
data-ai
VerifiedTrustedCommunity
Systematically diagnose GKE JobSet interruptions, restarts, and preemptions for AI/ML training workloads. Identifies preemption events, maintenance interruptions, bad host VMs, unhealthy pods, and coordinator worker failures.
161SKILL.mdUpdated Jun 4, 2026
googlecloudplatform/gke-ai-troubleshooting-tpu-connection-failure-vbar-oom
development
VerifiedTrustedCommunity
Diagnose and prevent `vbar_control_agent` segfaults and OOMs caused by race conditions during TPU device resets and frequent metrics collection (e.g. every 3s). Use when TPU slice initialization fails or `vbar_control_agent` crashes on TPU v6e nodes.
161SKILL.mdUpdated May 5, 2026
googlecloudplatform/gke-productionize
tools
VerifiedTrustedCommunity
Assists in preparing applications and clusters on GKE for production.
148SKILL.mdUpdated Apr 18, 2026
googlecloudplatform/gke-app-onboarding
devops
VerifiedTrustedCommunity
Workflows for containerizing and deploying applications to GKE for the first time.
148SKILL.mdUpdated Apr 16, 2026