Agent skill

Kubectl Helper

by shepherdjerred in shepherdjerred/monorepo

Kubernetes troubleshooting and resource management with kubectl When user works with Kubernetes, mentions kubectl, pods, deployments, or k8s errors

GPL-3.0Auto-check passedDevOps & Cloud

Install Kubectl Helper

skills CLI
$ npx skills add shepherdjerred/monorepo --skill kubectl-helper -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install shepherdjerred/monorepo kubectl-helper --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/shepherdjerred/monorepo.git skills-src && mkdir -p .claude/skills && cp -r skills-src/packages/dotfiles/dot_agents/skills/kubectl-helper .claude/skills/kubectl-helper && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
kubectl-helper
GitHub stars
112
Token cost
~2.8k tokens
SKILL.md length
428 words
Files
1
Skills in repo
63
Repo updated
First seen
Licence
GPL-3.0

At a glance

Kubernetes troubleshooting and resource management with kubectl When user works with Kubernetes, mentions kubectl, pods, deployments, or k8s errors

  • Works in 4 steps: Always use version control for manifests → Prefer server-side apply for all… → Preview changes before applying → …
  • Works with Kubernetes
  • SKILL.md covers What's New in Kubernetes 1.33…, Overview, CLI Commands and Troubleshooting Workflows, plus 6 more sections
  • Calls kubectl and git

What it does

Kubectl Helper is an agent skill from shepherdjerred/monorepo. Kubernetes troubleshooting and resource management with kubectl When user works with Kubernetes, mentions kubectl, pods, deployments, or k8s errors

Its SKILL.md is about 2.8k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in DevOps & Cloud, covering Container orchestration. It works with Kubernetes and Docker. The repository describes itself as: Monorepo for all of my projects. The licence is GPL-3.0.

When your agent uses it

  • Works with Kubernetes
  • Mentions kubectl

Example prompts

  • “Use the kubectl-helper skill to kubernete troubleshooting and resource management with kubectl When user works with Kubernetes, mentions kubectl…”
  • “/kubectl-helper”

Requirements

  • Docker

Workflow steps

4 steps, taken from the first numbered list in SKILL.md.

  1. Always use version control for manifests
  2. Prefer server-side apply for all manifest applications
  3. Preview changes before applying
  4. Use kubectl diff as pre-commit hook

What it can do on your machine

Read from SKILL.md and the folder at commit bc57ca5. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • kubectl
    • git

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use kubectl and git, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Kubectl Helper loads about 2.8k tokens when it runs. Until then it costs about 41 tokens; SKILL.md has 428 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~41
When it runs · the whole SKILL.md, loaded when a task matches
~2.8k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from shepherdjerred/monorepo at commit bc57ca5, republished under its GPL-3.0 licence (© shepherdjerred). 428 words, ~2,799 tokens.

Download SKILL.mdSave it as .claude/skills/kubectl-helper/SKILL.md (or your agent's skills folder).
name
kubectl-helper
description
Kubernetes troubleshooting and resource management with kubectl When user works with Kubernetes, mentions kubectl, pods, deployments, or k8s errors

Kubernetes Helper Agent

What's New in Kubernetes 1.33 & 2025

  • Server-Side Apply: Recommended default for applying manifests (better conflict resolution)
  • Server-Side Dry Run: Full API validation before applying changes
  • kubectl diff: Preview changes before applying
  • Containerd Default: containerd is now the default runtime (Docker deprecated)
  • Enhanced Label Selectors: More powerful filtering and bulk operations
  • Rollout Control: Better manual control with kubectl rollout pause

Overview

This agent helps you work with Kubernetes clusters using kubectl for resource management, troubleshooting, and debugging.

CLI Commands

Auto-Approved Commands

The following kubectl commands are auto-approved and safe to use:

  • kubectl get - List resources
  • kubectl describe - Show detailed resource information
  • kubectl logs - View container logs
  • kubectl explain - Show resource documentation
  • kubectl api-resources - List available resource types
  • kubectl version - Show version information
  • kubectl cluster-info - Display cluster information
  • kubectl config - Manage kubeconfig
  • kubectl top - Show resource usage
Modern Apply Patterns (2025)

Server-side apply (recommended):

bash
# Apply with server-side processing (better conflict resolution)
kubectl apply -f deployment.yaml --server-side

# Apply directory recursively
kubectl apply -f ./configs/ --server-side --recursive

# Force conflicts to be resolved server-side
kubectl apply -f deployment.yaml --server-side --force-conflicts

Preview changes before applying:

bash
# Show diff of what will change
kubectl diff -f deployment.yaml

# Dry run with full server-side validation
kubectl apply -f deployment.yaml --dry-run=server

# Client-side dry run (no server validation)
kubectl apply -f deployment.yaml --dry-run=client

Why server-side apply?

  • Better conflict resolution (server decides, not client)
  • Supports collaborative editing (multiple sources can manage same resource)
  • Respects field ownership (who owns each field)
  • Required for some newer Kubernetes features
Common Operations

Get resources:

bash
kubectl get pods
kubectl get pods -n production
kubectl get deployments --all-namespaces
kubectl get nodes
kubectl get services

Advanced label selectors (2025):

bash
# Single label match
kubectl get pods -l app=nginx

# Multiple labels (AND)
kubectl get pods -l app=nginx,env=production

# Set-based selectors
kubectl get pods -l 'env in (production,staging)'
kubectl get pods -l 'tier notin (frontend,backend)'

# Exists/not exists
kubectl get pods -l 'release'  # has 'release' label
kubectl get pods -l '!release'  # doesn't have 'release' label

# Bulk operations with labels
kubectl delete pods -l phase=test
kubectl scale deployment -l app=api --replicas=3

Describe resources:

bash
kubectl describe pod my-pod
kubectl describe node node-1
kubectl describe deployment my-app

View logs:

bash
kubectl logs my-pod
kubectl logs my-pod -c container-name
kubectl logs -f my-pod  # Follow logs
kubectl logs my-pod --previous  # Previous container logs
kubectl logs -l app=nginx  # Logs from all pods with label

Context and namespace management:

bash
kubectl config get-contexts
kubectl config current-context
kubectl config use-context production
kubectl config set-context --current --namespace=my-namespace

Rollout management and canary deployments:

bash
# View rollout status
kubectl rollout status deployment/my-app

# Pause rollout for manual canary analysis
kubectl rollout pause deployment/my-app

# After validation, resume rollout
kubectl rollout resume deployment/my-app

# Rollback if issues found
kubectl rollout undo deployment/my-app

# View rollout history
kubectl rollout history deployment/my-app

# Rollback to specific revision
kubectl rollout undo deployment/my-app --to-revision=2

Canary deployment workflow:

bash
# 1. Update deployment (triggers rollout)
kubectl apply -f deployment.yaml --server-side

# 2. Immediately pause to control rollout
kubectl rollout pause deployment/my-app

# 3. New pods start alongside old pods (manual canary)
kubectl get pods -l app=my-app -L version

# 4. Monitor metrics, test new version
# ... check logs, metrics, error rates ...

# 5. If good, resume full rollout
kubectl rollout resume deployment/my-app

# 6. If bad, rollback
kubectl rollout undo deployment/my-app

Troubleshooting Workflows

Pod Not Starting
bash
# 1. Check pod status
kubectl get pod my-pod -o wide

# 2. Describe pod to see events
kubectl describe pod my-pod

# 3. Check logs
kubectl logs my-pod

# 4. Check previous container logs if crash looping
kubectl logs my-pod --previous

# 5. Check events in namespace
kubectl get events --sort-by='.lastTimestamp' | grep my-pod
Debugging Running Pod
bash
# Execute commands in pod
kubectl exec -it my-pod -- sh
kubectl exec -it my-pod -c container-name -- bash

# Port forward to local machine
kubectl port-forward my-pod 8080:80

# Copy files to/from pod
kubectl cp my-pod:/path/to/file ./local-file
kubectl cp ./local-file my-pod:/path/to/file
Network Issues
bash
# Check service endpoints
kubectl get endpoints my-service

# Describe service
kubectl describe service my-service

# Test DNS resolution
kubectl run -it --rm debug --image=busybox --restart=Never -- nslookup my-service

# Check network policies
kubectl get networkpolicies
Resource Constraints
bash
# Check resource usage
kubectl top nodes
kubectl top pods
kubectl top pods --containers

# Describe resource limits
kubectl describe pod my-pod | grep -A 5 Limits

Common Patterns

Get Resource in Specific Format
bash
# JSON output
kubectl get pod my-pod -o json

# YAML output
kubectl get pod my-pod -o yaml

# Custom columns
kubectl get pods -o custom-columns=NAME:.metadata.name,STATUS:.status.phase

# JSONPath
kubectl get pods -o jsonpath='{.items[*].metadata.name}'
Filtering and Selecting
bash
# By label
kubectl get pods -l app=nginx
kubectl get pods -l 'env in (production,staging)'

# By field
kubectl get pods --field-selector status.phase=Running
kubectl get pods --field-selector metadata.namespace!=kube-system
Watch Resources
bash
# Watch for changes
kubectl get pods --watch
kubectl get pods -w

# Watch with timestamps
kubectl get pods --watch --output-watch-events

Best Practices and Smart Defaults (2025)

Infrastructure as Code
  1. Always use version control for manifests:

    bash
    # Good: Manifests in git
    git add k8s/
    git commit -m "Update deployment replicas"
    kubectl apply -f k8s/ --server-side
    
    # Bad: Imperative changes (lost on next apply)
    kubectl scale deployment my-app --replicas=5
  2. Prefer server-side apply for all manifest applications

    bash
    # Default to server-side
    kubectl apply -f . --server-side --recursive
  3. Preview changes before applying:

    bash
    # Always diff first
    kubectl diff -f deployment.yaml
    # Then apply
    kubectl apply -f deployment.yaml --server-side
  4. Use kubectl diff as pre-commit hook:

    bash
    # .git/hooks/pre-commit
    kubectl diff -f k8s/ --exit-code
Show full SKILL.md (191 more words)Show less
Runtime Notes (K8s 1.33)
  • Containerd is now the default runtime (Docker deprecated since 1.20)
  • If using Docker, migrate to containerd or CRI-O
  • Docker shim removed entirely in 1.33+
bash
# Check current runtime
kubectl get nodes -o wide
# Look at CONTAINER-RUNTIME column

# Verify containerd
kubectl describe node <node-name> | grep "Container Runtime"

Security Best Practices

  1. Use Namespaces: Isolate workloads with namespaces
  2. RBAC: Follow principle of least privilege
  3. Network Policies: Restrict pod-to-pod communication
  4. Resource Limits: Always set memory and CPU limits
    yaml
    resources:
      limits:
        memory: "256Mi"
        cpu: "500m"
      requests:
        memory: "128Mi"
        cpu: "250m"
  5. Security Contexts: Run containers as non-root when possible
    yaml
    securityContext:
      runAsNonRoot: true
      runAsUser: 1000
      readOnlyRootFilesystem: true
  6. Secrets: Use Kubernetes Secrets, never hardcode credentials
  7. Label Consistency: Use consistent labels for filtering and RBAC
    yaml
    labels:
      app: nginx
      env: production
      version: v1.2.3

Common Issues and Solutions

ImagePullBackOff
bash
# Check image name and tag
kubectl describe pod my-pod | grep Image

# Check image pull secrets
kubectl get secrets
kubectl describe secret my-registry-secret

# Check node's ability to pull
kubectl describe node my-node | grep -A 10 Conditions
CrashLoopBackOff
bash
# View current logs
kubectl logs my-pod

# View previous logs
kubectl logs my-pod --previous

# Check liveness/readiness probes
kubectl describe pod my-pod | grep -A 5 Probes

# Temporarily disable probes (edit deployment)
kubectl edit deployment my-app
Pending Pods
bash
# Check events
kubectl describe pod my-pod | grep Events -A 10

# Check node resources
kubectl top nodes
kubectl describe nodes

# Check PVC status
kubectl get pvc

Examples

Example 1: Complete Pod Debugging
bash
#!/bin/bash
POD=$1

echo "=== Pod Status ==="
kubectl get pod "$POD" -o wide

echo "\n=== Pod Events ==="
kubectl describe pod "$POD" | grep Events -A 20

echo "\n=== Pod Logs ==="
kubectl logs "$POD" --tail=50

echo "\n=== Resource Usage ==="
kubectl top pod "$POD" --containers
Example 2: Find Pods Using Most Resources
bash
# CPU
kubectl top pods --all-namespaces --sort-by=cpu

# Memory
kubectl top pods --all-namespaces --sort-by=memory
Example 3: Quick Health Check
bash
# Check cluster health
kubectl get nodes
kubectl get componentstatuses
kubectl get pods --all-namespaces --field-selector=status.phase!=Running

# Check critical system pods
kubectl get pods -n kube-system

Advanced Operations

Bulk Operations
bash
# Delete all pods with label
kubectl delete pods -l app=old-version

# Scale all deployments
kubectl get deployments -o name | xargs -I {} kubectl scale {} --replicas=3

# Restart all pods in deployment (rollout restart)
kubectl rollout restart deployment my-app
Debug with Ephemeral Containers
bash
# Add debug container to running pod (K8s 1.23+)
kubectl debug my-pod -it --image=busybox --target=my-container

# Create debug pod as copy
kubectl debug my-pod -it --copy-to=my-pod-debug --container=debugger --image=busybox

When to Ask for Help

Ask the user for clarification when:

  • The cluster context or namespace is ambiguous
  • Destructive operations are needed (delete, drain, cordon)
  • RBAC permissions might be insufficient
  • The issue requires changes to cluster configuration
  • Multiple pods/deployments match the criteria

© shepherdjerred, GPL-3.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in packages/dotfiles/dot_agents/skills/kubectl-helper of shepherdjerred/monorepo.

Open the folder on GitHubat commit bc57ca5

Compare with similar skills

Kubectl Helper next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Kubectl Helper compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Kubectl Helper this skillshepherdjerred/monorepo112—~2.8kAutomated safety check: PassGPL-3.0
LangBot Deployment Guidelangbot-app/LangBot18k—~1.2kAutomated safety check: NotesApache-2.0
Build Openshell Mxc WindowsNVIDIA/OpenShell16k—~4.9kAutomated safety check: PassApache-2.0
Devopsnicepkg/auto-company1942 repos~814Automated safety check: PassMIT
Debug Openshell ClusterNVIDIA/OpenShell16k—~19kAutomated safety check: NotesApache-2.0
Deepseek Harness Dockerrunzhliu/deepseek-harness-docker110—~2.7kAutomated safety check: NotesMIT

Similar skills

  • LangBot Deployment Guide

    langbot-app/LangBot

    Deploys and configures a LangBot instance with Docker Compose or Kubernetes, covering config.yaml, the Box sandbox runtime, the plugin runtime and the global API key.

    18k GitHub stars~1.2k tokensUpdated today
    DevOps & CloudAuto-check: notes
  • Official

    Maintain and validate OpenShell's build-only Windows MSVC lane for x64 and ARM64.

    16k GitHub stars~4.9k tokensUpdated today
    DevOps & CloudAuto-check passed
  • Devops

    nicepkg/auto-company

    Deploy to Cloudflare (Workers, R2, D1), Docker, GCP (Cloud Run, GKE), Kubernetes (kubectl, Helm).

    194 GitHub starsUsed in 2 repos~814 tokens
    DevOps & CloudAuto-check passed
  • Debug Openshell Cluster

    NVIDIA/OpenShell

    Official

    Debug why an OpenShell gateway deployment is unhealthy, unreachable, or unable to create sandboxes.

    16k GitHub stars~19k tokensUpdated today
    DevOps & CloudAuto-check: notes
  • Deepseek Harness Docker

    runzhliu/deepseek-harness-docker

    Deploy, configure, verify, upgrade, and troubleshoot DeepSeek Harness with the community Docker, Docker Compose, rootless Podman, and Helm runtime, including the built-in Chromium/noVNC browser…

    110 GitHub stars~2.7k tokensUpdated yesterday
    DevOps & CloudAuto-check: notes
  • Pi K8s Deploy

    rodrigorodrigues/microservices-design-patterns

    Check Docker Hub for a new :latest image on a managed service and roll it out to the home Pi k8s cluster, the same way authentication-service was deployed on 2026-08-29 (SSH + kubectl rollout…

    187 GitHub stars~1.6k tokensUpdated 20 days ago
    DevOps & CloudAuto-check passed

More from shepherdjerred/monorepo

All 63 skills in this repo
  • Bun Runtime Best Practices

    shepherdjerred/monorepo

    Bun runtime APIs and current operational patterns for files, processes, modules, networking, databases, tests, and deployment.

    112 GitHub stars~2k tokensUpdated today
    Auto-check passed
  • Bun Test Patterns

    shepherdjerred/monorepo

    Current Bun test runner guidance for discovery, isolation, parallelism, sharding, changed tests, mocks, timers, snapshots, coverage, DOM Testing Library, and integration teardown.

    112 GitHub stars~2k tokensUpdated today
    Auto-check passed
  • Bun Workspaces

    shepherdjerred/monorepo

    Current Bun workspace guidance for isolated and hoisted linkers, catalogs, filters, scripts, dependency classes, lockfiles, lifecycle trust, caches, publishing, TypeScript package exports, and…

    112 GitHub stars~2.2k tokensUpdated today
    Auto-check passed
  • Deep Research

    shepherdjerred/monorepo

    This skill should be used when the user asks to "deep research", "research this topic", "investigate thoroughly", "do a deep dive on", "comprehensive research on", "find everything about", "survey…

    112 GitHub stars~4.7k tokensUpdated today
    Auto-check: notes
  • Figma Use

    shepherdjerred/monorepo

    This skill should be used when the user asks to "create a Figma design", "design in Figma", "make a Figma mockup", "create an app icon", "design UI", "render JSX to Figma", "export from Figma"…

    112 GitHub stars~946 tokensUpdated today
    Auto-check passed
  • Fish Helper

    shepherdjerred/monorepo

    Current Fish shell scripting, functions, abbreviations, completions, variables, events, configuration, plugins, testing, and safety guidance.

    112 GitHub stars~2k tokensUpdated today
    Auto-check passed

Categories

Questions about Kubectl Helper

What does Kubectl Helper do?

Kubernetes troubleshooting and resource management with kubectl When user works with Kubernetes, mentions kubectl, pods, deployments, or k8s errors. Kubectl Helper is an agent skill from shepherdjerred/monorepo.

When should I use Kubectl Helper?

Kubectl Helper fits situations like: works with Kubernetes; mentions kubectl.

How do I install Kubectl Helper in Claude Code?

Run `npx skills add shepherdjerred/monorepo --skill kubectl-helper -a claude-code`. Or copy the skill folder (packages/dotfiles/dot_agents/skills/kubectl-helper in shepherdjerred/monorepo) into .claude/skills/kubectl-helper in your project. Claude Code loads it when a task matches its description.

How do I install Kubectl Helper in Codex?

Run `npx skills add shepherdjerred/monorepo --skill kubectl-helper -a codex`. Or copy the skill folder (packages/dotfiles/dot_agents/skills/kubectl-helper in shepherdjerred/monorepo) into .agents/skills/kubectl-helper in your project. Codex loads it when a task matches its description.

Can I use Kubectl Helper in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add shepherdjerred/monorepo --skill kubectl-helper -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/kubectl-helper, .gemini/skills/kubectl-helper, .github/skills/kubectl-helper and .opencode/skills/kubectl-helper in your project.

What does Kubectl Helper need to run?

Going by SKILL.md and its folder, Kubectl Helper needs the command-line tools its instructions call (kubectl and git). Our summary lists: Docker.

Does Kubectl Helper access the network?

SKILL.md contains no URLs. Its commands use git, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Kubectl Helper safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Kubectl Helper use?

Kubectl Helper is published under the GPL-3.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Kubectl Helper use?

About 2.8k tokens (SKILL.md is roughly 11k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Kubectl Helper?

Skills that share tags, products or a category with Kubectl Helper: LangBot Deployment Guide (langbot-app/LangBot, 18k stars), Build Openshell Mxc Windows (NVIDIA/OpenShell, 16k stars), Devops (nicepkg/auto-company, 194 stars) and Debug Openshell Cluster (NVIDIA/OpenShell, 16k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Kubectl Helper?

shepherdjerred (a GitHub user) maintains it in shepherdjerred/monorepo, which has 112 GitHub stars. The repository holds 63 skills in this directory. The repository was last updated on October 9, 2026.

Source: shepherdjerred/monorepo on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.