| name | gh-aw |
| description | Use when creating, compiling, validating, running, or debugging GitHub Agentic Workflows with the gh-aw CLI. |
gh-aw
Use this skill whenever work touches GitHub Agentic Workflows in .github/workflows/, their generated .lock.yml files, or the gh aw command line workflow around them.
When to use this skill
- creating a new agentic workflow
- editing workflow frontmatter or prompt instructions
- compiling or validating
.md workflows into .lock.yml files
- enabling, disabling, or manually running workflows
- investigating workflow logs, health, status, or audits
- managing secrets or MCP integrations used by gh-aw workflows
- setting up local or Copilot environments so
gh aw is installed and ready
Working rules
- Treat
.github/workflows/*.md as the source of truth and .github/workflows/*.lock.yml as generated output.
- Re-run
gh aw compile --validate after any frontmatter change or when you add a new workflow.
- Keep the agent job read-only; use
safe-outputs: for issue, PR, or comment writes.
- Prefer fuzzy schedules like
daily on weekdays when the workflow is meant to run regularly.
- Ensure
.gitattributes marks .lock.yml files as generated with linguist-generated=true merge=ours.
- If
gh aw is missing, install it with an immutable script URL such as curl -fsSL https://raw.githubusercontent.com/github/gh-aw/13ac7dee59ec5127393ec22dc3f4d0f6987a3842/install-gh-aw.sh -o /tmp/install-gh-aw.sh && bash /tmp/install-gh-aw.sh v0.67.1 && rm -f /tmp/install-gh-aw.sh, then verify with gh aw version.
Recommended authoring loop
- Use
gh aw new <workflow-id> or write .github/workflows/<workflow-id>.md directly.
- Edit the workflow instructions in Markdown and keep frontmatter minimal and secure.
- Run
gh aw validate <workflow-id> while iterating.
- Run
gh aw compile <workflow-id> --validate before committing.
- Use
gh aw run <workflow-id> or gh aw trial <workflow-id> when you need an execution check.
- Use
gh aw status, gh aw logs, and gh aw audit to troubleshoot runtime behavior.
Command references
Useful setup snippets
Dev container
{
"features": {
"ghcr.io/devcontainers/features/github-cli:1": {}
},
"postCreateCommand": "curl -fsSL https://raw.githubusercontent.com/github/gh-aw/13ac7dee59ec5127393ec22dc3f4d0f6987a3842/install-gh-aw.sh -o /tmp/install-gh-aw.sh && bash /tmp/install-gh-aw.sh v0.67.1 && rm -f /tmp/install-gh-aw.sh"
}
Copilot setup workflow step
- name: Install gh-aw extension
run: curl -fsSL https://raw.githubusercontent.com/github/gh-aw/13ac7dee59ec5127393ec22dc3f4d0f6987a3842/install-gh-aw.sh -o /tmp/install-gh-aw.sh && bash /tmp/install-gh-aw.sh v0.67.1 && rm -f /tmp/install-gh-aw.sh