gh-aw-adoption

GitHub Agentic Workflows 采用技能

目的

指导你在任何仓库中采用 GitHub Agentic Workflows（gh-aw），具体包括：

1. 调查现有工作流和自动化机会
2. 确定优先级，根据仓库需求决定要创建哪些工作流
3. 创建可用于生产环境的 Agent 工作流，并行开展
4. 解决 CI 问题、合并冲突和集成问题
5. 验证工作流能否编译并遵循最佳实践

此技能负责协调完整的 gh-aw 采用流程，帮助你从零开始构建可用于生产环境的 Agent 自动化。

何时使用此技能

在以下情况下启用此技能：

• 在尚无 Agent 工作流的仓库中采用 gh-aw
• 了解 gh-aw 仓库中可用的 gh-aw 工作流模式
• 高效创建多个 Agent 工作流
• 自动化重复的仓库任务（问题分类、PR 标记、安全扫描等）
• 调试或升级现有 Agent 工作流
• 排查工作流故障（MCP 服务错误、权限问题、CI 故障）

快速入门

基本用法：

Adopt GitHub Agentic Workflows in this repository

指定目标：

Adopt gh-aw to automate:
- Issue triage and labeling
- PR review reminders
- Security scanning
- Deployment automation

仅调查：

Investigate what agentic workflows the gh-aw team uses

故障排查：

My workflow is failing with "MCP server(s) failed to launch: docker-mcp"

Help me fix the "lockdown mode without custom token" error

工作原理

阶段 1：调查（15-20 分钟）

目标：了解现有的 Agent 工作流，以及你的仓库存在哪些不足。

步骤：

1. 查询 gh-aw 仓库：使用 gh api 列出 github/gh-aw 中的所有工作流
2. 分析工作流：阅读 5-10 个不同的工作流文件，了解其模式
3. 对工作流分类：按用途分组（安全、维护、自动化等）
4. 找出不足：与仓库当前的自动化情况进行比较
5. 制定优先级列表：按影响和可行性对工作流排序

输出：Markdown 报告，包含：

• 所有可用工作流模式的列表
• 针对你仓库的差距分析
• 按优先级排列的实施计划（建议 15-20 个工作流）

阶段 2：并行创建工作流（30-45 分钟）

目标：同时创建多个可用于生产环境的 Agent 工作流。

架构：

• 为每个工作流启动单独的 Agent 线程
• 每个 Agent 独立创建工作流
• 中央协调器跟踪进度并处理冲突
• 在功能分支中创建所有工作流

工作流创建流程（每个工作流）：

1. 从 gh-aw 仓库读取参考工作流
2. 根据你的仓库环境和需求进行调整
3. 在 .github/workflows/[name].md 中创建工作流文件
4. 添加全面的错误恢复机制（API 故障、速率限制、网络问题）
5. 适当配置 safe-outputs、权限和工具
6. 创建功能分支并提交
7. 向协调器报告完成情况

并行执行示例：

Agent 1 → issue-classifier.md
Agent 2 → pr-labeler.md
Agent 3 → security-scanner.md
Agent 4 → stale-pr-manager.md
Agent 5 → weekly-summary.md
... (up to N agents in parallel)

阶段 3：CI 诊断和集成（15-30 分钟）

目标：确保所有工作流均可编译并通过 CI 检查。

常见问题及解决方案：

问题：工作流编译失败

• 解决方案：运行 gh aw compile 并修复 YAML 语法错误
• 常见错误：缺少必填字段、工具名称无效、权限问题

问题：合并冲突

• 解决方案：将功能分支变基到最新的 main/integration
• 策略：依次将 integration 合并到各功能分支

问题：CI/CodeQL 检查失败

• 解决方案：合并前确保外部检查通过
• 使用 gh pr checks 监控状态

问题：Safe-output 验证错误

• 解决方案：为每种 safe-output 类型配置适当的限制
• 参考：查看 gh-aw 文档，了解 safe-output 语法

阶段 4：验证和部署（10-15 分钟）

目标：验证工作流已准备好用于生产环境，并合并到 main。

验证清单：

• 所有工作流都已编译为 .lock.yml 文件
• 没有 YAML 语法错误
• 权限遵循最小权限原则
• 已配置具有适当限制的 safe-outputs
• 已指定网络防火墙规则
• 已实施错误恢复模式
• 已使用 workflow_dispatch 事件测试工作流
• 文档包含用途和使用方法

部署策略：

1. 先将功能分支合并到集成分支（如有）
2. 在集成分支上运行 CI 检查
3. 所有检查通过后，将集成分支合并到 main
4. 监控首次工作流执行，检查运行时错误

导航指南

何时阅读辅助文件

reference.md — 在以下情况下阅读：

• 需要完整的 gh-aw CLI 命令参考
• 需要详细的工作流架构和配置选项
• 需要了解安全最佳实践和沙盒详情
• 需要了解 MCP 服务集成模式
• 需要了解 Repo-memory 配置和用法

examples.md — 在以下情况下阅读：

• 需要实际采用会话中的真实工作流创建示例
• 需要特定工作流类型的分步实施指南
• 需要常见错误及其解决方法
• 需要并行 Agent 编排模式
• 需要 CI/CD 集成示例

patterns.md — 在以下情况下阅读：

• 需要生产工作流架构模式
• 需要错误恢复策略（重试、回退、断路器）
• 需要 safe-output 配置最佳实践
• 需要安全加固技术
• 需要性能优化建议

关键概念

GitHub Agentic Workflows（gh-aw）

简介：GitHub 的 CLI 扩展，可通过带有 YAML frontmatter 的 Markdown 文件，以自然语言创建 AI 驱动的工作流。

主要功能：

• 使用 Markdown 编写工作流，并编译为 GitHub Actions YAML
• AI 引擎：Copilot、Claude、Codex 或自定义引擎
• 集成 MCP 服务以使用更多工具
• 使用 safe-outputs 与 GitHub API 进行结构化通信
• 默认启用 bash 和 edit 工具的沙盒执行
• 使用 Repo-memory 持久保存 Agent 状态

工作流结构

---
on: [trigger events]
permissions: [required permissions]
engine: copilot | claude-code | claude-sonnet-4-5 | codex
tools: [tool configuration]
safe-outputs: [GitHub API output limits]
network: [firewall configuration]
---

# Workflow Name

[Natural language prompt for AI agent]

关键配置项

权限：始终遵循最小权限原则

permissions:
  contents: read
  issues: write
  pull-requests: write

Safe-outputs：限制对 GitHub API 的修改操作

safe-outputs:
  add-comment:
    max: 5
    expiration: 1d
  close-issue:
    max: 3

网络：明确指定防火墙规则

network:
  firewall: true
  allowed:
    - defaults
    - github

错误恢复模式

始终实施：

• 处理 API 速率限制（指数退避）
• 网络故障重试（延迟后重试 3 次）
• 部分故障恢复（出错时继续）
• 完整的审计记录（将所有操作记录到 Repo-memory）
• 留意 safe-output 限制（优先处理关键操作）

前置条件

使用此技能前，请确保：

1. 已安装 gh CLI：gh --version
2. 已安装 gh-aw 扩展：gh extension install github/gh-aw
3. 拥有仓库访问权限：具有创建分支和 PR 的写入权限
4. 已完成身份验证：GitHub 令牌具有适当的作用域
5. 可选：集成分支：用于在合并到 main 前暂存工作流变更

Repo Guardian：推荐的首个工作流

Repo Guardian 是建议在任何仓库中优先采用的首个工作流。此技能目录中提供了可直接复制的模板：

• repo-guardian.md — gh-aw Agentic 工作流（面向 AI Agent 的自然语言提示词）
• repo-guardian-gate.yml — 标准 GitHub Actions 工作流，用于将 Agent 检查结果设为阻塞式 CI 检查

功能

检查每个 PR，查找不应存在于仓库中的临时内容：

• 会议记录、冲刺回顾、状态更新
• 临时脚本（fix-thing.sh、one-off-migration.py）
• 会随时间过时的特定时间点文档
• 文件名前缀带日期、表明其为快照的文件

发现问题后会发布 PR 评论。协作者可以使用 repo-guardian:override <reason> 覆盖检查结果。

快速设置

# 1. Copy templates
mkdir -p .github/workflows
cp .claude/skills/gh-aw-adoption/repo-guardian.md .github/workflows/repo-guardian.md
cp .claude/skills/gh-aw-adoption/repo-guardian-gate.yml .github/workflows/repo-guardian-gate.yml

# 2. Compile the agentic workflow (pins the gh-aw version)
cd .github/workflows
gh aw compile repo-guardian

# 3. Add COPILOT_GITHUB_TOKEN secret (PAT with read:org + repo scopes)
# Repository Settings → Secrets and variables → Actions → New repository secret

# 4. Commit and push all three files
git add .github/workflows/repo-guardian.md \
        .github/workflows/repo-guardian.lock.yml \
        .github/workflows/repo-guardian-gate.yml
git commit -m "feat: Add Repo Guardian agentic workflow"
git push

---

建议采用的常见工作流

根据对 gh-aw 仓库中 100 多个工作流的分析，以下是值得考虑的高影响力工作流：

安全与合规（高优先级）：

• repo-guardian.md - 阻止包含临时内容的 PR（已作为模板提供，见上文）
• secret-validation.md - 监控密钥是否即将过期或泄露
• container-security-scanning.md - 扫描容器映像中的漏洞
• license-compliance.md - 验证依赖项许可证
• sbom-generation.md - 生成软件物料清单

开发自动化（高优先级）：

• pr-labeler.md - 根据内容自动为 PR 添加标签
• issue-classifier.md - 对问题进行分类并添加标签
• stale-pr-manager.md - 在宽限期后关闭长期未处理的 PR
• changelog-generator.md - 根据提交自动生成变更日志

质量保证（中优先级）：

• test-coverage-enforcer.md - 阻止覆盖率低于阈值的 PR
• mutation-testing.md - 运行变异测试并报告存活的变异
• performance-testing.md - 自动执行性能回归测试

维护与运营（中优先级）：

• agentics-maintenance.md - 工作流健康状况监控中心
• workflow-health-dashboard.md - 每周指标和状态报告
• dependency-updates.md - 自动创建依赖项更新 PR

团队沟通（较低优先级）：

• weekly-issue-summary.md - 附带可视化内容的每周问题摘要
• team-status-reports.md - 每日团队状态更新
• pr-review-reminders.md - 提醒审阅者处理长期未完成的审阅

故障排除

问题：找不到 gh-aw 扩展

gh extension install github/gh-aw
gh aw --help

问题：编译错误

gh aw compile --validate
gh aw fix --write  # Auto-fix some issues

问题：工作流未执行

• 检查工作流文件是否位于 .github/workflows/
• 确认工作流具有有效的触发器（on: 字段）
• 检查 GitHub Actions 日志中的执行错误
• 确保已配置所需的密钥

问题：超出安全输出限制

• 检查工作流 frontmatter 中的安全输出配置
• 如有需要，调高限制
• 添加优先级逻辑，确保不超出限制

问题：权限被拒绝错误

• 检查工作流 frontmatter 中的 permissions: 块
• 检查 GitHub 令牌是否具有所需的权限范围
• 确保工作流具有必要的仓库权限

应避免的反模式

❌ 不要：创建包揽所有任务的单体工作流
✅ 应当：创建职责单一、重点明确的工作流

❌ 不要：跳过错误处理，假设 API 总能成功
✅ 应当：实现重试和回退机制，并进行全面的错误日志记录

❌ 不要：使用过于宽泛的权限（到处都设置 contents: write）
✅ 应当：对每个工作流应用最小权限原则

❌ 不要：在工作流中硬编码特定仓库的值
✅ 应当：使用 GitHub 上下文变量（${{ github.repository }}）

❌ 不要：未经测试就创建工作流
✅ 应当：先使用 workflow_dispatch 进行测试，再启用自动触发器

成功标准

符合以下条件时，表示 gh-aw 已成功落地：

1. ✅ 仓库中有 10-20 个生产级 Agentic 工作流
2. ✅ 所有工作流均可成功编译
3. ✅ CI/CD 流水线包含工作流验证
4. ✅ 工作流遵循安全最佳实践
5. ✅ 团队了解如何创建和修改工作流
6. ✅ 工作流能够妥善处理错误并提供审计跟踪
7. ✅ 维护中心会监控工作流的健康状况
8. ✅ 文档说明了每个工作流的用途和用法

落地后的后续步骤

1. 监控工作流健康状况：使用 workflow-health-dashboard.md
2. 根据反馈迭代：随着团队需求变化调整工作流
3. 创建自定义工作流：运用已学到的模式构建新的自动化流程
4. 分享经验：记录成功的模式，供其他仓库参考
5. 升级工作流：保持 gh-aw 扩展更新并应用迁移

---

文档结构（Diátaxis 框架）

此技能遵循 Diátaxis 文档框架，包含四种互补的资源：

1. SKILL.md（教程／概述）：入门指南、快速参考和高层概念
2. examples.md（操作指南）：分步实践示例和故障排除方案
3. patterns.md（说明）：了解模式、反模式和最佳实践
4. reference.md（参考）：技术规范、详细配置和故障排除参考

故障排除：

• 首先查阅 reference.md，了解错误及其根本原因
• 查看 examples.md，获取分步修复说明
• 阅读 patterns.md，避免在今后的工作流中使用反模式

---

注意：此技能可自动完成 gh-aw 的采用流程。若要手动控制或执行特定阶段，请在调用技能时明确说明（例如：“gh-aw-adoption: investigation only”）。