.pouch/skills/publish-docker-image/SKILL.md

name, description

name	description
publish-docker-image	构建当前项目的 Docker 镜像，并将其上传到用户指定的镜像仓库。仅当用户显式指定 $publish-docker-image 或明确说“使用 publish-docker-image skill”时使用； 不要因普通编码、编辑 Dockerfile、本地构建、测试或一般 Docker 问题而自动触发。

发布 Docker 镜像

安全、可复现地构建当前提交对应的 Docker 镜像，并按用户指定的目标上传。

执行流程

1. 读取项目的 AGENTS.md、Dockerfile、构建脚本和相关发布文档。
2. 收集目标 registry、repository、tag、platform、构建上下文和 Dockerfile。优先使用用户已明确提供的值；缺少会改变发布结果的值时，停止并询问。
3. 检查 Git 工作区与当前提交。若存在未提交修改，明确说明镜像将包含哪些修改。
4. 按 registry.md 检查仓库规则和认证状态。
5. 在执行外部写操作前，向用户展示完整镜像引用、platform、Dockerfile、构建上下文和源 commit。只有用户已明确要求上传到该目标时才继续。
6. 使用 publish.sh 构建并上传。不要自行拼接包含凭据的命令。
7. 检查命令退出状态，并尽可能获取远端 digest。
8. 汇报完整镜像引用、digest、platform、源 commit，以及是否包含未提交修改。

命令

默认构建并上传：

scripts/publish.sh \
  --registry REGISTRY \
  --repository NAMESPACE/IMAGE \
  --tag TAG \
  --platform PLATFORM

先验证而不构建或上传：

scripts/publish.sh \
  --registry REGISTRY \
  --repository NAMESPACE/IMAGE \
  --tag TAG \
  --platform PLATFORM \
  --dry-run

仅当用户明确要求本地构建时使用 --load。多平台镜像不能使用 --load。

安全边界

• 不把密码、访问令牌或 Docker 配置写入 skill、项目文件、命令参数或输出。
• 不主动执行 docker login；认证缺失时让用户通过交互式登录或其凭据管理器完成。
• 不覆盖已存在的 release tag，除非用户明确授权。无法可靠检查远端 tag 时说明这一限制。
• 不把 latest 作为隐含默认 tag。
• 不上传用户未指定的附加 tag。
• 不擅自修改 Dockerfile、发布配置、仓库权限或镜像保留策略。
• 若仓库、tag、platform 或目标环境存在歧义，在上传前询问用户。

验证

• 确认 docker buildx build 成功且启用了 --push。
• 优先用 docker buildx imagetools inspect FULL_IMAGE_REF 验证远端引用及平台。
• 记录远端 digest；若仓库不允许检查，明确报告只验证了 push 命令成功。
• 将发布所用的 Git commit 与工作区状态一并报告。