thomast1906/gh-aw-operations
Comprehensive skills for creating, compiling, debugging, and managing GitHub Agentic Workflows (gh-aw) with best practices and common patterns
npx skills add https://github.com/thomast1906/github-copilot-agent-skills --skill gh-aw-operationsThis skill provides expertise in creating, managing, and troubleshooting GitHub Agentic Workflows (gh-aw framework).
Configure workflow frontmatter with all required and optional fields following gh-aw specifications.
---
# ===== REQUIRED FIELDS =====
on:
workflow_dispatch:
inputs:
parameter_name:
description: 'Clear description of parameter'
required: false
type: string|boolean|choice|number
default: "default_value" # Boolean: "true"/"false" as strings
schedule:
- cron: '0 9 * * 1' # Monday 9 AM UTC
issues:
types: [opened, labeled]
pull_request:
types: [opened, synchronize]
engine: copilot # GitHub Copilot as AI engine
permissions:
contents: read # NEVER use write — strict mode blocks it
pull-requests: read # All writes go through safe-outputs
issues: read
# ===== TOOLS CONFIGURATION =====
tools:
edit: # bare key — enables file read AND edit
bash: # bare key — default safe commands
github:
toolsets: [pull_requests] # Only include toolsets your workflow needs
# ===== MCP SERVERS (if needed) =====
mcp-servers:
terraform:
container: "hashicorp/terraform-mcp-server:0.5.1"
env:
TF_LOG: "INFO"
allowed: ["*"]
# ===== SAFE OUTPUTS =====
safe-outputs:
create-pull-request:
title-prefix: "[automated] "
labels: [automation]
draft: true
reviewers: [copilot]
expires: 14
fallback-as-issue: true
create-issue:
title-prefix: "[bot] "
labels: [automation]
expires: 7
update-issue: null
add-comment: null
# ===== NETWORK ACCESS =====
network:
allowed:
- defaults
- registry.terraform.io
- releases.hashicorp.com
- api.github.com
# ===== IMPORTS (if using reusable agents/skills) =====
imports:
- owner/repo/.github/agents/agent-name.agent.md@main
- owner/repo/.github/skills/skill-name/SKILL.md@main
---
edit: is a bare key (no value) — enables both reading and writing files. edit: null and edit: true both fail compilation.read: is not a valid tool — file reading is provided by edit:.bash: is a bare key (no value) for default safe commands, or bash: ["cmd"] for specific commands.contents: write / pull-requests: write / issues: write are blocked by strict mode — use safe-outputs: for all write operations instead.pull_request: trigger requires types: — bare pull_request: fails compilation.workflow_dispatch: is a bare key — workflow_dispatch: null fails compilation.toolsets: [default] includes the issues toolset which requires issues: read; only declare the toolsets you actually need.default: "true" not default: truecreate-pull-request not create_pull_requestowner/repo/path@ref format, not raw GitHub URLsConfigure safe-outputs for GitHub operations (PRs, issues, comments) with proper validation and best practices.
safe-outputs:
create-pull-request:
title-prefix: "[type] "
labels: [automation, bot-generated]
draft: true
reviewers: [copilot]
expires: 14 # Auto-close after 14 days
fallback-as-issue: true # Create issue if PR fails
base-branch: main # Target branch
When to use:
safe-outputs:
create-issue:
title-prefix: "[report] "
labels: [automation, needs-review]
assignees: [copilot]
expires: 7
group: true # Group multiple issues as sub-issues
close-older-issues: true # Close previous issues from same workflow
When to use:
safe-outputs:
add-comment:
target: "triggering" # Comment on triggering issue/PR
max: 3
hide-older-comments: true # Hide previous comments from same workflow
When to use:
safe-outputs:
create-pull-request-review-comment:
max: 10
side: "RIGHT"
footer: "if-body" # Only show footer when review has body
submit-pull-request-review:
max: 1
footer: false
When to use:
safe-outputs:
add-labels:
allowed: [bug, enhancement, documentation]
max: 3
remove-labels:
allowed: [needs-triage, stale]
max: 3
When to use:
create-pull-request - Create PRs with code changescreate-issue - Create issuesupdate-issue - Update issue title/body/statusclose-issue - Close issuescreate-discussion - Create discussionsupdate-discussion - Update discussionsclose-discussion - Close discussionsadd-comment - Add comments to issues/PRs/discussionshide-comment - Hide commentsadd-labels - Add labelsremove-labels - Remove labelsadd-reviewer - Add PR reviewerscreate-pull-request-review-comment - Add PR review commentssubmit-pull-request-review - Submit PR reviewupdate-pull-request - Update PR title/bodydispatch-workflow - Trigger other workflowscreate-project, update-project - Manage GitHub Projectsupload-asset - Upload files to orphaned branchConfigure and use Model Context Protocol (MCP) servers for specialized tool access.
mcp-servers:
terraform:
container: "hashicorp/terraform-mcp-server:0.5.1"
env:
TF_LOG: "INFO"
allowed: ["*"] # or specific tools
Available operations:
mcp-servers:
azure:
container: "mcr.microsoft.com/azure-sdk/azure-mcp:latest"
env:
AZURE_SUBSCRIPTION_ID: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
Available operations:
mcp-servers:
custom:
container: "your-org/your-mcp-server:v1.0.0"
env:
API_KEY: ${{ secrets.API_KEY }}
allowed: ["specific_tool1", "specific_tool2"]
network:
allowed:
- defaults # GitHub APIs
- registry.terraform.io
- releases.hashicorp.com
- management.azure.com
- custom-api.example.com
Compile workflows and resolve common compilation errors.
# Compile single workflow
gh aw compile workflow-name
# Compile all workflows
gh aw compile
# Force recompile
gh aw compile --force workflow-name
# Validate without compiling
gh aw validate workflow-name
editProblem:
tools:
read: null # ❌ 'read' is not a valid tool
edit: null # ❌ null not valid for edit
edit: true # ❌ true not valid for edit
Solution:
tools: # ✅ bare keys
edit:
bash:
Problem:
permissions:
contents: write # ❌ blocked by strict mode
pull-requests: write # ❌ blocked by strict mode
Solution:
permissions: # ✅ read-only
contents: read
pull-requests: read
safe-outputs: # ✅ write operations go here
create-pull-request: null
pull_request trigger requires typesProblem:
on:
pull_request: # ❌ bare null not valid
workflow_dispatch: null # ❌ null not valid
Solution:
on:
workflow_dispatch: # ✅ bare key
pull_request: # ✅ explicit types
types: [opened, synchronize, reopened]
Problem:
tools:
github:
toolsets: [default] # includes 'issues' toolset
permissions:
contents: read # ❌ missing 'issues: read', compiler warns
Solution:
tools:
github:
toolsets: [pull_requests] # ✅ only what you need
permissions:
contents: read
pull-requests: read
Problem:
tools: ['bash', 'read', 'edit'] # ❌ Wrong
Solution:
tools: # ✅ Correct
bash:
edit:
Problem:
workflow_dispatch:
inputs:
enabled:
type: boolean
default: true # ❌ Wrong
Solution:
workflow_dispatch:
inputs:
enabled:
type: boolean
default: "true" # ✅ Correct (quoted)
Problem:
safe-outputs:
create_pull_request: null # ❌ Wrong (underscore)
Solution:
safe-outputs:
create-pull-request: null # ✅ Correct (hyphen)
Problem:
imports:
- https://raw.githubusercontent.com/owner/repo/main/agent.md # ❌ Wrong
Solution:
imports:
- owner/repo/.github/agents/agent.md@main # ✅ Correct
Problem:
safe-outputs: [create-issue, create-pull-request] # ❌ Wrong (array)
Solution:
safe-outputs: # ✅ Correct (object)
create-issue: null
create-pull-request: null
For deployment, testing, troubleshooting, performance optimization, security best practices, and quick reference, see references/GH-AW-PATTERNS.md.
Take thomast1906/gh-aw-operations from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.