// GitHub Agentic Workflows (gh-aw) - markdown-based AI automation with 5-layer security, safe outputs, and Continuous AI patterns
| 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 |
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.
Apply this skill when:
gh-aw enforces defense-in-depth with five security layers:
MUST:
.md) in .github/workflows/--- markers at the top.lock.yml files using gh aw compile.md (source) and .lock.yml (compiled) filesMUST NOT:
.lock.yml files (regenerate via compile).md changes without recompilingMUST:
on: trigger(s) with appropriate event types and activity filterspermissions: with specific resource scopes (e.g., issues: read, contents: read)tools: with specific toolsets (e.g., github: with toolsets: [issues, labels])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)timeout-minutes: to prevent runaway workflowsMUST NOT:
permissions: write-all without explicit security reviewsafe-outputs: for workflows that create/modify resourcesMUST:
MUST NOT:
MUST:
engine: needed)engine: claude and configure ANTHROPIC_API_KEY secretengine: codex and configure OPENAI_API_KEY secretMUST NOT:
MUST:
issues: with types: [opened, reopened] for issue automationpull_request: for PR-related automationschedule: with human-friendly syntax (daily, weekly on monday) or cronworkflow_dispatch: for manual executionslash_command: with command: for comment-triggered actions (e.g., /plan, /analyze)workflow_dispatch before enabling automatic triggersMUST NOT:
MUST:
tools:
github:
toolsets: [issues, labels, pull-requests]
safe-inputs: for custom lightweight inline functionsedit: tool for file modifications, bash: for shell commandsweb-search: or web-fetch: for external information with network restrictionsnetwork: allowlists when external access is neededmin-integrity: for public repos to control event visibilityMUST NOT:
MUST:
gh extension install github/gh-awgh aw init for new repositoriesgh aw compile (generates .lock.yml)gh aw compile --watch for developmentgh aw run <workflow-name> for manual testinggh aw logs <workflow-name> for debugginggh aw add-wizard <url>MUST NOT:
gh aw init for new repositories---
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.
---
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
---
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.
---
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
---
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.
---
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.
workflow_dispatchcreate-commentgh aw compile --watch for rapid iterationissues: read) not read-alltitle-prefix, labels, allowed, maxnetwork: {} for zero external access, network: defaults for GitHub-onlythreat-detection for all safe-outputs workflowsmin-integrity: in public repos for event visibility controlThe GitHub Next team operates 100+ workflows. Key learnings:
/plan command + sub-issuesgh aw logs and GitHub Actions logs1. 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
| 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 |
| 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 |
This skill aligns with:
| 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 |
gh-aw CLI usage, compilation, testing, debugging, add-wizard, and CI/CD practices for GitHub Agentic Workflows
Multi-agent coordination, orchestrator-worker patterns, /plan decomposition, and project coordination for GitHub Agentic Workflows
5-layer defense-in-depth security for GitHub Agentic Workflows - safe outputs, threat detection, AWF firewall, and zero-trust patterns
Continuous AI patterns from Agent Factory - issue triage, documentation sync, code quality, security scanning, and project coordination
GDPR compliance including privacy by design, data protection requirements, consent management, right to be forgotten, and data breach response
Approved cryptographic algorithms, TLS enforcement, key management, and certificate handling per Hack23 Cryptographic Controls Policy