K8

k8s-troubleshoot

Automated diagnostics for Kubernetes clusters, covering pod logs, events, and node health.

Install

mkdir -p .claude/skills/k8s-troubleshoot && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/5528" && unzip -o skill.zip -d .claude/skills/k8s-troubleshoot && rm skill.zip

Installs to .claude/skills/k8s-troubleshoot

Activation

This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.

Debug Kubernetes pods, nodes, and workloads. Use when pods are failing, containers crash, nodes are unhealthy, or users mention debugging, troubleshooting, or diagnosing Kubernetes issues.
188 chars✓ has a “when” trigger
Intermediate

Key capabilities

  • →Inspect pod status and conditions
  • →Retrieve and analyze pod logs
  • →Check node health and resource pressure
  • →Examine Kubernetes events
  • →Debug DNS resolution issues

How it works

It aggregates data from pod states, events, and resource metrics to identify root causes for common failures like CrashLoopBackOff or OOMKilled.

Inputs & outputs

You give it
Pod or node name
You get back
Diagnostic report or log output

When to use k8s-troubleshoot

  • →Debug CrashLoopBackOff states
  • →Inspect logs for failing pods
  • →Analyze kubernetes node health
  • →Investigate pod resource usage

About this skill

Kubernetes Troubleshooting

Expert debugging and diagnostics for Kubernetes clusters using kubectl-mcp-server tools.

Requires the cilium, diagnostics, istio, policy, security toolsets: start kubectl-mcp-server with --toolsets default,cilium,diagnostics,istio,policy,security (or MCP_TOOLSETS=default,cilium,diagnostics,istio,policy,security). For deep work, the project-maintained MCP servers may fit better: Kyverno: https://github.com/nirmata/kyverno-mcp.

When to Apply

Use this skill when:

  • User mentions: "debug", "troubleshoot", "diagnose", "failing", "crash", "not starting", "broken"
  • Pod states: Pending, CrashLoopBackOff, ImagePullBackOff, OOMKilled, Error, Unknown
  • Node issues: NotReady, MemoryPressure, DiskPressure, NetworkUnavailable, PIDPressure
  • Keywords: "logs", "events", "describe", "why isn't working", "stuck", "not responding"

Priority Rules

PriorityRuleImpactTools
1Check pod status firstCRITICALkubectl_get, kubectl_describe
2View recent eventsCRITICALkubectl_get
3Inspect logs (including previous)HIGHkubectl_logs
4Check resource metricsHIGHkubectl_top
5Verify endpointsMEDIUMkubectl_get
6Review network policiesMEDIUManalyze_network_policies
7Examine node statusLOWkubectl_get, kubectl_describe

Quick Reference

SymptomFirst ToolNext Steps
Pod Pendingkubectl_describeCheck events, node capacity, resource requests
CrashLoopBackOffkubectl_logs(pod_name, previous=True)Check exit code, resources, liveness probes
ImagePullBackOffkubectl_describeVerify image name, registry auth, network
OOMKilledkubectl_topIncrease memory limits, check for memory leaks
ContainerCreatingkubectl_describeCheck PVC binding, secrets, configmaps
Terminating (stuck)kubectl_describeCheck finalizers, PDBs, preStop hooks

Diagnostic Workflows

Pod Not Starting

1. kubectl_get(resource_type="pods", namespace, label_selector) - Get pod status
2. kubectl_describe(name, namespace) - See events and conditions
3. kubectl_get(resource_type="events", namespace, field_selector="involvedObject.name=<pod>") - Check events
4. kubectl_logs(name, namespace, previous=True) - For crash loops

Common Pod States

StateLikely CauseTools to Use
PendingScheduling issueskubectl_describe, kubectl_get, kubectl_get
ImagePullBackOffRegistry/authkubectl_describe, check image name
CrashLoopBackOffApp crashkubectl_logs(pod_name, previous=True)
OOMKilledMemory limitkubectl_top, adjust limits
ContainerCreatingVolume/networkkubectl_describe, kubectl_get

Node Issues

1. kubectl_get(resource_type="nodes") - List nodes and status
2. kubectl_describe(name) - See conditions and capacity
3. Check: Ready, MemoryPressure, DiskPressure, PIDPressure
4. node_logs(name, "kubelet") - Kubelet logs

Deep Debugging Workflows

CrashLoopBackOff Investigation

1. kubectl_logs(name, namespace, previous=True) - See why it crashed
2. kubectl_describe(name, namespace) - Check resource limits, probes
3. kubectl_top(name, namespace) - Memory/CPU at crash time
4. If OOM: compare requests/limits to actual usage
5. If app error: check logs for stack trace

Networking Issues

1. kubectl_get(resource_type="services", namespace) - Verify service exists
2. kubectl_get(resource_type="endpoints", namespace) - Check endpoint backends
3. If empty endpoints: pods don't match selector
4. analyze_network_policies(namespace) - Check traffic rules
5. For Cilium: cilium_list_endpoints(), get_hubble_flows()

Storage Problems

1. kubectl_get(resource_type="pvc", namespace) - Check PVC status
2. kubectl_describe(name, namespace) - See binding issues
3. kubectl_get(resource_type="storageclasses") - Verify provisioner exists
4. If Pending: check storage class, access modes

DNS Resolution

1. exec_in_pod(pod, namespace, "nslookup kubernetes.default") - Test DNS
2. If fails: check coredns pods in kube-system
3. kubectl_get(resource_type="pods", namespace="kube-system", label_selector="k8s-app=kube-dns")
4. kubectl_logs(pod_name="coredns-*", namespace="kube-system")

Multi-Cluster Debugging

All tools support context parameter for targeting different clusters:

kubectl_get(resource_type="pods", namespace="kube-system", context="production-cluster")
kubectl_get(resource_type="events", namespace="default", context="staging-cluster")
kubectl_describe(resource_type="pod", name="myapp-xyz", namespace="prod", context="prod-east")

Diagnostic Scripts

For comprehensive diagnostics, run the bundled scripts:

Decision Tree

See references/DECISION-TREE.md for visual troubleshooting flowcharts.

Common Errors Reference

See references/COMMON-ERRORS.md for error message explanations and fixes.

Related Tools

Core Diagnostics

  • kubectl_get, kubectl_describe, kubectl_logs, kubectl_top
  • kubectl_get, kubectl_get, kubectl_describe
  • kubectl_top, compare_namespaces

Advanced (Ecosystem)

  • Cilium: cilium_list_endpoints, get_hubble_flows
  • Istio: istio_proxy_status, istio_analyze

Related Skills

When not to use it

  • →When cluster-level logs are not accessible
  • →When the issue is outside the Kubernetes control plane

Prerequisites

kubectl

Limitations

  • →Requires sufficient permissions to view logs
  • →Limited to Kubernetes-native resources

How it compares

It provides a structured diagnostic workflow that correlates events and logs rather than just returning raw output.

Compared to similar skills

k8s-troubleshoot side by side with the closest alternatives in the catalog.

SkillInstallsUpdatedSafetyDifficulty
k8s-troubleshoot (this skill)19moReviewIntermediate
k8s-incident19moReviewIntermediate
debug-cluster21yReviewIntermediate
k8s-cilium19moReviewAdvanced

Try saying

Example prompts that trigger this skill in your AI assistant.

More by rohitg00

View all by rohitg00 →

Search skills

Search the agent skills registry