用途
该技能面向 GitHub Agentic Workflows（GH-AW）的仓库级工作，覆盖编写、审查、安装与调试四类任务。它适用于需要创建或维护智能体工作流的仓库，也适用于从其他仓库安装工作流、进行安全审查或排查运行失败。若任务仅涉及标准确定性 GitHub Actions YAML 而不含智能体 Markdown 工作流，则该技能不适用。
主要能力
技能按六个步骤组织工作：识别仓库状态、选择工作模式、编写或修订工作流源、配置仓库前置条件与认证、校验编译与执行、以及持续运营与改进。
在识别阶段，检查 .github/workflows/、.github/agents/、已有 .lock.yml 文件及 gh aw 使用情况，并可运行 node skills/github-agentic-workflows/scripts/find-gh-aw-targets.mjs . 定位目标；在做出对编译器敏感的决定前先运行 gh aw version。
工作模式分为：仓库设置、新工作流编写、工作流修订、从其他仓库安装工作流、安全审查、失败调试。技能提供 references/examples.md（定时报告、issue/PR 分诊、编排、智能体交接的起始模式）、references/security-and-operations.md（安全输出、网络策略、认证、锁定、威胁检测、运行可观测性）、references/troubleshooting.md（编译、安装、认证、安全输出、工具访问失败）。
编写阶段以 .github/workflows/<workflow-name>.md 为唯一来源，使用 assets/workflow.template.md 作为新工作流基础；选择最小可行的触发面与仓库角色范围；除非确实需要更广的 GitHub Actions 权限，否则保持 permissions: read-only；优先使用 safe-outputs: 处理评论、issue、标签、PR、智能体分配与编排，而非直接授予写权限；在安全输出工作流中，指示智能体在无需操作时调用 noop；保持 tools: 与 toolsets: 最小且具体；默认 engine: copilot，除非任务明确需要其他引擎且仓库已准备好相应认证模型；以最小权限配置 network:，优先使用 node、python、github 等生态标识符而非单个注册域；若严格模式与已安装 CLI 拒绝工作流仍需要的外部域，则在确定性设置步骤中预取外部来源并将本地文件传入智能体，而非放宽防火墙；不要依赖 ${{ steps.<id>.outputs.* }} 占位符到达智能体可见的 Markdown 正文，若提示依赖运行时值，应在设置阶段写入确定性本地文件并让智能体读取；仅在仓库确实受益于共享逻辑或编排时使用导入或可复用工作流；对动态输入集的重复工作，优先使用可复用 GH-AW worker 加确定性 YAML 包装器进行发现与矩阵扇出；当可复用 GH-AW worker 从矩阵调用时，不要保留默认的共享工作流级并发组，应设置以矩阵输入或提示身份为键的显式并发组，以免并行分支被 GitHub 的“一运行一等待”并发行为取消；frontmatter、导入或其他编译期配置变更后需重新编译；若仅 Markdown 正文变更且直接在 GitHub.com 上编辑，则无需仅为正文变更重新编译；除非工作流有意使用 .github/aw/ 中检入的文件，否则将其视为本地编译、校验或试运行流程中的临时 GH-AW 运行时与编译器暂存空间。
使用方式
首次仓库设置前阅读 references/authoring.md；仓库未配置 GH-AW 编写且用户需要持久设置时运行 gh aw init；使用 gh aw secrets bootstrap 或 gh aw secrets set 配置引擎密钥；Copilot 引擎认证使用 COPILOT_GITHUB_TOKEN，且应使用细粒度 PAT，通用 gho_... OAuth 令牌可能通过密钥检查但在实际 Copilot 执行时失败；使用 gh aw trial 时确认宿主仓库也具备所需引擎密钥，逻辑或源仓库的密钥不会自动复制到临时或可复用宿主仓库；扩展升级或重装后重新检查 gh aw version；若确定性包装器调用可复用 worker，调用方工作流权限至少应与嵌套 worker 请求的 actions、contents、pull-requests 范围一样宽，否则可能在智能体执行前就失败；需要跨仓库读写、Projects 访问、远程 GitHub 工具模式或高级安全输出时，使用 GitHub App 或自定义 GitHub 令牌；若仓库为公开且工作流会检查不可信外部内容，除非任务明确为低风险公开工作流，否则保留锁定与审批控制。
校验与执行：工作流使用已弃用字段或编译器指出可 codemod 的漂移时运行 gh aw fix --write；将工作流视为就绪前运行 gh aw validate --strict；CLI 版本变化或工作流依赖较新 frontmatter 行为时运行 gh aw compile --verbose；校验成功后运行 gh aw compile 并同时提交 .md 源与生成的 .lock.yml 文件；使用 gh aw run <workflow> --dry-run 验证远程分发行为；需要在推送前执行本地工作流源时使用 gh aw trial ./.github/workflows/<workflow>.md，显式 ./ 路径很重要，否则 CLI 可能将参数解析为仓库规格；仅当工作流源或锁文件确实存在于目标分支后才用 gh aw run <workflow> 直接执行；变更后使用 gh aw status、gh aw logs、gh aw audit、gh aw health 审查状态、失败、成本、工具使用与成功趋势。
运营与改进：审查工作流能否简化、拆分为更小工作流或转为共享组件；对大规模创建 issue、评论或 PR 的工作流，初始推广优先使用分阶段安全输出；对重复维护，有意固定或审查已安装 gh-aw 版本，并通过 gh aw update 或 gh aw upgrade 更新工作流而非临时复制粘贴；保持工作流提示具体、有界、可审计，多个工作流需要相同规则时将广泛策略移入可复用导入或智能体文件。
适用场景
适用于仓库中 GH-AW 的编写、修订、安装、安全审查与失败调试，包括定时报告、issue/PR 分诊、编排、智能体交接等模式，以及需要安全输出、网络策略、认证、锁定、威胁检测或运行可观测性的工作流。
限制
不适用于仅含标准确定性 GitHub Actions YAML 而无智能体 Markdown 工作流的任务。技能中未提供具体收费、价格、平台支持范围或效果保证等信息。错误处理方面：gh extension install github/gh-aw 失败时使用 references/troubleshooting.md 中的独立安装路径；编译失败时先修复 frontmatter 语法、弃用字段、导入或权限不匹配；编译器行为与所读文档不符时以已安装 gh aw 版本为准；gh aw trial 拒绝 .github/workflows/<name>.md 为无效仓库规格时改用显式本地路径 ./.github/workflows/<name>.md；可复用 worker 单独成功但包装器启动失败时先检查调用方工作流权限继承；可复用 GH-AW worker 矩阵多数分支立即取消时先检查被调用工作流的并发组；试运行在激活步骤因 Validate COPILOT_GITHUB_TOKEN secret 失败时用 gh secret list -R <host-repo> 检查宿主仓库；gh aw trial --force-delete-host-repo-before 失败时确认对宿主仓库有管理员权限且当前 GitHub 认证令牌含 delete_repo 范围；提示中仍显示未解析运行时占位符时将其移入生成的本地上下文文件并让智能体显式读取；本地 gh aw compile、validate 或 trial 生成的 .github/aw/ 文件（如 actions-lock.json 或日志）视为临时产物，除非仓库有意保留，否则提交前移除；安全输出无动作时确认分阶段模式是有意为之且提示明确指示无需写操作时调用 noop；gh aw mcp inspect 在已编译定时工作流源上因模糊调度解析错误失败时，先视为检查路径限制，重新运行 gh aw compile，优先使用已安装工作流或运行日志调试，若校验与编译已通过则不要假定工作流本身无效；编译器拒绝看似有效的引擎字段或工具条目时以已安装 schema 为准，例如 gh aw v0.58.3 中 Copilot 不支持 engine.max-turns，bash 必须为 true、false 或允许列表，裸 edit: / web-fetch: 键在布尔值不被接受处被接受；URL 被净化为 (redacted) 或工具无法访问所需服务时，有意收紧并扩展 network.allowed 而非禁用防火墙；Copilot 推理在已配置令牌下失败时确认 PAT 所有者确实拥有 Copilot 许可与推理访问；公开仓库工作流遗漏外部贡献者内容时，先确认 GitHub 锁定模式是否阻止该内容再更改工作流逻辑。