GitHub Agentic Workflows Adoption Skill

Purpose

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

1. Investigating existing workflows and automation opportunities
2. Prioritizing which workflows to create based on repository needs
3. Creating production-ready agentic workflows in parallel
4. Resolving CI issues, merge conflicts, and integration problems
5. 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:

1. Query gh-aw repository: Use gh api to list all workflows in github/gh-aw
2. Analyze workflows: Read 5-10 diverse workflow files to understand patterns
3. Categorize workflows: Group by purpose (security, maintenance, automation, etc.)
4. Identify gaps: Compare against your repository's current automation
5. 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):

1. Read reference workflow from gh-aw repository
2. Adapt to your repository's context and requirements
3. Create workflow file in .github/workflows/[name].md
4. Add comprehensive error resilience (API failures, rate limits, network issues)
5. Configure safe-outputs, permissions, tools appropriately
6. Create feature branch and commit
7. 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:

1. Merge feature branches to integration branch first (if exists)
2. Run CI checks on integration branch
3. Merge integration → main when all checks pass
4. 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:

1. gh CLI installed: gh --version
2. gh-aw extension installed: gh extension install github/gh-aw
3. Repository access: Write permissions to create branches and PRs
4. Authentication: GitHub token with appropriate scopes
5. 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:

1. ✅ Repository has 10-20 production agentic workflows
2. ✅ All workflows compile without errors
3. ✅ CI/CD pipeline includes workflow validation
4. ✅ Workflows follow security best practices
5. ✅ Team understands how to create and modify workflows
6. ✅ Workflows handle errors gracefully and provide audit trails
7. ✅ Maintenance hub monitors workflow health
8. ✅ Documentation explains each workflow's purpose and usage

Next Steps After Adoption

1. Monitor workflow health: Use workflow-health-dashboard.md
2. Iterate based on feedback: Adjust workflows as team needs evolve
3. Create custom workflows: Use patterns learned to build new automation
4. Share learnings: Document successful patterns for other repositories
5. 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:

1. SKILL.md (Tutorial/Overview): Getting started guide, quick reference, high-level concepts
2. examples.md (How-to guides): Step-by-step practical examples and troubleshooting solutions
3. patterns.md (Explanation): Understanding patterns, anti-patterns, and best practices
4. 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").