---

name: kubernetes-troubleshoot description: "Troubleshoot and manage Kubernetes clusters, including resource inspection, debugging, pod logs, events, and cluster operations. Use when the user needs to diagnose issues, inspect workloads, analyze pod failures, or perform Kubernetes cluster operations."

Kubernetes Troubleshooting & Management Skill

What this Skill does

Use this skill when the user needs to troubleshoot or manage Kubernetes clusters. This includes operations such as:

• Listing pods, deployments, namespaces, nodes
• Getting pod logs
• Fetching events for a resource
• Inspecting workloads and resource conditions
• Understanding CrashLoopBackOff, ImagePullBackOff, pending pods
• Multi-cluster interactions through kubeconfig contexts
• Suggesting next debugging steps

Tool Preference: MCP First, kubectl as Fallback

Preferred Method: Use the Kubernetes MCP server when available

• MCP tools allow pre-approved operations for faster execution
• More efficient for common read operations
• Built-in safety guardrails

Fallback Method: Use kubectl commands via terminal when:

• MCP server is not available or fails
• MCP cannot provide the information needed
• Specific kubectl features are required (port-forward, plugins, etc.)

This skill helps Claude:

• Choose the appropriate tool based on availability and capabilities
• Restrict queries to namespace/cluster automatically
• Ask for confirmation before destructive actions
• Recommend stepwise debugging strategies
• Provide safe, context-efficient responses

Best Practices

1. Always scope operations

• Include namespace unless user explicitly wants cluster-wide.
• Include context when user has multiple clusters.
• Encourage label selectors instead of listing all resources.

2. Prefer read-only operations first

Recommended sequence for debugging:

1. List pods matching a selector
2. Describe pod
3. Fetch pod events
4. Retrieve logs
5. Inspect configmaps/secrets/environment
6. Only then consider restart/delete/scale

4. Tool Usage Guidelines

When using MCP (preferred): Examples of safe MCP-driven operations:

• List Pods: list pods --namespace=<ns> --context=<cluster>
• Get Pod Logs: logs --namespace=<ns> --pod=<pod>
• Get Events: get events --namespace=<ns> --field-selector=involvedObject.name=<name>
• Inspect Deployment: get deployment <name> --namespace=<ns>

When using kubectl (fallback):

• Always specify namespace with -n <namespace> or --namespace=<namespace>

• Use --context when multiple clusters are configured

• Consider using -o yaml or -o json for detailed inspection

• Use kubectl explain for resource documentation

• List Pods

  • list pods --namespace=<ns> --context=<cluster>

• Get Pod Logs

  • logs --namespace=<ns> --pod=<pod>

• Get Events

  • get events --namespace=<ns> --field-selector=involvedObject.name=<name>

• Inspect Deployment

  • get deployment <name> --namespace=<ns>

5. Multi-Cluster Awareness

If multiple contexts exist:

• Always request or infer the correct context.
• Avoid ambiguous commands that default to the wrong cluster.

Example User Requests → Recommended Actions

Tool Limitations

MCP Limitations:

• Some advanced operations may not be available (port-forward, plugin commands)
• Complex manifest edits may require kubectl fallback

kubectl Limitations:

• Requires user approval for each command
• Less efficient for multiple sequential operations
• No pre-approval mechanisms) may not be available
• Complex edits to manifests may require manual patching