googs1025/kube-agent-helper

O que kube-agent-helper faz?

Assistente de diagnóstico nativo do Kubernetes alimentado pelo Claude Agent SDK + SKILL.md declarativo.

Visão Geral

Esta skill capacita agentes de IA (como o Claude Code) a ajudar desenvolvedores e operadores a diagnosticar e resolver problemas dentro de clusters Kubernetes. Ela segue um conjunto de instruções estruturadas (detalhadas em SKILL.md) que orientam o agente sobre como inspecionar recursos do cluster, interpretar logs e sugerir ações corretivas.

Como funciona

1. O agente lê o arquivo SKILL.md que define:
   • Quais comandos kubectl usar para diferentes cenários de diagnóstico (ex.: kubectl describe pod, kubectl logs, kubectl get events).
   • Como analisar a saída desses comandos (ex.: procurar por CrashLoopBackOff, ImagePullBackOff, Pending).
   • Recomendações acionáveis baseadas em padrões observados (ex.: corrigir limites de recursos, verificar secrets, ajustar health checks).
2. O usuário interage com o agente no chat, descrevendo o problema (ex.: "Meu pod está falhando com CrashLoopBackOff").
3. O agente executa os comandos, analisa os resultados, e retorna um diagnóstico claro junto com passos sugeridos para correção.

Exemplo de uso

# Suponha que o agente esteja ativo no Claude Code
$ kubectl get pods -n minha-aplicacao
NAME                     READY   STATUS             RESTARTS   AGE
app-frontend-5d8f-2k9s   0/1     CrashLoopBackOff   3          2m

# Pergunte ao agente:
"Por que meu pod app-frontend está em CrashLoopBackOff? O que devo fazer?"

# O agente executará comandos como:
kubectl describe pod app-frontend-5d8f-2k9s -n minha-aplicacao
kubectl logs app-frontend-5d8f-2k9s -n minha-aplicacao --previous
kubectl get events -n minha-aplicacao --sort-by='.lastTimestamp' | tail -5

# E retornará um diagnóstico como:
"O pod está falhando devido a um erro de memória (OOMKilled). Sugiro aumentar o limite de memória no deployment ou otimizar o consumo de memória da aplicação."

Configuração

1. Certifique-se de que o Claude Agent SDK ou ferramenta compatível esteja instalado e autenticado.
2. Coloque o repositório da skill em seu caminho de skills ou configure o agente para carregá-la.
3. (Opcional) Defina variáveis de ambiente como KUBECONFIG para apontar para o cluster correto.

Pré-requisitos

• Acesso a um cluster Kubernetes (via kubectl).
• Claude Code ou outra ferramenta compatível com o Claude Agent SDK.
• Permissões adequadas de RBAC para ler recursos do cluster (pods, serviços, eventos, etc.).

Limitações

• A skill depende da capacidade do agente de executar comandos kubectl; portanto, o agente deve ter permissão para isso.
• Diagnósticos mais avançados (ex.: análises de rede ou fluxo de tráfego) podem não ser cobertos e exigem conhecimento humano.
• A qualidade da análise depende da completude e precisão do SKILL.md instruído.

Contribuindo

• Sinta-se à vontade para fazer fork e modificar o SKILL.md para adicionar novos cenários de diagnóstico ou melhorar os existentes.
• Abra issues para reportar problemas ou sugerir novos diagnósticos Kubernetes.

Licença

MIT - consulte o arquivo LICENSE no repositório original para detalhes.