KubeShark (kubernetes-skill) 快速入门

这是什么？适合谁？

KubeShark（LukasNiessen/kubernetes-skill，374 Stars）是一个面向 Claude Code 和 Codex 的 Kubernetes Skill，定位”修复 K8s 幻觉”：LLM 生成 K8s 清单时经常漏掉 securityContext、用已废弃 API、写通配符 RBAC、忘资源限制、配错探针引发级联失败—KubeShark 用官方最佳实践约束 Agent，让它输出安全、可靠、生产可用的 manifest。

它的三个差异化卖点：按星数排名第一的 K8s Skill（作者自述）；Token 高效（激进去重，不把整个 K8s 文档倒给 Agent）；基于权威来源（官方 K8s 文档、NSA/CISA 加固指南、OWASP Kubernetes Top 10、Pod Security Standards、CIS Benchmark，冲突时以官方文档优先）。

适合人群：

• 平台工程师/DevOps：每天让 Agent 写 Helm/Kustomize/清单，被幻觉 API 版本折磨的人
• 后端开发者赶 K8s 上手：想要”生成即合规”的清单底稿
• SRE：评审他人清单时想要一个自动对照 CIS/NSA 基线的助手
• 多集群运维（EKS/GKE/AKS/OpenShift）：Skill 内置发行版差异检查（CNI、存储类、GitOps 控制器）

不适合：想学 Kubernetes 概念的纯新手（它是纠错器不是教程）；需要管理大规模集群状态的工具型需求（它是生成/审查层，不是 controller）。

使用前提：支持 skills 目录或 skills CLI 的 Agent 宿主（Claude Code / Codex）；对 K8s 有基本词汇量（知道 Deployment/Ingress/RBAC 是什么）。

准备工作

• Agent 宿主：Claude Code 或 Codex CLI（两者官方徽章认证支持）
• 安装方式三选一：skills CLI / git clone / marketplace 插件（见下）
• 时间预算：安装 2 分钟；Skill 自动按工作流触发，零学习成本
• 成本：MIT 开源免费，只花自己的 LLM tokens
• 目标环境信息：使用前准备好集群版本（如 1.30/1.31）、发行版（EKS/GKE/AKS/k3s）、命名空间与环境等级（dev/staging/prod）—SKILL.md 第 1 步就要求记录这些上下文

快速上手（3 步）

第一步：安装（三选一）

# 方式 1：skills CLI（推荐）
npx skills add https://github.com/lukasniessen/kubernetes-skill --skill kubernetes-skill

# 方式 2：git clone（macOS/Linux）
git clone https://github.com/LukasNiessen/kubernetes-skill.git ~/.claude/skills/kubernetes-skill

# 方式 2b：Windows PowerShell
git clone https://github.com/LukasNiessen/kubernetes-skill.git "$env:USERPROFILE\.claude\skills\kubernetes-skill"

skills CLI 方式自动发现、无需重启；clone 方式 Claude Code 也会自动发现 ~/.claude/skills/ 下的 skill。

第二步：触发第一个清单生成

在新项目里直接让 Agent 写部署清单：

给这个 Go 服务写一份生产级 Deployment + Service + Ingress，
EKS 1.31，namespace payments，含资源限制和探针。

KubeShark 的工作流自上而下执行：先捕获执行上下文（集群版本/发行版/环境等级/部署方式/策略执行层/云厂商与 CNI/平台控制器），再按失败模式清单生成清单。

第三步：验证输出质量

对照检查生成结果：

• ✅ Pod 有 securityContext（runAsNonRoot、seccompProfile、去掉多余 capability）
• ✅ 无已废弃 API（如 policy/v1beta1/PodDisruptionBudget）
• ✅ RBAC 无 resources: ["*"] 通配
• ✅ 有 resources requests/limits
• ✅ 探针有合理的 failureThreshold/periodSeconds，不会级联重启

成功判定：以上五项全过；对照 NSA/CISA 加固指南 的关键项无缺失。

初级用法

• 生成新清单：Deployment/StatefulSet/Job/CronJob/Helm values/Kustomize overlay，自动带安全默认值
• 审查既有清单：把仓库里的 yaml 丢给 Agent”用 KubeShark 失败模式审查”，输出问题清单
• 迁移辅助：老集群升级前重写废弃 API；跨发行版迁移（EKS->GKE）时自动换存储类/负载均衡注解
• 策略对照：配合 Pod Security Admission level（baseline/restricted）生成合规 workload

高级玩法

1. 失败模式工作流：SKILL.md 把 K8s 常见坑组织成六大失败模式（不安全默认值/资源饥饿/网络暴露/权限蔓延/脆弱滚动/API 漂移），按模式逐项排查，可当作团队的 K8s code review checklist
2. GitOps 场景：把 KubeShark 装进 Argo CD 仓库的 Agent 流程，PR 生成阶段就拦住不合规 manifest
3. 多发行版矩阵：EKS/GKE/AKS/OpenShift 差异（Ingress 类、LB 注解、PSP 替代方案）在生成时一次性问清，避免”能跑在 k3s 跑不了在 OpenShift”
4. 与安全 Skill 组合：先 KubeShark 生成清单，再用 AAS 的 k8s-security-policies / container-security-hardening 做二道审查，双保险
5. Token 预算管理：作者强调”质量/Token 比”，大型 monorepo 里可只对 infra 目录启用，避免无关会话加载

常见踩坑（5 条）

踩坑 1：以为装了就万事大吉

• 现象：生成清单仍有幻觉
• 原因：SKILL.md 第 1 步要求先记录集群上下文，你没提供版本/发行版信息时 Agent 只能猜
• 解决：prompt 里主动给出集群版本、发行版、namespace 等级；或维护一个 CLAUDE.md 集群档案

踩坑 2：Windows 路径写错

• 现象：clone 后 Claude Code 不识别
• 原因：Windows 下目标路径要用 $env:USERPROFILE\.claude\skills\...
• 解决：用 README 提供的 PowerShell 版本命令，别照抄 macOS 路径

踩坑 3：把 restricted 级别到处套

• 现象：所有 namespace 都用 Pod Security restricted，老应用跑不起来
• 原因：不同 workload 类型对 securityContext 的要求不同
• 解决：dev 用 baseline、生产前端用 restricted 分级；KubeShark 会按环境等级差异化生成

踩坑 4：探针配置照抄默认

• 现象：滚动更新时服务抖动
• 原因：liveness 与 readiness 探针阈值没按启动时长调整
• 解决：明确告诉 Agent 服务的启动时间与依赖，让它给出 failureThreshold 推导而非模板值

踩坑 5：混用多个 K8s Skill

• 现象：输出时好时坏，规则冲突
• 原因：同时加载多个 K8s skill（模板型/教程型），提示词互相打架
• 解决：只保留 KubeShark 一个 K8s skill；它是”防幻觉”定位，与资源模板类 skill 二选一

小技巧（5 条）

1. 让 Agent 自报上下文：开工前问它”KubeShark 第 1 步要求记录哪些执行上下文？“逼它先建档案再生成
2. 审查模式提问法：“用 KubeShark 的失败模式清单审查这份 Helm values，按严重性排序”，比”看看有什么问题”输出质量高得多
3. PHILOSOPHY.md 值得一读：仓库附带作者的设计哲学（为何激进去重、为何以官方文档为最高优先级），理解后能更好预判输出边界
4. CHANGELOG 跟进：K8s API 废弃节奏快，skill 数据更新跟着 K8s 版本走，定期 git pull
5. ISSUE 反馈：仓库 open issues 只有 2 个且响应快，发现漏检的失败模式直接提 issue

常见问题 FAQ

Q1：KubeShark 免费吗？

A：MIT 开源完全免费，374 Stars（2026-08-20 采集）。费用只有你自己付给 LLM 提供商的 tokens；作者有 GitHub Sponsors 赞助入口但无付费墙。

Q2：它和直接把 K8s 文档塞进上下文有什么区别？

A：文档塞入法 token 成本高且 LLM 仍会跳读；KubeShark 做了激进去重，只保留”失败模式->检查项”的决策路径，官方称同等质量下 token 消耗低得多。

Q3：支持 Codex 吗？

A：支持。README 同时带 Claude Skill 和 Codex Skill 官方徽章，安装走各自的 skills 机制。

Q4：能管理已有集群吗？

A：不能。它是清单生成/审查层，不连接 kube-apiserver、不做漂移检测；运行时治理请用 Kyverno/OPA 等策略引擎，两者互补。

Q5：更新频率如何？

A：最近一次推送 2026-08-16（采集时点四天内），CHANGELOG 持续维护，跟 K8s 版本节奏走。

进阶学习建议

• 通读 SKILL.md 的失败模式工作流全文：六大失败模式（insecure workload defaults / resource starvation / network exposure / privilege sprawl / fragile rollouts / API drift）是 K8s 生产事故的极好归纳，值得背下来
• 对照 NSA/CISA Kubernetes Hardening Guide 与 CIS Kubernetes Benchmark，看 Skill 如何把两份基线裁剪成 Agent 可执行的检查粒度
• 读仓库的 PHILOSOPHY.md 与 references/ 目录，学习”token 效率优先”的 skill 设计取舍
• 把 KubeShark 的检查项导出为团队的 PR review checklist，人机双轨执行
• 实验对比：同一需求分别裸 prompt 与 KubeShark 生成，统计 securityContext/RBAC/探针五项命中率，建立自己的量化信任基线

参考链接

• kubernetes-skill GitHub 仓库
• SKILL.md（失败模式工作流全文）
• NSA/CISA Kubernetes Hardening Guide
• OWASP Kubernetes Top 10
• Pod Security Standards

本文基于公开资料于 2026-08-20 整理，社区指标来自 GitHub 公开数据。独立实测未进行，功能与配置可能随版本更新变化，请以官方仓库为准。