gh-aw

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

1. Treat .github/workflows/*.md as the source of truth and .github/workflows/*.lock.yml as generated output.
2. Re-run gh aw compile --validate after any frontmatter change or when you add a new workflow.
3. Keep the agent job read-only; use safe-outputs: for issue, PR, or comment writes.
4. Prefer fuzzy schedules like daily on weekdays when the workflow is meant to run regularly.
5. Ensure .gitattributes marks .lock.yml files as generated with linguist-generated=true merge=ours.
6. 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

1. Use gh aw new <workflow-id> or write .github/workflows/<workflow-id>.md directly.
2. Edit the workflow instructions in Markdown and keep frontmatter minimal and secure.
3. Run gh aw validate <workflow-id> while iterating.
4. Run gh aw compile <workflow-id> --validate before committing.
5. Use gh aw run <workflow-id> or gh aw trial <workflow-id> when you need an execution check.
6. Use gh aw status, gh aw logs, and gh aw audit to troubleshoot runtime behavior.

Command references

• gh aw add
• gh aw add-wizard
• gh aw audit
• gh aw checks
• gh aw compile
• gh aw completion
• gh aw disable
• gh aw domains
• gh aw enable
• gh aw fix
• gh aw hash-frontmatter
• gh aw health
• gh aw init
• gh aw list
• gh aw logs
• gh aw mcp
• gh aw mcp-server
• gh aw new
• gh aw pr
• gh aw project
• gh aw remove
• gh aw run
• gh aw secrets
• gh aw status
• gh aw trial
• gh aw update
• gh aw upgrade
• gh aw validate
• gh aw version

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