github-agentic-workflows

GitHub Agentic Workflows

Procedures

Step 1: Identify the repository state

1. Inspect the workspace for .github/workflows/, .github/agents/, existing .lock.yml files, and any gh aw usage.
2. Execute node skills/github-agentic-workflows/scripts/find-gh-aw-targets.mjs . when a Node runtime is available.
3. Run gh aw version before making compiler-sensitive decisions so the workflow authoring path matches the installed CLI behavior.
4. If the repository contains multiple candidate workflows, prefer the workflow the user named or the one closest to the active issue, pull request, or automation surface.
5. If the repository has no GH-AW setup and the task is to create or maintain agentic workflows, read references/authoring.md before editing.
6. If the task is limited to standard deterministic GitHub Actions YAML without agentic markdown workflows, stop and explain that this skill does not apply.

Step 2: Choose the working mode

1. Classify the task as one of: repository setup, new workflow authoring, workflow revision, workflow installation from another repository, security review, or failure debugging.
2. Read references/examples.md when the task needs a starting pattern for scheduled reports, issue or PR triage, orchestration, or agent handoff.
3. Read references/security-and-operations.md when the workflow needs safe outputs, network policy, authentication, lockdown, threat detection, or run observability.
4. Read references/troubleshooting.md when the workflow fails to compile, install, authenticate, execute safe outputs, or access tools.

Step 3: Author or revise the workflow source

1. Keep the workflow source of truth in .github/workflows/<workflow-name>.md.
2. Use assets/workflow.template.md as the base shape when creating a new workflow.
3. Choose the smallest viable trigger surface and repository role scope that satisfies the task.
4. Keep permissions: read-only unless the workflow truly needs broader GitHub Actions permissions outside the agentic section.
5. Prefer safe-outputs: for comments, issues, labels, PRs, agent assignment, and orchestration instead of granting direct write access to the agent.
6. In safe-output workflows, instruct the agent to call noop when no action is required.
7. Keep tools: and toolsets: minimal and specific to the task.
8. Default to engine: copilot unless the task explicitly requires another engine and the repository is already prepared for that engine's authentication model.
9. Configure network: with least privilege. Prefer ecosystem identifiers such as node, python, or github over individual registry domains when the compiler supports them.
10. If strict mode and the installed CLI reject custom domains that the workflow still needs, prefetch external sources in deterministic setup steps and pass local files into the agent instead of broadly relaxing the firewall.
11. Do not rely on ${{ steps.<id>.outputs.* }} placeholders reaching the agent-visible markdown body in real runs. If prompt instructions depend on runtime values, write them into a deterministic local file during setup and tell the agent to read that file.
12. Use imported or reusable workflows only when the repository genuinely benefits from shared logic or orchestration.
13. For recurring work across a dynamic set of inputs, prefer a reusable GH-AW worker plus a deterministic YAML wrapper for discovery and matrix fan-out.
14. When a reusable GH-AW worker is called from a matrix, do not leave it on the default shared workflow-level concurrency group. Set an explicit concurrency group keyed by the matrix input or prompt identity so parallel legs are not cancelled by GitHub's one-running-one-pending concurrency behavior.
15. Recompile the workflow after frontmatter, imports, or other compile-time configuration changes.
16. If only the markdown body changed and the workflow is edited directly on GitHub.com, do not recompile solely for body text changes.
17. Treat .github/aw/ as transient GH-AW runtime and compiler scratch space during local compile, validate, or trial flows unless the workflow intentionally uses checked-in files from that path.