name	github-agentic-workflows
description	GitHub Agentic Workflows (gh-aw) - markdown-based AI automation with 5-layer security, safe outputs, and Continuous AI patterns
license	Apache-2.0

🤖 GitHub Agentic Workflows Skill

Purpose

This skill provides comprehensive guidance on GitHub Agentic Workflows (gh-aw), a Go-based GitHub CLI extension that enables writing agentic workflows in natural language using Markdown files and running them as GitHub Actions workflows. Developed by GitHub Next and Microsoft Research, gh-aw delivers repository automation with strong guardrails, safe outputs, and sandboxed execution.

gh-aw augments existing deterministic CI/CD with Continuous AI capabilities — systematic, automated application of AI to software collaboration tasks like triaging issues, maintaining documentation, improving code quality, and automating reviews.

When to Use

Apply this skill when:

Writing AI-powered repository automation as Markdown workflows
Implementing Continuous AI patterns (issue triage, documentation sync, code review, quality improvement)
Leveraging safe-outputs for write operations without granting direct write permissions
Using multiple AI engines (Copilot, Claude, Codex) for event-triggered and scheduled jobs
Building orchestrator-worker patterns for complex multi-agent coordination
Automating tasks that traditionally require human judgment

5-Layer Security Architecture

gh-aw enforces defense-in-depth with five security layers:

Read-only tokens — Agent receives only read-scoped GitHub token
Zero secrets in agent — Write tokens/API keys exist only in separate isolated jobs
Containerized with network firewall — Agent Workflow Firewall (AWF) routes all outbound traffic through Squid proxy with domain allowlist
Safe outputs with guardrails — Agent produces structured artifacts; a separate gated job applies only permitted actions
Agentic threat detection — AI-powered scan of proposed changes before any write; blocks prompt injection, leaked credentials, malicious code

Rules

Workflow Structure

MUST:

Create workflow files as Markdown (.md) in .github/workflows/
Include YAML frontmatter between --- markers at the top
Write natural language instructions below the frontmatter
Compile to .lock.yml files using gh aw compile
Commit both .md (source) and .lock.yml (compiled) files
Use clear, imperative task descriptions in natural language
Separate configuration (frontmatter) from instructions (body)

MUST NOT:

Manually edit .lock.yml files (regenerate via compile)
Push .md changes without recompiling
Write complex YAML conditionals in workflow files
Skip compilation step before deployment

Frontmatter Configuration

MUST:

Define on: trigger(s) with appropriate event types and activity filters
Set permissions: with specific resource scopes (e.g., issues: read, contents: read)
Configure tools: with specific toolsets (e.g., github: with toolsets: [issues, labels])
Include safe-outputs: for all write operations, using a hard limit where the output type supports it (e.g., max, max-size) or an allowlist where it does not (e.g., allowed)
Set timeout-minutes: to prevent runaway workflows

MUST NOT:

Use permissions: write-all without explicit security review
Omit safe-outputs: for workflows that create/modify resources
Hard-code secrets in frontmatter
Grant unrestricted tool access

Natural Language Instructions

MUST:

Write as if explaining a task to a colleague
Use imperative mood ("Analyze this issue", "Create a summary")
Include context, success criteria, and constraints
Define expected outputs (comments, PRs, issues)
Break complex tasks into clear numbered phases
Specify what NOT to do when relevant
Include examples of desired output format

MUST NOT:

Write vague instructions ("Do something helpful")
Assume the AI knows implicit repository context
Mix code/YAML in instruction text

Engines (AI Models)

MUST:

Use GitHub Copilot as default (no explicit engine: needed)
For Claude: set engine: claude and configure ANTHROPIC_API_KEY secret
For Codex: set engine: codex and configure OPENAI_API_KEY secret
Test with chosen engine before production deployment

MUST NOT:

Mix multiple engines in same workflow
Assume identical capabilities across engines

Triggers

MUST:

Choose appropriate trigger(s):
- issues: with types: [opened, reopened] for issue automation
- pull_request: for PR-related automation
- schedule: with human-friendly syntax (daily, weekly on monday) or cron
- workflow_dispatch: for manual execution
- slash_command: with command: for comment-triggered actions (e.g., /plan, /analyze)
Consider rate limits and costs for scheduled workflows
Test with workflow_dispatch before enabling automatic triggers

MUST NOT:

Use overly frequent schedules that waste resources
Trigger on every event type without necessity

Tools and MCP Integration

MUST:

Configure tools in frontmatter with specific toolsets:

tools:
  github:
    toolsets: [issues, labels, pull-requests]

Use safe-inputs: for custom lightweight inline functions
Use edit: tool for file modifications, bash: for shell commands
Use web-search: or web-fetch: for external information with network restrictions
Set network: allowlists when external access is needed
Use min-integrity: for public repos to control event visibility

MUST NOT:

Grant unrestricted tool access without review
Bypass tool allowlists or network access controls

Compilation and Setup

MUST:

Install: gh extension install github/gh-aw
Initialize: gh aw init for new repositories
Compile: gh aw compile (generates .lock.yml)
Watch mode: gh aw compile --watch for development
Test: gh aw run <workflow-name> for manual testing
Logs: gh aw logs <workflow-name> for debugging
Add community workflows: gh aw add-wizard <url>
Use fine-grained PATs with minimal scopes

MUST NOT:

Use classic PATs instead of fine-grained tokens
Skip gh aw init for new repositories
Commit secrets to version control

Examples

Example 1: Issue Triage (Real-World Pattern from Agent Factory)

---
timeout-minutes: 5
on:
  issues:
    types: [opened, reopened]
permissions:
  issues: read
tools:
  github:
    toolsets: [issues, labels]
safe-outputs:
  add-labels:
    allowed: [bug, feature, enhancement, documentation, question, "help wanted", "good first issue"]
  create-comment:
    max: 1
---

# Issue Triage Agent

Analyze the triggering issue (${{ github.event.issue.number }}) title and body,
then add one of the allowed labels: `bug`, `feature`, `enhancement`,
`documentation`, `question`, `help wanted`, or `good first issue`.

Skip the issue if it:
- Already has any of these labels
- Has been assigned to any user (especially non-bot users)

Do research on the issue in the context of the codebase and, after adding
the label, mention the issue author in a comment explaining why the label
was added and give a brief summary of how the issue may be addressed.

Example 2: Daily Status Report

---
on:
  schedule: daily
permissions:
  contents: read
  issues: read
  pull-requests: read
safe-outputs:
  create-issue:
    max: 1
    title-prefix: "[team-status] "
    labels: [report, daily-status]
    close-older-issues: true
---

## Daily Issues Report

Create an upbeat daily status report for the team as a GitHub issue.

## What to include

- Recent repository activity (issues, PRs, discussions, releases, code changes)
- Progress tracking, goal reminders and highlights
- Project status and recommendations
- Actionable next steps for maintainers

Example 3: Plan Command (Slash Command)

---
on:
  slash_command:
    command: /plan
permissions:
  issues: read
tools:
  github:
    toolsets: [issues]
safe-outputs:
  create-issue:
    max: 10
  create-comment:
    max: 1
---

# Plan Command

Break down the current issue into actionable sub-tasks.
Create child issues for each sub-task and link them.
Post a comment summarizing the plan with links to all created sub-issues.

Example 4: Network-Restricted Security Review

---
on: pull_request
timeout-minutes: 10
permissions:
  contents: read
  pull-requests: read
  security-events: read
tools:
  github:
    toolsets: [pull-requests, code-scanning]
network: defaults
safe-outputs:
  create-comment:
    max: 3
  threat-detection:
    enabled: true
    action: block
---

# Security-Focused PR Review

Review pull request for security issues. No external network access allowed.

Focus on:
- Hard-coded secrets or credentials
- Unsafe input handling
- Missing authentication checks
- Injection vulnerabilities

Example 5: Safe Inputs with Custom Tool

---
on: issues
permissions:
  issues: read
tools:
  github:
safe-inputs:
  calculate_priority:
    type: function
    description: Calculate issue priority based on labels and content
    code: |
      function calculate_priority(labels, body) {
        let score = 0;
        if (labels.includes('critical')) score += 10;
        if (labels.includes('security')) score += 8;
        if (labels.includes('bug')) score += 5;
        if (body.toLowerCase().includes('production')) score += 3;
        return Math.min(score, 10);
      }
safe-outputs:
  create-comment:
    max: 1
---

# Priority Calculator

Use the calculate_priority tool to assess issue priority.
Post a comment with the priority score and recommended action timeline.

Example 6: Multi-Engine Configuration

---
on: workflow_dispatch
engine: claude
permissions:
  contents: read
tools:
  github:
safe-outputs:
  create-issue:
    max: 1
---

# Advanced Analysis with Claude

Perform deep technical analysis of repository architecture.
Create an issue with findings and recommendations.

Note: Requires ANTHROPIC_API_KEY secret to be configured.

Best Practices

Start Simple, Iterate

Begin with read-only workflows using workflow_dispatch
Add safe-outputs incrementally; start with create-comment
Use gh aw compile --watch for rapid iteration
Graduate to scheduled triggers after manual testing

Clear Instructions Win

Write as if explaining to a human colleague
Include examples of desired output format
Define constraints and guardrails explicitly
Specify what NOT to do when relevant

Security First

Use specific permissions (e.g., issues: read) not read-all
Use safe-outputs constraints: title-prefix, labels, allowed, max
Use network: {} for zero external access, network: defaults for GitHub-only
Enable threat-detection for all safe-outputs workflows
Use min-integrity: in public repos for event visibility control

Agent Factory Patterns (Proven at Scale)

The GitHub Next team operates 100+ workflows. Key learnings:

Customized agents beat generic ones — tailor to your repo's context
Incremental improvement beats heroic efforts — small daily PRs
Observability is essential — track success rates and merge rates
Meta-analysis reveals hidden patterns — use AI to analyze AI behavior
Task decomposition enables coordination — /plan command + sub-issues

Monitor and Improve

Track workflow success/merge rates
Review AI output quality regularly
Refine instructions based on actual behavior
Use gh aw logs and GitHub Actions logs

Compilation Flow

1. Author:   .github/workflows/my-workflow.md
2. Compile:  gh aw compile → generates .lock.yml
3. Commit:   git add *.md *.lock.yml && git commit
4. Push:     git push
5. Secrets:  Configure API keys in repository settings
6. Test:     gh aw run my-workflow
7. Monitor:  gh aw logs my-workflow

Safe Outputs Reference

Output Type	Key Constraints	Example
`create-issue`	`title-prefix`, `labels`, `max`, `close-older-issues`	Status reports
`create-comment`	`max`	Triage analysis
`add-labels`	`allowed` list	Issue classification
`create-pull-request`	`max`, `title-prefix`	Code improvements
`create-code-scanning-alert`	`max`	Security scanning
`upload-asset`	`branch`, `max-size`, `allowed-exts`	Screenshots

Troubleshooting

Symptom	Solution
Compilation fails	Check YAML frontmatter syntax; run `gh aw compile --verbose`
Workflow doesn't trigger	Verify `.lock.yml` is committed; check trigger config
AI output quality issues	Make instructions more specific; add examples; try different engine
Permission errors	Review `permissions:` and `safe-outputs:` config; check token scopes
Network timeout	Add domain to `network:` allowlist; check AWF firewall logs

Related ISMS Policies

This skill aligns with:

Secure Development Policy - Secure automation practices
Access Control Policy - Least privilege for workflows
Cryptographic Controls Policy - Secure secret management
Information Security Policy - Overall security framework

Related Skills

Agentic Workflow Security - Security best practices and threat detection
Agentic Workflow Orchestration - Multi-agent patterns and coordination
Agentic Workflow Development - CLI usage, testing, debugging
Continuous AI Patterns - Automation patterns and best practices
MCP Server Integration - Model Context Protocol servers
Copilot Agent Patterns - Custom agent design patterns

Compliance Mapping

ISO 27001:2022

A.8.25 Secure development life cycle
A.8.32 Change management
A.5.23 Information security for use of cloud services

NIST Cybersecurity Framework 2.0

GV.OV-03: Cybersecurity supply chain risk management
PR.DS-02: Data-in-transit is protected
DE.CM-07: Monitoring for unauthorized changes

CIS Controls v8.1

Control 16: Application Software Security
- 16.1 Establish and Maintain a Secure Application Development Process
- 16.11 Leverage Vetted Modules or Services for Application Security Components

Enforcement

Severity	Violation	Action
Critical	Hard-coded secrets, `write-all` permissions	Block deployment
High	Missing compilation, unsafe tool config	Require remediation
Medium	Unclear instructions, missing docs	Create improvement ticket
Low	Style inconsistencies	Optional improvement

Version History

2026-04-02: Major update with latest gh-aw v0.45+ features, 5-layer security architecture, real-world Agent Factory patterns, safe-outputs reference table
2026-02-11: Initial skill creation

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

🤖 GitHub Agentic Workflows Skill

Purpose

When to Use

5-Layer Security Architecture

Rules

Workflow Structure

Frontmatter Configuration

Natural Language Instructions

Engines (AI Models)

Triggers

Tools and MCP Integration

Compilation and Setup

Examples

Example 1: Issue Triage (Real-World Pattern from Agent Factory)

Example 2: Daily Status Report

Example 3: Plan Command (Slash Command)

Example 4: Network-Restricted Security Review

Example 5: Safe Inputs with Custom Tool

Example 6: Multi-Engine Configuration

Best Practices

Start Simple, Iterate

Clear Instructions Win

Security First

Agent Factory Patterns (Proven at Scale)

Monitor and Improve

Compilation Flow

Safe Outputs Reference

Troubleshooting

Related ISMS Policies

Related Skills

Related Documentation

Compliance Mapping

ISO 27001:2022

NIST Cybersecurity Framework 2.0

CIS Controls v8.1

Enforcement

Version History

FilesExpand file tree

SKILL.md

Latest commit

History

SKILL.md

File metadata and controls

🤖 GitHub Agentic Workflows Skill

Purpose

When to Use

5-Layer Security Architecture

Rules

Workflow Structure

Frontmatter Configuration

Natural Language Instructions

Engines (AI Models)

Triggers

Tools and MCP Integration

Compilation and Setup

Examples

Example 1: Issue Triage (Real-World Pattern from Agent Factory)

Example 2: Daily Status Report

Example 3: Plan Command (Slash Command)

Example 4: Network-Restricted Security Review

Example 5: Safe Inputs with Custom Tool

Example 6: Multi-Engine Configuration

Best Practices

Start Simple, Iterate

Clear Instructions Win

Security First

Agent Factory Patterns (Proven at Scale)

Monitor and Improve

Compilation Flow

Safe Outputs Reference

Troubleshooting

Related ISMS Policies

Related Skills

Related Documentation

Compliance Mapping

ISO 27001:2022

NIST Cybersecurity Framework 2.0

CIS Controls v8.1

Enforcement

Version History