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

| User wants | Preferred (MCP) | Fallback (kubectl) | |-------------------------------------|-----------------------------------------------------------------------------------------|---------------------------------------------------------------------| | "List pods in frontend namespace" | list pods --namespace=frontend | kubectl get pods -n frontend | | "Show me events for api-server" | get events --namespace=<ns> --field-selector=involvedObject.name=api-server | kubectl get events -n <ns> --field-selector involvedObject.name=api-server | | "Get logs for db-0" | logs --namespace=<ns> --pod=db-0 | kubectl logs -n <ns> db-0 | | "Why is pod web-123 CrashLooping?" | List pod → describe → events → logs (stepwise) | kubectl describe pod -n <ns> web-123, then logs | | "Restart worker deployment" | Ask confirmation → delete pods or rollout restart if supported | kubectl rollout restart deployment/<name> -n <ns> |

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