🛠️ Agentic Workflow Development Skill

Purpose

This skill provides comprehensive guidance on the development lifecycle for GitHub Agentic Workflows, including CLI usage, compilation, testing, debugging, version control, and maintenance practices. It focuses on developer productivity, rapid iteration, and reliable deployment of agentic automation.

When to Use

Apply this skill when:

Setting up development environment for agentic workflows
Creating, testing, and debugging workflows
Implementing CI/CD for workflow deployment
Troubleshooting workflow execution issues
Maintaining and upgrading existing workflows
Collaborating on workflow development with teams

Rules

CLI Setup and Usage

MUST:

Install GitHub CLI: gh --version to verify
Install gh-aw extension: gh extension install github/gh-aw
Keep gh-aw updated: gh extension upgrade gh-aw
Initialize repositories: gh aw init for new projects
Use CLI for all workflow operations (not manual file editing of .lock.yml)

MUST NOT:

Manually edit .lock.yml files
Use outdated gh-aw versions
Skip repository initialization
Bypass CLI for workflow management

Development Workflow

MUST:

Create workflow .md files in .github/workflows/
Use descriptive workflow names (kebab-case)
Compile after every edit: gh aw compile
Test workflows before committing: gh aw run <workflow-name>
Review compilation output for warnings
Commit both .md and .lock.yml files together
Write meaningful commit messages

MUST NOT:

Edit workflows without compiling
Commit .md without .lock.yml
Skip testing before merge
Use generic commit messages

Rapid Iteration with Watch Mode

MUST:

Use gh aw compile --watch for active development
Keep watch mode running in dedicated terminal
Review compilation errors immediately
Test changes incrementally
Save frequently to trigger recompilation

MUST NOT:

Ignore watch mode error messages
Make multiple changes without testing
Disable automatic compilation during development

Testing Strategies

MUST:

Test with workflow_dispatch trigger first
Use gh aw run <workflow-name> for manual testing
Test with real repository data
Verify safe-outputs work as expected
Test error conditions and edge cases
Review GitHub Actions logs after each test run
Test permission boundaries

MUST NOT:

Test only happy path scenarios
Skip permission testing
Test in production without staging
Ignore test failures

Debugging Techniques

MUST:

Use gh aw logs to review execution logs
Check GitHub Actions workflow run details
Review compilation output for syntax errors
Add debug logging to workflow instructions
Test workflows in isolation
Use gh aw status to check workflow health
Reproduce issues locally when possible

MUST NOT:

Debug only by editing production workflows
Ignore error messages
Skip log review
Make blind fixes without understanding root cause

Version Control Practices

MUST:

Use feature branches for workflow changes
Write descriptive pull request descriptions
Include workflow testing results in PRs
Review workflow changes carefully (both .md and .lock.yml)
Tag workflow versions for major changes
Maintain changelog for workflow evolution
Document breaking changes

MUST NOT:

Commit directly to main branch
Merge without review
Skip documentation updates
Delete workflow history

Code Review for Workflows

MUST:

Review natural language instructions for clarity
Verify security settings (permissions, tools, network)
Check safe-outputs configuration
Validate trigger appropriateness
Confirm secret usage is correct
Test workflow before approving PR
Verify compilation produces expected .lock.yml

MUST NOT:

Approve without testing
Skip security review
Ignore compilation warnings
Rubber-stamp workflow changes

Workflow Organization

MUST:

Group related workflows in subdirectories (if supported)
Use consistent naming conventions
Document workflow purpose in file header
Create README for complex workflow systems
Link related workflows explicitly
Maintain workflow dependency documentation

MUST NOT:

Create monolithic workflows (split into orchestrator-worker)
Use unclear or cryptic names
Leave workflows undocumented
Create hidden dependencies

Performance Optimization

MUST:

Profile workflow execution time
Optimize AI prompts for clarity and brevity
Batch operations when possible
Cache results to avoid redundant work
Use appropriate trigger frequencies
Monitor resource usage and costs

MUST NOT:

Over-trigger workflows
Create unnecessarily complex instructions
Ignore performance warnings
Skip cost monitoring

Maintenance and Upgrades

MUST:

Regularly update gh-aw CLI: gh extension upgrade gh-aw
Upgrade workflow dependencies: gh aw upgrade
Review and apply workflow template updates
Monitor for deprecated features
Test upgrades in non-production first
Document upgrade procedures
Maintain backward compatibility when possible

MUST NOT:

Let workflows become outdated
Skip testing after upgrades
Apply breaking changes without notice
Ignore deprecation warnings

Examples

Example 1: Complete Development Workflow

# 1. Initialize new repository for agentic workflows
cd my-repo
gh aw init

# 2. Create new workflow file
cat > .github/workflows/issue-triage.md << 'EOF'
---
on: issues
permissions: read-all
tools:
  github:
safe-outputs:
  create-comment:
    max: 1
---

# Issue Triage

Analyze new issues and provide triage information.
EOF

# 3. Start watch mode for development
gh aw compile --watch &

# 4. Edit workflow, save, watch auto-compiles
# (Make changes to issue-triage.md)

# 5. Test workflow manually
gh aw run issue-triage

# 6. Check logs
gh aw logs issue-triage

# 7. Commit both files
git add .github/workflows/issue-triage.md
git add .github/workflows/issue-triage.lock.yml
git commit -m "Add issue triage workflow"

# 8. Push and create PR
git push origin feature/issue-triage
gh pr create --title "Add issue triage workflow" \
  --body "Implements automated issue triage with AI"

Example 2: Debugging Workflow Issues

# Check workflow status
gh aw status

# Review recent logs for specific workflow
gh aw logs my-workflow --tail 100

# Check compilation for errors
gh aw compile --verbose

# Test workflow with debug output
gh aw run my-workflow --debug

# Check GitHub Actions workflow runs
gh run list --workflow=my-workflow.lock.yml

# View specific run logs
gh run view <run-id> --log

# Check for common issues
gh aw doctor

Example 3: Testing Workflow Changes

# Create test branch
git checkout -b test/workflow-improvements

# Make changes to workflow
vim .github/workflows/pr-reviewer.md

# Compile and check for errors
gh aw compile
if [ $? -ne 0 ]; then
  echo "Compilation failed"
  exit 1
fi

# Test workflow (requires PR or issue depending on trigger)
gh aw run pr-reviewer

# Wait and check results
sleep 30
gh aw logs pr-reviewer --tail 50

# If successful, commit
git add .github/workflows/pr-reviewer.md
git add .github/workflows/pr-reviewer.lock.yml
git commit -m "Improve PR reviewer workflow logic"
git push origin test/workflow-improvements

Example 4: Workflow CI/CD Pipeline

# .github/workflows/workflow-ci.yml
name: Workflow CI

on:
  pull_request:
    paths:
      - '.github/workflows/*.md'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup GitHub CLI
        run: gh --version
      
      - name: Install gh-aw
        run: gh extension install github/gh-aw
      
      - name: Compile workflows
        run: gh aw compile --check
      
      - name: Validate workflow structure
        run: |
          for workflow in .github/workflows/*.md; do
            echo "Validating $workflow"
            gh aw validate "$workflow"
          done
      
      - name: Check for security issues
        run: gh aw security-check
      
      - name: Verify lock files are up to date
        run: |
          gh aw compile
          if [ -n "$(git status --porcelain .github/workflows/*.lock.yml)" ]; then
            echo "Lock files out of date. Run: gh aw compile"
            exit 1
          fi

Example 5: Workflow with Debug Logging

---
on: workflow_dispatch
permissions: read-all
tools:
  github:
safe-outputs:
  create-comment:
    max: 1
---

# Debug Example Workflow

**DEBUG MODE ENABLED**

Log all steps for debugging:

1. List repository details
   - Log: Repository name, owner, default branch
   
2. Check issue count
   - Log: Total open issues, closed issues
   
3. Analyze most recent issue
   - Log: Issue number, title, author
   - Log: Label count, comment count
   
4. Generate report
   - Include all logged data
   - Post as comment on issue #1

Use verbose output for all operations.

Example 6: Workflow Upgrade Process

# Check current gh-aw version
gh extension list

# Upgrade gh-aw extension
gh extension upgrade gh-aw

# Check for workflow upgrades
gh aw check-updates

# Upgrade workflows to latest patterns
gh aw upgrade --dry-run  # See what would change
gh aw upgrade            # Apply upgrades

# Recompile all workflows
gh aw compile

# Test critical workflows
gh aw run critical-workflow-1
gh aw run critical-workflow-2

# If tests pass, commit
git add .github/workflows/
git commit -m "Upgrade workflows to gh-aw v2.0"

Example 7: Local Development Setup Script

#!/bin/bash
# setup-aw-dev.sh - Set up local environment for agentic workflows

set -e

echo "Setting up Agentic Workflows development environment..."

# Install/update GitHub CLI
if ! command -v gh &> /dev/null; then
  echo "Installing GitHub CLI..."
  # Installation varies by OS
  brew install gh  # macOS
fi

# Install gh-aw extension
echo "Installing gh-aw extension..."
gh extension install github/gh-aw || gh extension upgrade gh-aw

# Initialize repository
echo "Initializing repository..."
gh aw init

# Set up git hooks for workflow compilation
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/bash
# Pre-commit hook: Compile workflows
if git diff --cached --name-only | grep -q ".github/workflows/.*\.md"; then
  echo "Compiling workflows..."
  gh aw compile || exit 1
  
  # Stage updated lock files
  git add .github/workflows/*.lock.yml
fi
EOF

chmod +x .git/hooks/pre-commit

echo "Setup complete! Development environment ready."
echo "- gh-aw version: $(gh aw version)"
echo "- Pre-commit hook installed"

Example 8: Workflow Testing Framework

#!/bin/bash
# test-workflows.sh - Test all workflows

set -e

echo "Testing all agentic workflows..."

WORKFLOWS=$(ls .github/workflows/*.md | xargs -n1 basename -s .md)

for workflow in $WORKFLOWS; do
  echo "Testing: $workflow"
  
  # Compile
  gh aw compile "$workflow" || {
    echo "❌ Compilation failed: $workflow"
    exit 1
  }
  
  # Validate structure
  gh aw validate "$workflow" || {
    echo "❌ Validation failed: $workflow"
    exit 1
  }
  
  # Security check
  gh aw security-check "$workflow" || {
    echo "❌ Security check failed: $workflow"
    exit 1
  }
  
  echo "✅ $workflow passed all checks"
done

echo "All workflows tested successfully!"

CLI Command Reference

Essential Commands

# Initialize repository
gh aw init

# Compile workflows
gh aw compile                    # Compile all
gh aw compile <workflow>         # Compile specific
gh aw compile --watch            # Watch mode
gh aw compile --check            # Check only (CI)

# Run workflows
gh aw run <workflow>             # Run manually
gh aw run <workflow> --debug     # Run with debug

# View logs
gh aw logs                       # All recent logs
gh aw logs <workflow>            # Specific workflow
gh aw logs <workflow> --tail 100 # Last 100 lines

# Status and health
gh aw status                     # All workflows
gh aw status <workflow>          # Specific workflow
gh aw doctor                     # Diagnose issues

# Workflow management
gh aw add <url>                  # Add workflow from URL
gh aw add-wizard <url>           # Add with guided setup
gh aw upgrade                    # Upgrade workflows
gh aw check-updates              # Check for updates

# Validation and security
gh aw validate <workflow>        # Validate structure
gh aw security-check             # Security audit

# Version control
gh aw version                    # Show version
gh extension upgrade gh-aw       # Upgrade CLI

Best Practices Checklist

Development

Repository initialized with gh aw init
Watch mode used for active development
Workflows tested before committing
Both .md and .lock.yml committed together
Meaningful commit messages written

Testing

Security

Security check passed: gh aw security-check
Minimal permissions configured
Safe-outputs used for write operations
Secrets properly configured
Network access restricted

Collaboration

Maintenance

Troubleshooting Guide

Compilation Errors

Symptom: gh aw compile fails Solutions:

Check YAML frontmatter syntax
Verify all required fields present
Review error message carefully
Check for unclosed quotes or brackets
Validate indentation

Workflow Won't Trigger

Symptom: Workflow doesn't run on expected events Solutions:

Verify .lock.yml is committed
Check trigger configuration in frontmatter
Review GitHub Actions logs
Ensure workflow name is correct
Check repository workflow permissions

Permission Denied Errors

Symptom: Workflow fails with permission errors Solutions:

Review permissions: in frontmatter
Check if safe-outputs needed
Verify secrets configured correctly
Ensure token has required scopes
Check repository Actions permissions

Slow or Hanging Workflows

Symptom: Workflows take too long or never complete Solutions:

Add explicit timeouts
Simplify workflow instructions
Check for infinite loops
Review tool usage (disable unused tools)
Monitor GitHub Actions queue

Unexpected AI Behavior

Symptom: AI doesn't follow instructions Solutions:

Make instructions more specific
Add examples to workflow
Break complex tasks into steps
Use imperative language
Consider different engine

Related ISMS Policies

This skill aligns with:

Secure Development Policy - Secure development lifecycle
Change Management Policy - Workflow change management
Information Security Policy - Overall security framework

Related Skills

GitHub Agentic Workflows - Core workflow fundamentals
Agentic Workflow Security - Security best practices
Agentic Workflow Orchestration - Multi-workflow coordination
GitHub Actions CI/CD - CI/CD integration
Testing Strategy - Testing approaches

Compliance Mapping

ISO 27001:2022

A.8.25 Secure development life cycle
A.8.32 Change management
A.5.37 Documented operating procedures

NIST Cybersecurity Framework 2.0

PR.IP-02: System development lifecycle
PR.MA-01: Maintenance is performed
DE.CM-08: Vulnerability scans are performed

CIS Controls v8.1

Control 16: Application Software Security
- 16.1 Secure Application Development Process
- 16.3 Maintain Separate Development Environments

Enforcement

Development practice violations:

Critical: Committing without compilation, exposed secrets - Block deployment
High: Missing tests, no code review - Require remediation
Medium: Incomplete documentation, style issues - Create improvement tickets
Low: Minor optimization opportunities - Optional improvements

Version History

2026-02-11: Initial skill creation based on latest gh-aw CLI and development practices

agentic-workflow-development

🛠️ Agentic Workflow Development Skill

Purpose

When to Use

Rules

CLI Setup and Usage

Development Workflow

Rapid Iteration with Watch Mode

Testing Strategies

Debugging Techniques

Version Control Practices

Code Review for Workflows

Workflow Organization

Performance Optimization

Maintenance and Upgrades

Examples

Example 1: Complete Development Workflow

Example 2: Debugging Workflow Issues

Example 3: Testing Workflow Changes

Example 4: Workflow CI/CD Pipeline

Example 5: Workflow with Debug Logging

Example 6: Workflow Upgrade Process

Example 7: Local Development Setup Script

Example 8: Workflow Testing Framework

CLI Command Reference

Essential Commands

Best Practices Checklist

Development

Testing

Security

Collaboration

Maintenance

Troubleshooting Guide

Compilation Errors

Workflow Won't Trigger

Permission Denied Errors

Slow or Hanging Workflows

Unexpected AI Behavior

Related ISMS Policies

Related Skills

Related Documentation

Compliance Mapping

ISO 27001:2022

NIST Cybersecurity Framework 2.0

CIS Controls v8.1

Enforcement

Version History