/cluster-status

O Skill /cluster-status produz um único snapshot denso de saúde do cluster: detalhes gerais do cluster, quantos nodes e pods estão saudáveis, e uma lista classificada curta do que não está. É somente leitura e nunca muta o estado do cluster.

A saída é deliberadamente limitada (~10 linhas independentemente do tamanho do cluster) para que a primeira resposta seja barata de ler e de o modelo regenerar. O detalhe completo por node e por pod é escrito em um cache JSON local que o agent lê nas perguntas de acompanhamento, sem precisar consultar a API novamente.

/cluster-status                    # snapshot (uses cache if fresh)
/cluster-status --refresh          # force a fresh fetch
/cluster-status --ttl 1h           # only re-fetch if older than 1h

Este Skill não aceita argumentos posicionais. Perguntas de acompanhamento (“listar pods”, “quais nodes estão com taint”, “pods no worker-3”) são respondidas a partir do cache — veja Acompanhamentos abaixo.

---

O que coleta

Bundle inicial

• Metadados do cluster (cluster.json) — nome do contexto, versão do Kubernetes e plataforma (EKS, GKE, kind, etc.), via kubectl version e kubectl cluster-info.
• Lista de nodes (nodes.json) — labels, taints, condições (Ready, MemoryPressure, DiskPressure, PIDPressure, SchedulingDisabled), capacidade, alocável e papel de control-plane vs. worker de cada node.
• Lista de pods (pods.json) — todos os pods em todos os namespaces, incluindo fase, condição Ready, status dos containers, contagens de reinicialização, owner references e o node em que cada pod está agendado.

Fontes: apenas a API do Kubernetes — kubectl version, kubectl get nodes -o json e kubectl get pods -A -o json, em paralelo. Os três arquivos são escritos em um diretório de cache por contexto e reutilizados nos acompanhamentos dentro da janela TTL.

---

O que verifica

Verificações

• Identidade do cluster — nome do contexto, versão do Kubernetes e plataforma (EKS, GKE, kind, etc.)
• Status Ready do node, condições MemoryPressure / DiskPressure / PIDPressure, SchedulingDisabled, e divisão control-plane vs. worker
• Fase e condição Ready dos pods em todos os namespaces, mais pods com contagens de reinicialização não-zero
• Uma lista classificada de principais problemas (top 5 por severidade, com um “…e mais N” quando o cluster tem muita coisa errada)

Fontes: apenas a API do Kubernetes — kubectl version, kubectl get nodes e kubectl get pods -A, em paralelo.

---

Como funciona

O Skill busca as três listas concorrentemente e escreve cada uma em um diretório de cache por contexto como cluster.json, nodes.json e pods.json. Agregação e classificação por severidade acontecem no lado do cliente sobre esse JSON, de modo que execuções repetidas dentro da janela TTL ignoram completamente a API.

O bloco de resumo tem este formato:

Cluster: prod-us-east · Kubernetes v1.30.4 · EKS

Nodes  12/12 Ready · 1 pressure · 0 unschedulable · 3 control-plane, 9 worker
Pods   184/187 Ready · 4 pod(s) with restarts

Issues (6):
  payments/checkout-7c9  CrashLoopBackOff  17 restarts in 42m
  ingress/nginx-0        MemoryPressure    node ip-10-0-3-14
  ...                                      (top 5 by severity)
  …and 1 more

Snapshot cached (TTL 15m). Ask to drill in — e.g. "list nodes", "list pods", "pods on <node>", "which nodes are tainted".

O bloco Issues é omitido quando o cluster está limpo. O rodapé informa se o snapshot foi obtido recentemente ou servido do cache, e a idade dos dados em cache.

---

Acompanhamentos

O resumo omite deliberadamente as tabelas por node e por pod para que a resposta inicial permaneça pequena. Quando você pede para vê-las — ou faz qualquer pergunta que possa ser respondida a partir dos três arquivos JSON em cache — o agent lê o cache com jq em vez de re-executar o Skill:

❯ /cluster-status
[ summary... ]

❯ list pods
[ full pod table, rendered from pods.json ]

❯ which pods are on ip-10-0-3-14?
[ filtered from pods.json ]

Para dados que não estão no cache (events, logs, YAML de um recurso específico), o agent roteia para o Skill certa — /events, /logs ou /investigate — em vez de ampliar o /cluster-status.

Diga “atualizar” / “buscar novamente” / “verificar de novo” e o agent re-invoca o Skill com --refresh.

---

O que o agent é instruído

Além de buscar as três listas, o Skill orienta o agent sobre como se comportar nos acompanhamentos:

• Preferir responder a partir do cluster.json / nodes.json / pods.json em cache com jq em vez de re-invocar o Skill — o cache é o objetivo do resumo limitado.
• Re-invocar com --refresh apenas quando o usuário pedir ou quando o acompanhamento for claramente sensível ao tempo (“o node já se recuperou?”).
• Manter o resumo curto — rotear pedidos de detalhes (tabelas completas, drill-downs por node) para leituras do cache em vez de crescer o bloco de resumo.
• Encaminhar para /events, /logs ou /investigate para qualquer coisa que não esteja nos três arquivos em cache, em vez de ampliar este Skill.

---

Opções

--refresh

Ignora o cache e busca dados frescos da API.

--ttl <duration>

Só re-busca se o snapshot em cache for mais antigo que isso (estilo kubectl: 5m, 1h, 24h). Padrão: 15m. Ignorado quando —refresh está definido.

Sinalizadores globais de Visão geral também se aplicam.