✍️ GitHub Agentic Workflows - Workflow Authoring Skill

📋 Purpose

Master the art of authoring GitHub Agentic Workflows - creating AI-powered automation using natural language markdown instead of complex YAML. This skill provides comprehensive expertise in workflow design, natural language instructions, configuration, and best practices for effective agentic automation.

🎯 Core Concepts

What Makes Agentic Workflows Different?

Traditional GitHub Actions:

Complex conditional logic

if: | contains(github.event.issue.labels..name, 'bug') && !contains(github.event.issue.labels..name, 'wontfix') && github.event.issue.state == 'open' run: echo "Process bug"

Agentic Workflow:

If this is an open bug that should be fixed, provide helpful triage information.

Key Differences:

Traditional Actions Agentic Workflows

✅ Deterministic 🤖 AI-driven decisions

⚙️ Complex YAML 📝 Natural language

🔧 Fixed logic paths 🧠 Context-aware responses

📊 Explicit conditionals 💡 Inferred intent

🏗️ Workflow Structure

File Anatomy

.github/ ├── workflows/ │ ├── issue-triage.md # Source (human-authored) │ └── issue-triage.lock.yml # Compiled (generated)

Workflow File Structure:

YAML Frontmatter - Configuration

on: issues permissions: read-all tools: github: toolsets: [issues] safeoutputs___comment: engine: copilot

Markdown Body - Natural Language Instructions

Analyze this issue and provide helpful triage information.

Consider:

• Issue content and context
• Related issues and PRs
• Historical patterns
• Repository conventions

Provide actionable recommendations.

YAML Frontmatter

Required Fields:

on: issues # Trigger event permissions: read-all # Security permissions tools: # Available tools github: engine: copilot # AI engine

Optional Fields:

name: "Issue Triage" # Workflow name description: "Automated issue analysis" timeout-minutes: 10 # Execution timeout concurrency: # Concurrency control group: ${{ github.ref }} cancel-in-progress: true

🛠️ Tools Configuration

GitHub Tools

Repository Operations:

tools: github: toolsets: - repos # File operations - issues # Issue management - pull_requests # PR operations - projects # GitHub Projects

Examples:

tools: github: toolsets: [repos]

Review the repository structure and suggest improvements.

Safe Outputs

Write Operations:

tools: safeoutputs___issue: # Create/update issues safeoutputs___pull_request: # Create PRs safeoutputs___comment: # Add comments safeoutputs___file: # Modify files allowed_paths: - "docs/**/*.md" safeoutputs___label: # Manage labels safeoutputs___noop: # Read-only mode

Example:

tools: safeoutputs___comment: safeoutputs___label:

Analyze this issue, add appropriate labels, and provide feedback.

File Operations

tools: edit: # Edit existing files view: # Read file contents create: # Create new files

Shell Commands

tools: bash: allowed-commands: - npm - git - python3

Security Note: Be restrictive with shell access.

Web Access

tools: web-fetch: # Fetch URLs web-search: # Search the web

Browser Automation

tools: playwright: headless: true

Custom MCP Servers

tools: custom-mcp: url: https://your-mcp-server.com headers: Authorization: ${{ secrets.API_TOKEN }}

📝 Natural Language Instructions

Writing Effective Prompts

1. Be Specific and Clear:

❌ Bad:

Do something with this issue.

✅ Good:

Analyze this issue and:

1. Determine if it's a bug, feature request, or question

2. Check for duplicates in existing issues

3. Suggest appropriate labels

4. Add a helpful comment with next steps

5. Provide Context:

❌ Bad:

Fix the code.

✅ Good:

Review the changed files in this PR and:

• Check for common security issues (SQL injection, XSS)
• Verify error handling is comprehensive
• Ensure tests cover new functionality
• Suggest improvements following our style guide

3. Structure with Lists:

Perform code review with focus on:

Security:

• Input validation
• Authentication checks
• Data sanitization

Quality:

• Code duplication
• Function complexity
• Test coverage

Documentation:

• API documentation
• Inline comments
• README updates

4. Use Examples:

Analyze this pull request and provide feedback similar to:

"## Code Review

Security Concerns

• Line 45: User input not validated

Performance

• Line 78: Consider caching this result

Style

• Follows project conventions ✓"

Prompt Engineering Patterns

Pattern 1: Analyze → Decide → Act

1. Analyze the issue description and comments
2. Decide if it's a duplicate or new issue
3. If duplicate: Close with reference to original
4. If new: Add labels and assign to appropriate team

Pattern 2: Conditional Instructions

If this is a security issue:

• Add 'security' label
• Mark as high priority
• Notify security team

If this is a feature request:

• Add 'enhancement' label
• Ask for use case details
• Add to product backlog

Pattern 3: Multi-Step Workflow

Step 1: Review all changed files Step 2: Identify potential issues Step 3: For each issue found:

• Note the file and line number
• Explain the problem
• Suggest a solution Step 4: Summarize findings in a comment

🎯 Workflow Examples

Example 1: Issue Triage

name: "Issue Triage" on: issues permissions: read-all

tools: github: toolsets: [issues] safeoutputs___label: safeoutputs___comment:

Automated Issue Triage

Analyze this new issue and provide comprehensive triage:

Classification

Determine if this is:

• 🐛 Bug: Something isn't working
• ✨ Feature: New functionality request
• ❓ Question: Help or clarification needed
• 📚 Documentation: Documentation improvement

Duplicate Check

Search for similar issues using keywords from the title and description. If a duplicate is found, note the issue number.

Priority Assessment

Based on:

• Impact (how many users affected)
• Severity (how critical)
• Workaround availability

Suggest priority: high, medium, or low

Actions

Using safeoutputs___label, add appropriate labels:

• Type: bug/feature/question/docs
• Priority: high/medium/low
• Component: affected area

Using safeoutputs___comment, provide:

• Classification explanation
• Duplicate status (if any)
• Recommended priority with reasoning
• Suggested assignee or team
• Next steps for the reporter

Example 2: PR Code Review

name: "Code Review Assistant" on: pull_request permissions: read-all

tools: github: toolsets: [pull_requests, repos] bash: allowed-commands: [git, npm] safeoutputs___comment:

Automated Code Review

Perform a comprehensive code review of this pull request:

Files Changed

Review each changed file for:

Security

• Input validation
• SQL injection risks
• XSS vulnerabilities
• Authentication/authorization
• Sensitive data exposure

Code Quality

• Function complexity
• Code duplication
• Error handling
• Edge cases

Testing

• Test coverage
• Test quality
• Missing test cases

Performance

• Inefficient algorithms
• Memory leaks
• Database query optimization

Style

• Follows project conventions
• Naming consistency
• Documentation completeness

Summary

Provide:

• Overall assessment (approve/needs work/concerns)
• Count of issues by severity
• Most critical items to address
• Positive feedback on good practices

Use safeoutputs___comment to post the review.

Example 3: Documentation Updates

name: "Documentation Sync" on: push paths:

• 'src/**/*.ts'

permissions: read-all

tools: github: toolsets: [repos] bash: allowed-commands: [git] safeoutputs___file: allowed_paths: - "docs/**/*.md" - "README.md"

Keep Documentation Current

When code changes, ensure documentation stays synchronized:

Changed Files Analysis

1. Identify which source files changed
2. Determine if they have corresponding documentation
3. Review the nature of changes (new features, API changes, deprecations)

Documentation Updates

For each relevant change:

API Documentation

• Update function signatures
• Add new method documentation
• Mark deprecated features
• Update examples

README

• Add new feature descriptions
• Update installation if needed
• Refresh examples
• Update version compatibility

Changelog

• Add entry for this change
• Include breaking changes prominently
• Link to PR/issue

Implementation

Use safeoutputs___file to update documentation files. Ensure:

• Examples are tested and work
• Links are valid
• Formatting is consistent
• Version numbers are current

Example 4: Dependency Management

name: "Dependency Update Review" on: pull_request paths:

• 'package.json'
• 'package-lock.json'

permissions: read-all

tools: github: toolsets: [pull_requests] bash: allowed-commands: [npm] web-fetch: safeoutputs___comment:

Dependency Update Analysis

When dependencies are updated, provide security and compatibility review:

Changed Dependencies

Identify all dependency changes:

• New dependencies added
• Updated versions
• Removed dependencies

Security Check

For each changed dependency:

1. Check npm audit for known vulnerabilities
2. Review GitHub advisory database
3. Check Snyk or similar databases
4. Note any security warnings

Compatibility Check

• Review changelog for breaking changes
• Check if major version bump
• Verify Node.js version compatibility
• Check for deprecated features used

License Check

• Verify license compatibility
• Flag any license changes
• Note GPL or other copyleft licenses

Recommendation

Provide:

• ✅ Safe to merge
• ⚠️ Review required
• ❌ Security concerns

Include:

• Specific issues found
• Recommended actions
• Links to relevant documentation

Use safeoutputs___comment to post the analysis.

Example 5: Scheduled Maintenance

name: "Weekly Repository Health Check" on: schedule: - cron: '0 0 * * 0' # Every Sunday

permissions: read-all

tools: github: toolsets: [issues, pull_requests, repos] safeoutputs___issue:

Weekly Repository Health Report

Generate a comprehensive repository health report:

Open Issues Analysis

• Total open issues
• Issues by label
• Stale issues (30+ days)
• High priority unassigned
• Trends (increasing/decreasing)

Pull Requests Review

• Open PRs count
• Average PR age
• PRs awaiting review
• Stale PRs (14+ days)
• Merge rate trend

Code Quality Metrics

• Test coverage
• Recent build failures
• Security vulnerabilities
• Dependency updates needed

Community Health

• New contributors this week
• First-time contributors
• Response times
• Merge frequency

Recommendations

Based on the analysis:

1. Issues to prioritize
2. PRs needing attention
3. Maintenance tasks
4. Community engagement opportunities

Use safeoutputs___issue to create:

• Weekly health report issue
• Label it 'maintenance' and 'automated'
• Assign to repository maintainers

⚙️ Advanced Configuration

Concurrency Control

on: issues

concurrency: group: issue-${{ github.event.issue.number }} cancel-in-progress: true

Use Cases:

• Prevent duplicate processing

• Cancel outdated runs

• Resource management

Conditional Execution

on: pull_request

if: | github.event.pull_request.draft == false && !contains(github.event.pull_request.labels.*.name, 'skip-review')

Timeouts

timeout-minutes: 5 # Cancel if exceeds 5 minutes

Environment Variables

env: NODE_VERSION: '24' DEBUG: 'true'

🔄 Compilation Process

Manual Compilation

Install compiler

npm install -g @github/agentic-workflows-compiler

Compile workflow

aw-compile .github/workflows/issue-triage.md

Output: .github/workflows/issue-triage.lock.yml

Automatic Compilation

GitHub Actions:

name: Compile Agentic Workflows

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

jobs: compile: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4

  - name: Compile Workflows
    run: |
      npm install -g @github/agentic-workflows-compiler
      aw-compile .github/workflows/*.md
  
  - name: Commit Compiled Files
    run: |
      git add .github/workflows/*.lock.yml
      git commit -m "Compile agentic workflows"
      git push

Validation

Validate syntax

aw-validate .github/workflows/issue-triage.md

Check for common issues

aw-lint .github/workflows/issue-triage.md

🎨 Best Practices

1. Single Responsibility

❌ Bad: Multiple tasks in one workflow

Triage issues, review PRs, update documentation, and manage dependencies.

✅ Good: Focused workflow

Triage new issues by analyzing content, checking for duplicates, and applying appropriate labels.

2. Clear Success Criteria

❌ Bad: Vague instructions

Make this better.

✅ Good: Specific criteria

Improve this code by:

• Reducing cyclomatic complexity to <10
• Adding error handling for edge cases
• Including unit tests with 80%+ coverage

3. Tool Minimalism

❌ Bad: Grant all tools

tools: github: toolsets: [''] bash: safeoutputs___:

✅ Good: Only required tools

tools: github: toolsets: [issues] safeoutputs___comment:

4. Error Guidance

If you encounter issues:

1. Check for existing similar issues first

2. If API rate limit reached, note it and suggest trying later

3. If insufficient permissions, explain what's needed

4. Always provide fallback recommendations

5. Testing Instructions

Before implementation:

1. Validate file paths exist
2. Check for required permissions
3. Verify tool availability
4. Test with dry-run if possible

Use safeoutputs___noop to report findings if validation fails.

🚨 Common Pitfalls

Pitfall 1: Overly Complex Instructions

❌ Don't:

Analyze code considering 27 different quality metrics, cross-reference with 15 different documentation sources, generate detailed reports with statistical analysis, create visualization dashboards, and...

✅ Do:

Focus on 3 key areas:

1. Security vulnerabilities
2. Test coverage
3. Code complexity

Provide actionable feedback for each.

Pitfall 2: Assuming Tool Availability

❌ Don't:

Use bash to run npm install...

✅ Do:

tools: bash: allowed-commands: [npm]

If npm is available, run npm install to verify dependencies.

Pitfall 3: Ignoring Rate Limits

❌ Don't:

Search all 10,000 issues for duplicates.

✅ Do:

Search recent issues (last 90 days) for duplicates. If none found, note that older issues weren't checked due to performance.

Pitfall 4: Not Handling Failures

❌ Don't:

Update the file with new content.

✅ Do:

Attempt to update the file. If it fails (permissions, file doesn't exist, etc.):

• Use safeoutputs___noop to explain the issue
• Suggest manual resolution steps

🔗 Related Skills

• gh-aw-safe-outputs - Understanding write operations

• gh-aw-tools-ecosystem - Available tools and capabilities

• gh-aw-mcp-gateway - MCP server integration

• gh-aw-continuous-ai-patterns - Workflow patterns and strategies

• gh-aw-github-actions-integration - Deployment and CI/CD

📚 References

• GitHub Agentic Workflows Documentation

• Quick Start Guide

• How They Work

• Workflow Examples

• Best Practices

✅ Remember

• ✅ Write in natural language, not code

• ✅ Be specific and provide context

• ✅ Use tool minimalism (least privilege)

• ✅ Structure with clear sections

• ✅ Provide examples in instructions

• ✅ Handle errors gracefully

• ✅ Test before deploying

• ✅ Focus on single responsibility

• ✅ Compile generates .lock.yml

• ✅ Natural language beats complex YAML

Version: 1.0.0

Last Updated: 2026-02-17

Maintained by: Hack23 AB