Agent-Skills.md

Agent Skills: Kubernetes Troubleshooting & Management Skill

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.

UncategorizedID: timbuchinger/loadout/kubernetes-troubleshoot

Repository

timbuchinger/loadout
timbuchinger

Install this agent skill to your local

pnpm dlx add-skill https://github.com/timbuchinger/loadout/tree/HEAD/skills/kubernetes-troubleshoot

Skill Files

Browse the full folder contents for kubernetes-troubleshoot.

Download Skill

Loading file tree…

skills/kubernetes-troubleshoot/SKILL.md

Skill Metadata

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

| 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