| name | gh-aw |
| description | GitHub Agentic Workflows (`gh aw`) operations for repository automation, creating workflows, running coding agents, and auditing workflow runs. You MUST load this skill when working with the `gh aw` command. |
| license | MIT |
gh-aw Skill
Use gh aw to orchestrate GitHub Agentic Workflows for repository automation.
WHEN TO USE
- To initialize, create, update, or run GitHub Agentic Workflows.
- When compiling
.md agent definitions into executable .lock.yml GitHub Actions.
- To manage MCP (Model Context Protocol) servers and toolsets within a repository's agent configuration.
WHEN NOT TO USE
- For standard GitHub CLI operations that don't involve the Agentic Workflows extension (e.g., just listing issues or PRs).
- When writing application code that simply uses the OpenAI or Anthropic API directly.
- For troubleshooting a failed workflow run (use
gh-aw-troubleshooting instead).
Common Pitfalls
- Manual Lockfile Edits: Directly editing the
.lock.yml file, which will be silently overwritten the next time gh aw compile is run.
- Skipping Compilation: Changing an agent's
.md definition but forgetting to run gh aw compile, causing the CI pipeline to run the outdated version.
- Missing Extension: Attempting to run
gh aw commands on a fresh runner without first executing gh extension install github/gh-aw.
How to Install the Extension
To install the GitHub Agentic Workflows extension for the GitHub CLI, run:
gh extension install github/gh-aw
If gh extension install is unavailable or fails (e.g., in environments
without GitHub CLI extension support), you can download and run the
installation script:
curl -sL https://raw.githubusercontent.com/github/gh-aw/v0.74.3/install-gh-aw.sh -o install-gh-aw.sh
head -n 50 install-gh-aw.sh
bash install-gh-aw.sh
Mindmap of Commands
mindmap
root((gh aw))
Setup Commands
add
Add workflows
add-wizard
Interactively add workflows
init
Initialize repository
new
Create new workflow
remove
Remove workflow files
secrets
Manage secrets
update
Update workflows
upgrade
Upgrade repository
Development Commands
compile
Compile workflows into YAML
domains
List network domains
fix
Apply automatic fixes
lint
Lint workflows
mcp
Manage MCP servers
validate
Validate workflows
Execution Commands
disable
Disable workflows
enable
Enable workflows
run
Run workflows on GitHub Actions
trial
Run in trial mode
Analysis Commands
list
List workflows
audit
Audit workflow runs
checks
Classify CI check state
health
Show health overview
logs
Analyze workflow logs
status
Show workflow status
Utilities
completion
Generate shell completion
hash-frontmatter
Compute frontmatter hash
mcp-server
Run MCP server
pr
Pull request utilities
project
Create Projects V2 boards
Core Process
- Setup: Use
gh aw init to initialize a repository, followed by gh aw new <workflow-name> or gh aw add-wizard.
- Development: Workflows are markdown files compiled via
gh aw compile into GitHub Actions YAML (.lock.yml).
- Execution: Use
gh aw run <workflow-name> to execute a workflow or gh aw trial for simulated runs.
- Analysis: If a run fails, load the
gh-aw-troubleshooting skill to diagnose the root cause using gh aw audit and gh aw logs.
- Updating: Run
gh aw upgrade to get the latest agent files and apply codemods.
What to Avoid
- Always review the changes made by the AI agent, especially considering security and context.
- Do not manually edit the generated
.lock.yml files; they are intended to be compiled from the markdown workflows.
References
Agentic Workflow Prompts
When asked to create, update, debug, or upgrade GitHub Agentic Workflows,
use webfetch to retrieve and read the appropriate instruction prompt from the official repository before proceeding:
Setup docs
Related Skills
- gh-aw-compile:
You MUST load this skill when recompiling Agentic Workflows.
- gh-aw-troubleshooting:
You MUST load this skill to diagnose and fix failing Agentic Workflows.
- gh-run:
You MUST load this skill when working with GitHub Actions workflow runs.
