GitHub Agentic Workflows Operations Skill

This skill provides expertise in creating, managing, and troubleshooting GitHub Agentic Workflows (gh-aw framework).

Skill 1: Frontmatter Configuration

Description

Configure workflow frontmatter with all required and optional fields following gh-aw specifications.

Implementation Pattern

===== 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.3.3" 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

Key Rules

• 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 and permissions must align — toolsets: [default] includes the issues toolset which requires issues: read ; only declare the toolsets you actually need.

• Boolean defaults must be strings: default: "true" not default: true

• Safe-output fields use hyphens: create-pull-request not create_pull_request

• Imports use owner/repo/path@ref format, not raw GitHub URLs

• Safe-outputs can be bare key (default config) or object (custom config)

Skill 2: Safe-Outputs Configuration

Description

Configure safe-outputs for GitHub operations (PRs, issues, comments) with proper validation and best practices.

Common Safe-Output Patterns

Pattern: Pull Request Creation

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:

• Automated code changes

• Dependency upgrades

• Code generation

• Refactoring

Pattern: Issue Creation

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:

• Reporting findings

• Tracking tasks

• Alerting on issues

• Documentation requests

Pattern: Issue/PR Comments

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:

• Status updates

• Analysis results

• Bot responses

• Progress reporting

Pattern: PR Reviews

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:

• Code review automation

• Inline suggestions

• Security analysis

• Style checking

Pattern: Label Management

safe-outputs: add-labels: allowed: [bug, enhancement, documentation] max: 3 remove-labels: allowed: [needs-triage, stale] max: 3

When to use:

• Workflow status tracking

• Issue classification

• Automation state management

Available Safe-Output Types

• create-pull-request

• Create PRs with code changes

• create-issue

• Create issues

• update-issue

• Update issue title/body/status

• close-issue

• Close issues

• create-discussion

• Create discussions

• update-discussion

• Update discussions

• close-discussion

• Close discussions

• add-comment

• Add comments to issues/PRs/discussions

• hide-comment

• Hide comments

• add-labels

• Add labels

• remove-labels

• Remove labels

• add-reviewer

• Add PR reviewers

• create-pull-request-review-comment

• Add PR review comments

• submit-pull-request-review

• Submit PR review

• update-pull-request

• Update PR title/body

• dispatch-workflow

• Trigger other workflows

• create-project , update-project

• Manage GitHub Projects

• upload-asset

• Upload files to orphaned branch

Skill 3: MCP Server Integration

Description

Configure and use Model Context Protocol (MCP) servers for specialized tool access.

Common MCP Server Configurations

Terraform MCP Server

mcp-servers: terraform: container: "hashicorp/terraform-mcp-server:0.3.3" env: TF_LOG: "INFO" allowed: ["*"] # or specific tools

Available operations:

• Read Terraform configurations

• Analyze provider versions

• Detect breaking changes

• Generate upgrade recommendations

Azure MCP Server

mcp-servers: azure: container: "mcr.microsoft.com/azure-sdk/azure-mcp:latest" env: AZURE_SUBSCRIPTION_ID: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

Available operations:

• Azure resource queries

• Best practices validation

• Documentation lookup

• Terraform Azure integration

Custom MCP Server

mcp-servers: custom: container: "your-org/your-mcp-server:v1.0.0" env: API_KEY: ${{ secrets.API_KEY }} allowed: ["specific_tool1", "specific_tool2"]

Network Configuration for MCP Servers

network: allowed: - defaults # GitHub APIs - registry.terraform.io - releases.hashicorp.com - management.azure.com - custom-api.example.com

Skill 4: Workflow Compilation & Debugging

Description

Compile workflows and resolve common compilation errors.

Compilation Commands

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

Common Compilation Errors & Fixes

Error: Invalid tool value for edit

Problem:

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:

Error: Write permissions blocked by strict mode

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

Error: pull_request trigger requires types

Problem:

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]

Error: Missing permission for toolset

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

Error: "got array, want object" for tools

Problem:

tools: ['bash', 'read', 'edit'] # ❌ Wrong

Solution:

tools: # ✅ Correct bash: edit:

Error: Boolean default must be string

Problem:

workflow_dispatch: inputs: enabled: type: boolean default: true # ❌ Wrong

Solution:

workflow_dispatch: inputs: enabled: type: boolean default: "true" # ✅ Correct (quoted)

Error: Invalid safe-output field name

Problem:

safe-outputs: create_pull_request: null # ❌ Wrong (underscore)

Solution:

safe-outputs: create-pull-request: null # ✅ Correct (hyphen)

Error: Import download failed

Problem:

imports:

• https://raw.githubusercontent.com/owner/repo/main/agent.md # ❌ Wrong

Solution:

imports:

• owner/repo/.github/agents/agent.md@main # ✅ Correct

Error: Safe-outputs format

Problem:

safe-outputs: [create-issue, create-pull-request] # ❌ Wrong (array)

Solution:

safe-outputs: # ✅ Correct (object) create-issue: null create-pull-request: null

Skill 5: Workflow Testing & Deployment

Description

Deploy and test agentic workflows in GitHub Actions.

Deployment Checklist

Compile Workflow

gh aw compile workflow-name

• Verify 0 errors

• Check warnings (informational only)

Commit Files

git add .github/workflows/workflow-name.md git add .github/workflows/workflow-name.lock.yml git commit -m "feat: Add workflow-name agentic workflow" git push

Enable PR Creation (if using create-pull-request )

• Go to: Settings → Actions → General

• Check: ✓ Allow GitHub Actions to create and approve pull requests

• Save

Configure Secrets (if needed)

• Go to: Settings → Secrets and variables → Actions

• Add required secrets (API keys, tokens, etc.)

Test Workflow

• Navigate to: Actions tab

• Select workflow

• Click "Run workflow"

• Provide inputs

• Monitor execution

Testing Strategies

Strategy 1: Manual Trigger Testing

on: workflow_dispatch: inputs: dry_run: description: 'Dry run mode (no actual changes)' type: boolean default: "true"

Test without making real changes first.

Strategy 2: Branch Testing

on: push: branches: - test/**

Test on dedicated test branches before enabling on main.

Strategy 3: Label-Based Testing

on: issues: types: [labeled]

Only run when "test-workflow" label is added

Control execution via labels during testing.

Skill 6: Import Reusable Agents & Skills

Description

Use imports to leverage reusable agents and skills from other repositories.

Import Patterns

Import External Agent

imports:

• thomast1906/github-copilot-skills-terraform/.github/agents/terraform-provider-upgrade.agent.md@main

In markdown instructions:

Use your imported Terraform provider upgrade expertise to analyze the current provider versions and recommend upgrades.

Import External Skill

imports:

• owner/repo/.github/skills/code-review/SKILL.md@main
• owner/repo/.github/skills/security-scan/SKILL.md@main

In markdown instructions:

Apply your code review and security scanning skills to analyze the changes in this pull request.

Import Multiple Resources

imports:

• owner/repo/.github/agents/analyzer.agent.md@main
• owner/repo/.github/skills/reporting/SKILL.md@main
• owner/repo/.github/skills/validation/SKILL.md@main

Import Best Practices

Pin to specific refs when stable:

imports:

• owner/repo/.github/agents/agent.md@v1.2.0 # Tag

• owner/repo/.github/agents/agent.md@abc1234 # Commit SHA

Use main/master for latest:

imports:

• owner/repo/.github/agents/agent.md@main

Imports are cached in .github/aw/imports/

• Committed to repository

• Updated on recompilation

• Version-locked for consistency

Skill 7: Common Workflow Patterns

Description

Pre-built patterns for common automation scenarios.

Pattern: Dependency Upgrade Workflow

on: workflow_dispatch: inputs: target_version: description: 'Target version (leave empty for latest)' required: false type: string schedule: - cron: '0 9 * * 1' # Weekly Monday 9 AM

engine: copilot

permissions: contents: read pull-requests: read

tools: edit: github: toolsets: [pull_requests]

safe-outputs: create-pull-request: title-prefix: "[dependency] " labels: [dependencies, automation] draft: true reviewers: [copilot] expires: 14 create-issue: title-prefix: "[dependency] " labels: [dependencies, blocked]

network: allowed: - defaults - registry.npmjs.org - registry.terraform.io

Dependency Upgrade Workflow

Automatically upgrade project dependencies to latest compatible versions.

Your Task

1. Scan current dependencies
2. Check for available upgrades
3. Analyze breaking changes
4. Create PR with upgrades or issue if blocked

Pattern: Code Analysis & Reporting

on: workflow_dispatch: pull_request: types: [opened, synchronize]

engine: copilot

permissions: contents: read pull-requests: read

tools: edit: github: toolsets: [pull_requests]

safe-outputs: add-comment: target: "triggering" create-pull-request-review-comment: max: 10 add-labels: allowed: [needs-review, lgtm, requires-changes]

Code Analysis Workflow

Analyze code quality and provide feedback on pull requests.

Your Task

Review the PR changes and provide:

1. Code quality feedback
2. Security concerns
3. Best practice suggestions
4. Inline comments on specific issues

Pattern: IssueOps/ChatOps

on: issues: types: [opened, labeled] issue_comment: types: [created]

engine: copilot

permissions: contents: read issues: read

tools: github: toolsets: [issues]

safe-outputs: add-comment: null update-issue: null add-labels: allowed: [in-progress, completed, needs-info] close-issue: null

IssueOps Workflow

Respond to issue commands and manage issue lifecycle.

Your Task

When an issue is created or commented on:

1. Parse commands (e.g., /analyze, /report, /close)
2. Execute the requested operation
3. Report results as comment
4. Update issue labels/status

Skill 8: Troubleshooting Guide

Description

Diagnose and fix common issues with agentic workflows.

Issue: Workflow Not Appearing in Actions UI

Symptoms:

• Workflow file exists but doesn't show in Actions tab

• Can't manually trigger workflow

Diagnosis:

Check if lock file was generated

ls -la .github/workflows/*.lock.yml

Check if files are committed

git status

Verify compilation succeeded

gh aw compile workflow-name

Solutions:

• Ensure both .md and .lock.yml are committed and pushed

• Verify workflow_dispatch trigger is configured

• Check repository Settings → Actions to ensure workflows are enabled

Issue: PR Creation Fails

Symptoms:

Warning: Failed to create pull request: GitHub Actions is not permitted to create or approve pull requests.

Solution:

• Go to: Settings → Actions → General

• Scroll to: "Workflow permissions"

• Check: ✓ Allow GitHub Actions to create and approve pull requests

• Click Save

Issue: MCP Server Not Working

Symptoms:

• Tools from MCP server not available

• Connection timeouts

Diagnosis:

Check container image is correct

mcp-servers: terraform: container: "hashicorp/terraform-mcp-server:0.3.3" # Verify version

Solutions:

• Verify container image exists and is accessible

• Check network allowlist includes required domains

• Verify environment variables are set correctly

• Check container logs in workflow run

Issue: Import Not Resolving

Symptoms:

Error: Failed to download import: owner/repo/path@ref

Solutions:

• Verify repository is public or accessible with token

• Check path is correct: .github/agents/name.agent.md

• Verify branch/tag/SHA exists

• Use correct format: owner/repo/path@ref (not raw URL)

Skill 9: Performance Optimization

Description

Optimize workflow execution time and resource usage.

Optimization Techniques

1. Minimize MCP Server Usage

Only allow specific tools needed

mcp-servers: terraform: allowed: ["analyze_version", "detect_breaking_changes"] # Not "*"

2. Set Appropriate Timeouts

Don't run indefinitely

on: workflow_dispatch: inputs: timeout_minutes: description: 'Maximum execution time' default: "30"

3. Cache Results

tools: cache-memory: null # Enable caching

Use caching in instructions:

Cache analysis results to avoid re-analyzing unchanged files.

4. Limit Safe-Output Operations

safe-outputs: create-pull-request-review-comment: max: 10 # Limit number of comments

5. Use Concise Instructions

❌ Avoid overly verbose instructions

Please very carefully analyze every single line...

✅ Be concise and clear

Analyze changes and report findings.

Skill 10: Security Best Practices

Description

Implement secure configurations for agentic workflows.

Security Checklist

Minimal Permissions

permissions: contents: read # Only write if absolutely necessary pull-requests: write # Only if creating PRs issues: write # Only if creating issues

Secret Management

mcp-servers: custom: env: API_KEY: ${{ secrets.API_KEY }} # Use secrets, not hardcoded values

Network Restrictions

network: allowed: - defaults - specific-domain.com # Only allow required domains # Don't use wildcards or overly broad allowlists

Input Validation

on: workflow_dispatch: inputs: target: type: choice # Use choice instead of string when possible options: [dev, staging, prod]

Safe-Output Restrictions

safe-outputs: add-labels: allowed: [bug, enhancement] # Restrict which labels can be added add-reviewer: reviewers: [team-lead, copilot] # Restrict who can be assigned

Quick Reference Card

File Structure

.github/ ├── workflows/ │ ├── workflow-name.md # Your workflow definition │ └── workflow-name.lock.yml # Generated (committed) ├── agents/ │ └── agent-name.agent.md # Reusable agents └── skills/ └── skill-name/ └── SKILL.md # Reusable skills

Essential Commands

Compile workflow

gh aw compile workflow-name

Compile all workflows

gh aw compile

Validate workflow

gh aw validate workflow-name

List workflows

gh aw list

Frontmatter Quick Template

on: workflow_dispatch: # bare key — no null pull_request: types: [opened, synchronize, reopened] # always specify types engine: copilot permissions: contents: read # never write — strict mode blocks it pull-requests: read # match only what your toolsets need tools: edit: # bare key — enables file read/edit github: toolsets: [pull_requests] # only what you need safe-outputs: create-pull-request: null # all write ops go here network: allowed: [defaults]

Common Safe-Outputs

• create-pull-request

• Code changes

• create-issue

• Reports/alerts

• add-comment

• Status updates

• update-issue

• Track progress

• add-labels

• State management

Debug Workflow Issues

• Check compilation: gh aw compile workflow-name

• Verify files committed: git status

• Check Actions enabled: Settings → Actions

• Enable PR creation: Settings → Actions → General

• Review workflow logs in Actions tab