编写与维护 Agentic Workflows

组织 frontmatter 和自然语言任务，编译 lock 文件并跟踪外部来源更新。

This page has not been translated into English yet. The original Chinese version is shown below.

工作流源文件位于 .github/workflows/，由 YAML frontmatter 和 Markdown 正文组成。Frontmatter 决定可执行范围，正文解释如何完成任务；两部分需要一起评审。

主要字段

字段	用途
`on`	触发事件，支持 GitHub Actions 触发语法及相应工作流简写
`permissions`	仓库权限，创建指南列出默认 read-all
`safe-outputs`	允许的写动作，如 create-issue、add-comment、create-pull-request
`engine`	copilot 默认，也可用 claude、codex、gemini

其他字段应按官方参考配置，不通过类比普通 Actions YAML 猜测所有设置都适用。

周报示例

下面基于官方周一报告配置，使用组织 Copilot 计费权限；组织准入要求见认证与费用。

---
on: weekly on monday
permissions:
  issues: read
  copilot-requests: write
network: defaults
tools:
  github:
    toolsets: [issues]
safe-outputs:
  create-issue:
---

# Weekly issue report

Review issue activity from the last seven days in this repository.
Create an issue summarizing opened and closed items, recurring themes,
and unresolved work. Include a short list of recommended next steps.

这里允许创建 Issue，不自动允许推送代码或创建 PR。任务正文提出的写操作不能替代相应 safe-outputs 声明。

使用 coding agent 辅助编写

先在仓库初始化工作流编写资源：

gh aw init

它会添加相关 Skills、instructions 和 custom agent。然后在 coding agent 中引用 agentic-workflows Skill，说明要创建的任务；代理可生成并编译文件。无论由谁编写，都应检查 frontmatter 权限与输出范围。

编译与部署

gh aw compile
gh aw run YOUR-WORKFLOW-NAME

编译生成 .lock.yml。将 .md 与 .lock.yml 一起提交到默认分支，再由 Actions 触发器、界面或 run 命令执行。

更新时修改 Markdown，重新编译，提交两份文件并在 PR 中检查 Actions。不要只编辑生成的 lock 文件而让源配置与产物失配。

导入与更新

可用 gh aw add-wizard 导入有访问权的外部工作流；非交互流程使用 gh aw add，也可固定版本。具体 pin 参数以扩展帮助为准，不使用未经核实的参数名。

导入时会在 frontmatter 写入 source:，便于后续用 gh aw update 获取上游更新。更新会尝试保留本地修改；出现冲突时，先解决，再重新编译。

标记 private: true 的工作流不能导入其他仓库。采用外部工作流前应检查其任务、工具和输出，不能仅凭来自公开仓库就视为适合当前权限。

Issue intent

Issue 类型写动作可通过 issue-intent 要求或关闭 rationale/confidence 元数据，见Issue 建议与审批。这与 safe-outputs 的动作授权不同：前者控制解释和建议流程，后者声明可执行写操作。