configure-skaffold

/configure:skaffold

检查 Skaffold 配置并使其符合项目标准。

何时使用此技能

在以下情况下使用此技能……	在以下情况下采用其他方法……
检查 Kubernetes 项目的 Skaffold 配置是否合规	项目没有 k8s/ 或 helm/ 目录（Skaffold 不适用）
修复端口转发安全问题（绑定到 0.0.0.0）	直接管理 Kubernetes 清单或 Helm chart
添加 dotenvx 钩子以在 Skaffold 中生成密钥	配置不使用 Kubernetes 的容器构建（使用 /configure:dockerfile）
将 Skaffold API 版本升级到最新版本	调试 Skaffold 运行时错误（使用 system-debugging agent）
根据模板创建标准 skaffold.yaml	设置非 Skaffold 的本地开发工作流（例如 Docker Compose）

上下文

• K8s/Helm 目录：!find . -maxdepth 1 -type d \( -name 'k8s' -o -name 'helm' \)
• Skaffold 配置：!find . -maxdepth 1 -name \'skaffold.yaml\'
• Skaffold API 版本：!grep -m1 apiVersion skaffold.yaml
• 端口转发配置：!grep -m1 address skaffold.yaml
• 已定义的配置档：!grep -m10 'name:' skaffold.yaml
• generate-secrets 脚本：!find . -maxdepth 1 -name \'scripts/generate-secrets.sh\'
• dotenvx 是否可用：!command -v dotenvx
• 项目标准：!find . -maxdepth 1 -name '.project-standards.yaml' -type f

引用的技能：skaffold-standards、container-development、skaffold-orbstack

适用范围：仅适用于使用 Kubernetes 部署的项目（包含 k8s/、helm/ 目录）

参数

从 $ARGUMENTS 解析以下参数：

标记	描述
--check-only	报告状态，不提供修复方案
--fix	自动应用修复

版本检查

重要：配置 Skaffold 前，先验证最新版本：

1. Skaffold：查看 skaffold.dev 或 GitHub releases
2. API 版本：当前推荐版本为 skaffold/v4beta13
3. dotenvx：查看 dotenvx.com 了解最新用法

使用 WebSearch 或 WebFetch 验证当前的 Skaffold 版本和 API 版本。

执行

执行以下 Skaffold 合规性检查：

步骤 1：检查适用性

检查是否存在 k8s/ 或 helm/ 目录。如果两者都不存在，则报告“SKIP: Skaffold not applicable (no Kubernetes manifests)”并停止。如果存在，则继续检查 skaffold.yaml。

步骤 2：解析配置

读取 skaffold.yaml 并提取：

• API 版本
• 构建配置（local.push、useBuildkit）
• 部署配置（kubeContext、statusCheck）
• 端口转发（addresses）
• 已定义的配置档
• 钩子（dotenvx 集成）

步骤 3：分析合规性

根据以下标准检查每项设置：

检查项	标准	严重性
API 版本	skaffold/v4beta13	如果版本较旧则为 WARN
local.push	false	如果为 true 则为 FAIL
portForward.address	127.0.0.1	如果缺失或为 0.0.0.0 则为 FAIL
useBuildkit	true	如果为 false 则为 WARN
kubeContext	orbstack	INFO（建议用于本地开发）
dotenvx 钩子	构建或部署钩子	INFO（建议用于密钥管理）

安全关键项：端口转发必须仅绑定到本地主机（127.0.0.1）。绝不能使用 0.0.0.0，也不能缺少 address。

建议设置：

• 为本地开发工作流使用 db-only 或 services-only 配置档
• 使用 statusCheck: true 并设置合理的截止时间（init 容器为 180s）
• 设置 tolerateFailuresUntilDeadline: true，以便 Pod 平稳初始化
• 使用 JSON 日志解析来处理结构化应用日志
• 使用 dotenvx 钩子从 .env 文件生成密钥

步骤 4：报告结果

打印合规性报告，包含：

• Skaffold 文件位置和 API 版本
• 每项配置检查的结果（PASS/WARN/FAIL）
• 找到的配置档
• 脚本状态（generate-secrets.sh）
• 总体合规状态

如果指定了 --check-only，则在此处停止。

第 5 步：应用修复（如果使用了 --fix 或用户确认）

1. 缺少 skaffold.yaml：根据 REFERENCE.md 中的标准模板创建
2. 安全问题：将端口转发地址修复为 127.0.0.1
3. 缺少配置文件：添加 db-only 配置文件模板
4. API 已过时：将 apiVersion 更新为 v4beta13
5. 缺少 dotenvx 钩子：添加密钥生成钩子
6. 缺少脚本：根据 REFERENCE.md 中的模板创建 scripts/generate-secrets.sh
7. 缺少 kubeContext：为本地开发添加 orbstack

第 6 步：更新标准跟踪

更新 .project-standards.yaml：

components:
  skaffold: "2025.1"

Agentic 优化

上下文	命令
快速合规性检查	/configure:skaffold --check-only
自动修复所有问题	/configure:skaffold --fix
检查 API 版本	head -5 skaffold.yaml | grep apiVersion
检查端口转发安全性	grep -A2 'portForward' skaffold.yaml | grep address
列出配置文件	grep 'name:' skaffold.yaml | grep -v metadata

安全说明

端口转发未设置 address: 127.0.0.1 会导致服务暴露到网络中。这属于失败情形，应始终修复。

标准 Skaffold 模板、dotenvx 集成模式和 generate-secrets 脚本模板，请参阅 REFERENCE.md。

另请参阅

• /configure:dockerfile - 容器配置
• /configure:all - 运行所有合规性检查
• skaffold-standards 技能 - Skaffold 模式