GitHub Agentic Workflows Adoption Skill

Purpose

Guides you through adopting GitHub Agentic Workflows (gh-aw) in any repository by:

• Investigating existing workflows and automation opportunities

• Prioritizing which workflows to create based on repository needs

• Creating production-ready agentic workflows in parallel

• Resolving CI issues, merge conflicts, and integration problems

• Validating workflows compile and follow best practices

This skill orchestrates the complete gh-aw adoption process, from zero to production-ready agentic automation.

When to Use This Skill

Activate this skill when you want to:

• Adopt gh-aw in a repository that doesn't have agentic workflows

• Learn about available gh-aw workflow patterns from the gh-aw repository

• Create multiple agentic workflows efficiently

• Automate repetitive repository tasks (issue triage, PR labeling, security scans, etc.)

• Debug or upgrade existing agentic workflows

• Troubleshoot workflow failures (MCP server errors, permission issues, CI failures)

Quick Start

Basic usage:

Adopt GitHub Agentic Workflows in this repository

With specific goals:

Adopt gh-aw to automate:

• Issue triage and labeling
• PR review reminders
• Security scanning
• Deployment automation

Investigation only:

Investigate what agentic workflows the gh-aw team uses

Troubleshooting:

My workflow is failing with "MCP server(s) failed to launch: docker-mcp"

Help me fix the "lockdown mode without custom token" error

How It Works

Phase 1: Investigation (15-20 minutes)

Goal: Understand what agentic workflows exist and what gaps your repository has.

Steps:

• Query gh-aw repository: Use gh api to list all workflows in github/gh-aw

• Analyze workflows: Read 5-10 diverse workflow files to understand patterns

• Categorize workflows: Group by purpose (security, maintenance, automation, etc.)

• Identify gaps: Compare against your repository's current automation

• Create priority list: Rank workflows by impact and feasibility

Output: Markdown report with:

• List of all available workflow patterns

• Gap analysis for your repository

• Prioritized implementation plan (15-20 recommended workflows)

Phase 2: Parallel Workflow Creation (30-45 minutes)

Goal: Create multiple production-ready agentic workflows simultaneously.

Architecture:

• Launch separate agent threads for each workflow

• Each agent creates workflow independently

• Central coordinator tracks progress and handles conflicts

• All workflows created in feature branches

Workflow Creation Process (per workflow):

• Read reference workflow from gh-aw repository

• Adapt to your repository's context and requirements

• Create workflow file in .github/workflows/[name].md

• Add comprehensive error resilience (API failures, rate limits, network issues)

• Configure safe-outputs, permissions, tools appropriately

• Create feature branch and commit

• Report completion to coordinator

Example parallel execution:

Agent 1 → issue-classifier.md Agent 2 → pr-labeler.md Agent 3 → security-scanner.md Agent 4 → stale-pr-manager.md Agent 5 → weekly-summary.md ... (up to N agents in parallel)

Phase 3: CI Diagnostics and Integration (15-30 minutes)

Goal: Ensure all workflows compile and pass CI checks.

Common issues and resolutions:

Issue: Workflow compilation failures

• Solution: Run gh aw compile and fix YAML syntax errors

• Common errors: Missing required fields, invalid tool names, permission issues

Issue: Merge conflicts

• Solution: Rebase feature branches on latest main/integration

• Strategy: Merge integration → feature branches in sequence

Issue: CI/CodeQL failures

• Solution: Ensure external checks pass before merging

• Use gh pr checks to monitor status

Issue: Safe-output validation errors

• Solution: Configure appropriate limits for each safe-output type

• Reference: Check gh-aw documentation for safe-output syntax

Phase 4: Validation and Deployment (10-15 minutes)

Goal: Verify workflows are production-ready and merge to main.

Validation checklist:

• All workflows compile to .lock.yml files

• No YAML syntax errors

• Permissions follow least-privilege principle

• Safe-outputs configured with appropriate limits

• Network firewall rules specified

• Error resilience patterns implemented

• Workflows tested with workflow_dispatch events

• Documentation includes purpose and usage

Deployment strategy:

• Merge feature branches to integration branch first (if exists)

• Run CI checks on integration branch

• Merge integration → main when all checks pass

• Monitor first workflow executions for runtime errors

Navigation Guide

When to Read Supporting Files

reference.md - Read when you need:

• Complete gh-aw CLI command reference

• Detailed workflow schema and configuration options

• Security best practices and sandboxing details

• MCP server integration patterns

• Repo-memory configuration and usage

examples.md - Read when you need:

• Real workflow creation examples from actual adoption sessions

• Step-by-step implementation guides for specific workflow types

• Troubleshooting common errors with solutions

• Parallel agent orchestration patterns

• CI/CD integration examples

patterns.md - Read when you need:

• Production workflow architecture patterns

• Error resilience strategies (retries, fallbacks, circuit breakers)

• Safe-output configuration best practices

• Security hardening techniques

• Performance optimization tips

Key Concepts

GitHub Agentic Workflows (gh-aw)

What it is: CLI extension for GitHub that enables creating AI-powered workflows in natural language using markdown files with YAML frontmatter.

Key features:

• Write workflows in markdown, compile to GitHub Actions YAML

• AI engines: Copilot, Claude, Codex, or custom

• MCP server integration for additional tools

• Safe-outputs for structured GitHub API communication

• Sandboxed execution with bash and edit tools enabled by default

• Repo-memory for persistent agent state

Workflow Structure

on: [trigger events] permissions: [required permissions] engine: copilot | claude-code | claude-sonnet-4-5 | codex tools: [tool configuration] safe-outputs: [GitHub API output limits] network: [firewall configuration]

Workflow Name

[Natural language prompt for AI agent]

Critical Configuration Elements

Permissions: Always use least-privilege

permissions: contents: read issues: write pull-requests: write

Safe-outputs: Limit GitHub API mutations

safe-outputs: add-comment: max: 5 expiration: 1d close-issue: max: 3

Network: Explicit firewall rules

network: firewall: true allowed: - defaults - github

Error Resilience Patterns

Always implement:

• API rate limit handling (exponential backoff)

• Network failure retries (3 attempts with delays)

• Partial failure recovery (continue on error)

• Comprehensive audit trails (log all actions to repo-memory)

• Safe-output limit awareness (prioritize critical actions)

Prerequisites

Before using this skill, ensure:

• gh CLI installed: gh --version

• gh-aw extension installed: gh extension install github/gh-aw

• Repository access: Write permissions to create branches and PRs

• Authentication: GitHub token with appropriate scopes

• Optional: Integration branch: For staging workflow changes before main

Repo Guardian: Featured First Workflow

Repo Guardian is the recommended first workflow to adopt in any repository. Ready-to-copy templates are included in this skill directory:

• repo-guardian.md — The gh-aw agentic workflow (natural language prompt for the AI agent)

• repo-guardian-gate.yml — Standard GitHub Actions workflow that enforces agent findings as a blocking CI check

What It Does

Reviews every PR for ephemeral content that doesn't belong in the repo:

• Meeting notes, sprint retrospectives, status updates

• Temporary scripts (fix-thing.sh , one-off-migration.py )

• Point-in-time documents that will become stale

• Files with date prefixes suggesting snapshots

Posts a PR comment with findings. Collaborators can override with repo-guardian:override <reason> .

Quick Setup

1. Copy templates

mkdir -p .github/workflows cp .claude/skills/gh-aw-adoption/repo-guardian.md .github/workflows/repo-guardian.md cp .claude/skills/gh-aw-adoption/repo-guardian-gate.yml .github/workflows/repo-guardian-gate.yml

2. Compile the agentic workflow (pins the gh-aw version)

cd .github/workflows gh aw compile repo-guardian

3. Add COPILOT_GITHUB_TOKEN secret (PAT with read:org + repo scopes)

Repository Settings → Secrets and variables → Actions → New repository secret

4. Commit and push all three files

git add .github/workflows/repo-guardian.md
.github/workflows/repo-guardian.lock.yml
.github/workflows/repo-guardian-gate.yml git commit -m "feat: Add Repo Guardian agentic workflow" git push

Common Workflows to Adopt

Based on analysis of 100+ workflows in the gh-aw repository, these are high-impact workflows to consider:

Security & Compliance (High Priority):

• repo-guardian.md

• Block PRs containing ephemeral content (included as template — see above)

• secret-validation.md

• Monitor secrets for expiration and leaks

• container-security-scanning.md

• Scan container images for vulnerabilities

• license-compliance.md

• Verify dependency licenses

• sbom-generation.md

• Generate Software Bill of Materials

Development Automation (High Priority):

• pr-labeler.md

• Automatically label PRs based on content

• issue-classifier.md

• Triage and label issues

• stale-pr-manager.md

• Close stale PRs with grace period

• changelog-generator.md

• Auto-generate changelogs from commits

Quality Assurance (Medium Priority):

• test-coverage-enforcer.md

• Block PRs below coverage threshold

• mutation-testing.md

• Run mutation tests and report survivors

• performance-testing.md

• Automated performance regression tests

Maintenance & Operations (Medium Priority):

• agentics-maintenance.md

• Hub for workflow health monitoring

• workflow-health-dashboard.md

• Weekly metrics and status reports

• dependency-updates.md

• Automated dependency update PRs

Team Communication (Lower Priority):

• weekly-issue-summary.md

• Weekly issue digest with visualizations

• team-status-reports.md

• Daily team status updates

• pr-review-reminders.md

• Nudge reviewers for stale reviews

Troubleshooting

Problem: gh-aw extension not found

gh extension install github/gh-aw gh aw --help

Problem: Compilation errors

gh aw compile --validate gh aw fix --write # Auto-fix some issues

Problem: Workflow not executing

• Check workflow file is in .github/workflows/

• Verify workflow has valid trigger (on: field)

• Check GitHub Actions logs for execution errors

• Ensure required secrets are configured

Problem: Safe-output limits exceeded

• Review safe-output configuration in workflow frontmatter

• Increase limits if appropriate

• Add prioritization logic to stay within limits

Problem: Permission denied errors

• Verify permissions: block in workflow frontmatter

• Check GitHub token has required scopes

• Ensure workflow has necessary repository permissions

Anti-Patterns to Avoid

❌ Don't: Create monolithic workflows that do everything ✅ Do: Create focused workflows with single responsibilities

❌ Don't: Skip error handling and assume APIs always succeed ✅ Do: Implement retries, fallbacks, and comprehensive error logging

❌ Don't: Use overly broad permissions (contents: write everywhere) ✅ Do: Apply least-privilege principle to each workflow

❌ Don't: Hardcode repository-specific values in workflows ✅ Do: Use GitHub context variables (${{ github.repository }} )

❌ Don't: Create workflows without testing them first ✅ Do: Test with workflow_dispatch before enabling automated triggers

Success Criteria

Your gh-aw adoption is successful when:

• ✅ Repository has 10-20 production agentic workflows

• ✅ All workflows compile without errors

• ✅ CI/CD pipeline includes workflow validation

• ✅ Workflows follow security best practices

• ✅ Team understands how to create and modify workflows

• ✅ Workflows handle errors gracefully and provide audit trails

• ✅ Maintenance hub monitors workflow health

• ✅ Documentation explains each workflow's purpose and usage

Next Steps After Adoption

• Monitor workflow health: Use workflow-health-dashboard.md

• Iterate based on feedback: Adjust workflows as team needs evolve

• Create custom workflows: Use patterns learned to build new automation

• Share learnings: Document successful patterns for other repositories

• Upgrade workflows: Keep gh-aw extension updated and apply migrations

Documentation Structure (Diátaxis Framework)

This skill follows the Diátaxis documentation framework with four complementary resources:

• SKILL.md (Tutorial/Overview): Getting started guide, quick reference, high-level concepts

• examples.md (How-to guides): Step-by-step practical examples and troubleshooting solutions

• patterns.md (Explanation): Understanding patterns, anti-patterns, and best practices

• reference.md (Reference): Technical specifications, detailed configurations, troubleshooting reference

For troubleshooting:

• Start with reference.md to understand the error and root cause

• Check examples.md for step-by-step fix instructions

• Review patterns.md to avoid the anti-pattern in future workflows

Note: This skill automates the complete gh-aw adoption process. For manual control or specific phases, invoke the skill with explicit instructions (e.g., "gh-aw-adoption: investigation only").