| name | generate-github-workflow |
| description | GitHub Actions YAML with embedded output contract: security-first, minimal permissions, version pinning. For CI, release, PR checks. Differs from generic templates by spec compliance and auditability. |
| description_zh | 生成嵌有输出契约的 GitHub Actions YAML：安全优先、最小权限、版本锁定；适用于 CI、发布与 PR 检查。 |
| tags | ["devops"] |
| version | 1.0.0 |
| license | MIT |
| recommended_scope | project |
| metadata | {"author":"ai-cortex"} |
| triggers | ["github workflow","generate workflow"] |
| input_schema | {"type":"free-form","description":"Workflow requirements (CI, release, PR checks) and project context"} |
| output_schema | {"type":"document-artifact","description":"GitHub Actions YAML workflow file(s) written to .github/workflows/"} |
技能（Skill）：生成GitHub工作流程
目的 (Purpose)
为各种软件项目生成满足此技能的 附录 A：工作流输出合同 的 GitHub Actions 工作流文件。标准化结构、触发器和安全性可降低 CI/CD 设置成本并提高可维护性和可审核性，同时避免常见的安全和权限问题。该技能仅产生工作流YAML；它与文档或规则技能无关。如果用户稍后需要 README 或 AGENTS.md 更新，请单独调用这些技能。
核心目标（Core Objective）
首要目标：针对用户的场景、堆栈和安全态势生成完整、符合规范且可立即运行的 GitHub Actions 工作流 YAML 文件 — 只需要替换占位符即可部署。
成功标准（必须满足所有要求）：
- ✅ 符合附录 A：输出满足附录 A 中的所有强制结构和安全需求（名称、工作、运行、步骤、固定操作、无硬编码秘密）
- ✅ 窄触发器：
on 块的范围仅限于特定分支/路径/标签 - 没有没有过滤器的裸露 on: Push
- ✅ 最小权限：在工作流程或作业级别将“权限”设置为场景类型所需的最低权限（CI：“内容：读取”；发布：“内容：写入”、“包：写入”）
- ✅ 堆栈对齐：Runner、语言版本、包管理器和命令与用户指定的堆栈匹配
- ✅ 写入前用户确认：列出必需的注释和占位符，并在写入
.github/Workflows/ 之前获得用户确认
验收测试：用户替换占位符后，除了秘密名称和环境特定值之外，工作流是否可以在目标存储库中运行而无需进一步修改？
范围边界（范围边界）
本技能负责：
- 为 CI、PR 检查、发布和计划场景生成完整的 GitHub Actions 工作流 YAML
- 安全强化（固定操作、最小权限、无硬编码秘密）
- 堆栈对齐（Node/Python/Go/Rust 运行程序、包管理器、构建命令）
- 多工作流生成（CI + Release 分成单独的文件）
- 与现有工作流程的冲突检测
- Go + Docker + GHCR + GoReleaser 模式（参见附录 B）
本技能不负责：
- 链接到文档技能（README、AGENTS.md 更新）——在工作流生成后单独调用这些技能
- 无需用户确认即可写入
.github/工作流s/
- 在没有警告的情况下覆盖现有的工作流程
- 实现已在“.goreleaser.yaml”或 Dockerfile 中定义的构建/发布逻辑
- 生成非 GitHub CI/CD（GitLab CI、Jenkins 等）
转交点：生成并确认工作流YAML后，经用户批准将文件写入.github/工作流/。对于新工作流触发的文档更新，请单独使用文档技能。
使用场景（用例）
- 新项目设置：将 CI（构建、测试、lint）或 PR 检查工作流添加到新存储库。
- 统一标准：在多个存储库中协调工作流程风格和命名，以进行操作和审计。
- 填补空白：使用最少的权限和固定版本将缺少的 CI/发布/预定工作流添加到遗留项目中。
- 基于场景：为给定场景生成 YAML（例如“仅在 PR 上运行测试”、“在标签上构建和发布”）。
何时使用：当用户或项目需要“为当前或指定项目创建或添加 GitHub 工作流”时。
范围：此技能的输出遵循嵌入式附录 A（狭窄的触发器、最小权限、固定版本、可审核）。通用模板（例如 Skills.sh github-actions-templates）更加通用；这项技能强调安全性和可维护性。
行为（行为）
原则（原则）
- 附录A具有权威性：输出的YAML必须满足附录A（结构、命名、安全性、可维护性）。
- 窄触发器：
on必须指定分支/路径/标签；避免每次推送时触发。常见模式：带有“branches”或“paths”的“push”/“pull_request”。 发布 工作流必须仅在版本标签上触发（例如push:tags:['v*']）并且存在于与 CI 不同的文件中。
- 最小权限：当工作流需要repo write、PR或Secrets时，将工作流或作业级别的“权限”设置为所需的最低权限；例如CI
内容：读取，释放内容：写入，包：写入；避免“全部”。
- 固定版本：固定第三方操作（提交 SHA 或主要版本标签）；不要使用“@master”或未固定的引用；更喜欢安全/扫描操作的特定版本（例如 Trivy）。
语气和风格
- 使用客观的技术语言；保持工作流程和步骤“名称”简短且便于操作日志阅读。
- 匹配项目堆栈：按项目类型（Node/Python/Go/Rust）和现有约定选择运行器、包管理器和构建命令；如果项目已经有工作流程，请调整命名和风格。
IN（输入）驱动
- 若存在
CLAUDE.md 或 .ai-cortex/config.yaml，优先读取其中的 test_command、base_branch 等；否则从用户输入或项目推断。参见 docs/guides/project-config.md。
- 使用用户的场景（例如“CI：在 PR 上运行测试”、“发布：在标签上构建和上传”）和 堆栈（语言、包管理器、测试/构建命令）来生成工作流；当信息丢失时使用合理的占位符并将其标记为替换；不要发明命令或路径。
交互（互动）
- 写入前确认：生成YAML后，列出必填注释（占位符、分支名称、用户必须设置的Secret名称），然后要求确认；不要写入
.github/工作流s/ 或在未经用户确认的情况下提交。
- 多个文件/发布：如果生成多个工作流（例如 CI + Release）或使用写入权限（
contents: write、packages: write），列出要创建/覆盖的文件和权限范围，然后在写入之前确认。
- 冲突：如果目标路径已经存在目的相同或重叠的工作流，则警告并询问是否覆盖或保存到其他地方；不要默默地覆盖。
输入与输出 (Input & Output)
输入（输入）
- 场景：目的（CI、PR 检查、发布、计划、矩阵）。
- Stack：语言和版本（例如 Node 20、Python 3.11、Go 1.21）、包管理器（npm/pnpm/yarn、pip、cargo）、测试/构建/发布命令。
- 触发器：分支（例如
main、develop）、路径过滤器、可选的工作流_dispatch。
- 目标路径：写入文件的位置，默认项目根目录下的
.github/Workflows/；对于多个工作流，指定每个文件名（例如“ci.yml”、“release.yml”）。
输出（输出）
- 工作流 YAML：完整文件内容符合附录 A，准备写入
.github/工作流s/<name>.yml。
- 注释：列出占位符（例如“npm run test”、分支“main”）、秘密名称以及用户必须配置的任何项目。
限制（限制）
硬边界（Hard Boundaries）
- 不要违反附录A：输出必须有
name、on、jobs，并且每个作业必须有runs-on和steps；不要使用未固定的第三方操作或硬编码的机密。
- 不要过度触发：除非用户明确请求，否则不要使用没有分支/路径过滤器的裸“on:push”。
- 不要发明命令：对未知的测试/构建/发布命令使用占位符并标记“替换为实际命令”；不要发明脚本或路径。
- 不要忽略现有的工作流：如果项目已经有
.github/工作流/，请调整命名和风格并避免重复或冲突。
- 不要重复构建逻辑：如果项目使用 GoReleaser、Dockerfile 等进行构建和镜像塑造，则工作流程仅触发、登录并传递参数（例如
GITHUB_TOKEN、BUILDX_BUILDER）；不要重新实现该逻辑。
技能边界 (Skill Boundaries)
不要做这些（其他技能可以处理它们）：
- 不要链接到文档或自述文件技能 - 单独调用它们
- 未经用户确认，请勿写入
.github/工作流s/
- 不要默默地覆盖现有的工作流程
- 不要重新实现
.goreleaser.yaml 或 Dockerfiles 中已定义的构建/发布逻辑
- 不要为非 GitHub 平台（GitLab CI、Jenkins 等）生成 CI/CD
何时停止并交接：
- 编写工作流文件并确认后，如果需要 README/AGENTS.md 更新，请移交给文档技能
- 当用户需要注册表或机密配置时，提供指导但不自动进行外部服务设置
自检（Self-Check）
核心成功标准
流程质量检查
验收测试
用户替换占位符后，除了秘密名称和环境特定值之外，工作流是否可以在目标存储库中运行而无需进一步修改？
示例（示例）
示例 1：节点 CI（测试 + PR 上的 lint）
输入：场景：CI。堆栈：节点 20、pnpm、测试 pnpm test、lint pnpm lint。触发器：“pull_request”到“main”。文件：ci.yml。
预期：带有“name”的单个“ci.yml”，例如“CI”； on: pull_request: 分支: [main];在 ubuntu-latest 上进行工作，包括结帐、设置 Node/pnpm、安装、lint、测试；使用固定的官方“actions/checkout”和“pnpm/action-setup”（或同等内容）；没有硬编码的秘密；如果设置了“权限”，则为只读。
示例 2：使用路径过滤器进行 PR 检查
输入：场景：PR 检查。堆栈：Go 1.21，测试“go test ./...”。仅当 go.mod 或 *.go 更改时触发。文件：pr-check.yml。
预期：on.pull_request 和 paths: ['**.go', 'go.mod']；固定“actions/setup-go”的工作，步骤结账，设置 Go，进行测试；如果不需要写入，则省略“权限”或“内容：读取”。
示例 3：Go 发布（Docker + GHCR + GoReleaser）
输入：场景：CD/发行版。堆栈：Go、Docker 多架构 (amd64/arm64)、GoReleaser for image 和 GitHub Release。触发器：仅“push”标签“v*”。文件：release.yml。
预期：on:push:tags:['v*']; 权限包括内容：写、包：写。步骤：签出（fetch-深度：0）→设置Go（go-version-file：go.mod，缓存）→设置QEMU（linux/amd64，linux/arm64）→设置Docker Buildx（id：buildx，相同平台）→登录GHCR（docker/login-action，ghcr.io）→GoReleaser（goreleaser/goreleaser-action pinned, pass GITHUB_TOKEN and BUILDX_BUILDER: ${{ steps.buildx.outputs.name }}).不要重新实现 .goreleaser.yaml/Dockerfile 中定义的逻辑。 参见附录 B。
示例 4（边缘）：最少信息
输入：项目：legacy-api。没有描述。语言和命令未知。用户想要“至少一个 CI 占位符工作流程”。
预期：生成一个结构完整、符合附录 A 的 YAML；对运行程序和步骤使用占位符（例如“指定运行程序和安装/测试命令”）并标记“要替换”；保持“on”范围较小（例如“pull_request:branches:[main]”）；不要发明测试或构建命令；保留“name”、“on”、“jobs”、“runs-on”、“steps”和推荐字段（例如“permissions”），以便用户稍后填写。
