gh-aw-workflow-authoring

name	gh-aw-workflow-authoring
description	Master GitHub Agentic Workflows authoring - markdown syntax, natural language instructions, YAML frontmatter, compilation, and workflow patterns
license	Apache-2.0
version	2.0.1
last_updated	"2026-04-13T00:00:00.000Z"
tags	["github-agentic-workflows","workflow-authoring","markdown","natural-language","ai-automation"]

✍️ GitHub Agentic Workflows - Workflow Authoring Skill

🔴 AI FIRST Quality Principle

Apply the AI FIRST principle: never accept first-pass quality. Minimum 2 iterations. Read all output, improve every section. No shortcuts.

📋 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
imports:                # Reusable prompt modules (resolved relative to workflow file)
  - ../prompts/00-base-contract.md
  - ../prompts/07-commit-and-pr.md

Factoring shared rules — prefer imports: over inlining large prompt blocks. In this repo see .github/prompts/ for a bounded-context example: 8 core modules + 1 Tier-C extension, each ≤ 300 lines, with a dependency matrix in the README.md. Workflow .md files stay ≤ 200 lines of body and contain only workflow-unique business rules.

🛠️ 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

2. 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

🆕 v0.68.1 Features

AI Engine Selection

Specify the engine in frontmatter or let gh aw compile choose the default:

---
engine:
  id: copilot                      # Repo convention: use Copilot engine, select model via `model`
  model: claude-sonnet-4.6         # Engine-specific model identifier (e.g. claude-sonnet-4.6, claude-opus-4.5)
  # Note: engine.mcp.session-timeout is NOT supported by MCP Gateway v0.3.1 — do not set it
timeout-minutes: 5
---

Integrity Filtering

Control who can trigger workflows in public repositories:

---
tools:
  github:
    toolsets: [issues, labels]
    min-integrity: approved  # Only collaborators+ (default)
    # min-integrity: none    # Allow all users (for public triage)
---

Threat Detection

Every workflow automatically includes threat detection. The dedicated scan checks agent outputs for:

• Prompt injection attacks
• Leaked credentials
• Malicious code patterns

If suspicious content is found, the workflow fails immediately and nothing is written.

Cross-Repository Workflows

---
safe-outputs:
  create-pull-request:
    target-repo: owner/other-repo  # Cross-repo PRs
---

Runtime Configuration

All agentic workflows MUST include the runtimes: field to enforce specific runtime versions:

runtimes:
  node:
    version: "26"    # Required: Node.js 26
  python:
    version: "3.12"  # Optional: Python 3.12
    action-repo: "actions/setup-python"
    action-version: "v5"

Runtimes from imported shared workflows are merged automatically.

Agentic Workflows Introspection Tool

Enable workflow introspection with:

tools:
  agentic-workflows: true

Provides: status, compile, logs, audit, checks tools for self-improving workflows.

MCP Server Inspection

Debug MCP server configurations from the command line:

gh aw mcp inspect                                             # List all
gh aw mcp inspect workflow-name                                # Inspect workflow
gh aw mcp inspect workflow-name --server name                  # Filter server
gh aw mcp inspect workflow-name --server name --tool tool-name # Tool details

Workflow Commands (Slash Commands)

Trigger workflows from issue/PR comments:

---
on:
  issue_comment:
    types: [created]
    command: /plan   # Triggers on `/plan` comments
---

🏭 Agent Factory Patterns (Best Practices from github/gh-aw)

High-Impact Patterns

Pattern	Description	Example Merge Rate
Plan Command	/plan decomposes issues into sub-tasks	67% (514/761 PRs)
Discussion Task Miner	Extracts tasks from discussion threads	57% (60/105 PRs)
Code Simplifier	Daily incremental code improvements	Continuous
Issue Triage Agent	Auto-labels and comments on new issues	Event-driven

Scheduling Best Practices

Prefer fuzzy schedules over fixed cron to distribute workflow execution times and reduce load spikes:

---
on:
  schedule: daily on weekdays              # Recommended: Mon-Fri, auto-distributed
  schedule: daily around 9:00 on weekdays  # With approximate time hint
  schedule: weekly on friday around 7:00   # Weekly with day and time
  schedule: every 6 hours                  # Periodic interval
---

The compiler converts fuzzy schedules to deterministic cron expressions, scattering execution times automatically. This avoids the "Monday wall of work" problem where weekend tasks pile up.

Use fixed cron only when the exact time matters (e.g., monthly runs on specific dates):

---
on:
  schedule:
    - cron: "0 8 1 * *"    # 1st of month — no fuzzy equivalent
    - cron: "0 10 28 * *"  # 28th of month
---

Stagger schedules to avoid resource contention. Use timeout-minutes: 5 for quick tasks, timeout-minutes: 45 for complex analysis.

Cross-Run Memory Patterns

gh-aw provides two built-in memory mechanisms (prefer these over @modelcontextprotocol/server-memory which is ephemeral per run):

Mechanism	Persistence	Scope	Use Case
cache-memory:	GitHub Actions cache, configurable via retention-days (eviction-dependent)	Per-workflow or shared via key	Session state, intermediate results, cross-run context
cache:	GitHub Actions cache	Per-workflow	Dependencies, build artifacts

Recommended: cache-memory: for cross-run context:

tools:
  cache-memory:
    key: news-${{ github.workflow }}-${{ inputs.article_date || 'today' }}
    retention-days: 14

Avoid: @modelcontextprotocol/server-memory — dies when the process ends, lost every run. Also skip @modelcontextprotocol/server-sequential-thinking — Claude has native CoT reasoning; it wastes context tokens.

📚 References

• Official Documentation
• Quick Start Guide
• How They Work
• Workflow Examples
• Agent Factory Blog (19-part series)
• LLM-friendly Docs

✅ 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 — use gh aw compile to validate
• ✅ Focus on single responsibility
• ✅ Compile generates .lock.yml — never edit lock files manually
• ✅ Natural language beats complex YAML
• ✅ Use min-integrity for public repo security
• ✅ Threat detection is always active — no opt-out needed

---

Version: 2.0.0
Last Updated: 2026-04-02
Maintained by: Hack23 AB

---

🔗 Integration with Riksdagsmonitor agentic workflows

This gh-aw skill is applied by the 11 agentic news workflows in .github/workflows/news-*.md. Their domain contract (analysis-artifact product, gate, article contract) lives in:

• .github/prompts/README.md — module catalogue, import rules, AI-FIRST 2-pass rule.
• analysis/methodologies/ai-driven-analysis-guide.md + analysis/templates/ — 9 core / 14 Tier-C artifacts.
• 05-analysis-gate.md — the single blocking gate before any article content is written.

Upstream gh-aw docs (v0.69.3): abridged · complete · agentic-workflows blog series · source repo · GitHub CLI manual.