Repo No. 3GitHub · Updated 24 September 2026 · In print

Skills Docs · No. 3

GitHub

github / gh-aw

GitHub Agentic Workflows

Start reading — 1 min

27 skills + 27 credited32,632 words

Inside this issue

1 — Install

$ npx skills add github/gh-aw

MIT5.2k stars32,632 wordsUpdated 24 September 2026

2 — Skills

27 skills + 27 credited · 2 hours 35 minutes

Agentic WorkflowsRoute gh-aw workflow design/create/debug/upgrade requests to the right prompts.1 min
Awf Release IntegratorUpgrade gh-aw to latest gh-aw-firewall release and identify follow-up spec tasks.2 min
Console RenderingUse Go struct tags to render styled terminal output in gh-aw.1 min
Custom AgentsDefine and validate GitHub custom agent files, prompts, and examples.5 min
Debugging WorkflowsDebug gh-aw workflows using run logs, audits, and failure triage.3 min

Skills Docs · Repo No. 3Whole repo as markdown

Provenance

Typeset in this issue’s own colours, resolved from a curated brand profile.

Front matter

From the README

GitHub Agentic Workflows

Hello fellow agent! Welcome to GitHub Agentic Workflows = Actions + Agent + Safety. Here are some pointers to get you started in using this tool.

Create a new workflow: https://raw.githubusercontent.com/github/gh-aw/main/create.md (opens in a new tab)
Install: https://raw.githubusercontent.com/github/gh-aw/main/install.md (opens in a new tab)
Package a workflow repository: https://raw.githubusercontent.com/github/gh-aw/main/package.md (opens in a new tab)
Reference: https://raw.githubusercontent.com/github/gh-aw/main/.github/aw/github-agentic-workflows.md (opens in a new tab)

GitHub Agentic Workflows (gh-aw) lets developers define AI-powered repository automation in Markdown with YAML frontmatter and run AI agents securely through GitHub Actions. The gh-aw GitHub CLI extension compiles each agentic workflow into a standard GitHub Actions workflow.

Use conventional GitHub Actions for deterministic builds, tests, linting, deployments, and reproducible scripts. Add an agentic workflow when a task needs reasoning or interpretation, such as issue triage, pull-request review, CI failure investigation, documentation maintenance, dependency analysis, or repository reporting. GitHub Agentic Workflows complements existing CI/CD; it does not replace it.

Built-in AI engines include GitHub Copilot, Claude Code, OpenAI Codex, Google Gemini, and Pi. Agent jobs are read-only and sandboxed by default, and configured GitHub writes are normally applied through validated safe-outputs jobs with scoped permissions.

Quick Start
How Agentic Workflows work
Security and permissions
Documentation
Contributing
Community Contributions
Related Projects
Workshop

[!NOTE] A security vulnerability (opens in a new tab) was discovered in versions >= 0.83.3, < 0.85.4 and, as a result, those releases were retired as a pre-emptive measure.

Quick Start

Install the GitHub CLI extension:

gh extension install github/gh-aw

Then follow the GitHub Agentic Workflows quickstart (opens in a new tab) to select an AI engine, add a sample workflow, and run it through GitHub Actions.

How Agentic Workflows work

An agentic workflow has two parts: YAML frontmatter configures triggers, permissions, tools, and the AI engine; the Markdown body tells the AI agent what to accomplish. The gh aw compile command validates this source and generates the .lock.yml workflow that GitHub Actions executes. Learn how GitHub Agentic Workflows works (opens in a new tab).

Security and permissions

Security, permissions, and controlled writes are core design concerns. The supported agent-job path defaults to read-only GitHub access and sandboxed execution. Safe outputs buffer configured writes, validate them, and apply them in separate jobs with scoped permissions. These controls are configurable, so workflow authors must review permissions, tools, network access, and generated files before deployment. Learn how GitHub Agentic Workflows handles security and permissions (opens in a new tab).

Using agentic workflows in your repository requires careful attention to security considerations and careful human supervision, and even then things can still go wrong. Use it with caution, and at your own risk.

Documentation

Use the GitHub Agentic Workflows documentation (opens in a new tab) for these paths:

For AI agents and retrieval tools, use the published agent prompt index (opens in a new tab), full prompt corpus (opens in a new tab), and AI-readable project summary (opens in a new tab).

Contributing

For development setup and contribution guidelines, see CONTRIBUTING.md (opens in a new tab).

Custom Go linters

To build and test repository custom linters:

go test ./pkg/linters/<linter-name>/...
go build ./cmd/linters
make golint-custom

make golint-custom builds cmd/linters and runs the custom analyzers against ./cmd/... and ./pkg/....

🌍 Community Contributions

Community members whose issues were resolved — updated automatically.

Workshop

[!TIP] Ready to learn GitHub Agentic Workflows hands-on? The Factory Tour Workshop (opens in a new tab) is a self-contained, step-by-step workshop repository designed to teach you how to build, run, and customize agentic workflows from scratch.

Colophon

How this issue was made

Source

github.com/github/gh-aw, branch main, last pushed 24 September 2026.

Licence

MIT — the text of every skill is reproduced unmodified, frontmatter included, under the upstream licence.

Discovery

54 skills found by walking the repository tree for SKILL.md, not by matching a directory convention. 4 distinct layouts observed: .claude/skills/*/SKILL.md, .github/skills/*/SKILL.md, .squad/*/skill.md, SKILL.md (repo root).

Authorship

27 of 54 skills are installed into the repository rather than published from it. They are shelved in the closing “Credited skills” part and remain the work of their own authors. A skill counts as credited when its only copy lives under one agent’s dot directory; visible directories, per-agent mirror sets, and skills installable from this repository on skills.sh all count as published.

Issue colours

Resolved from a curated brand profile — hue 295°, chroma 0.190. Two accent tones are generated per issue and each is proven against its own ground before it ships: a single accent that passes AA on both light and dark paper is arithmetically impossible.

Heading repairs

1 repair applied to the front matter so the document has one h1 and no skipped levels:

Shifted “10 headings” from h1 to h2 so the skill title is the only h1.

Spec compliance

4 editorial notes across 3 of 54 skills. They are printed in the margin of each skill rather than as errors here.

Images

Images inside a skill come from the upstream repository. Where the author gave no alternative text we mark the image decorative rather than inventing a description — a plausible caption we made up is worse than none for the reader who depends on it.

Signal

Install counts come from skills.sh. They measure downloads, not quality, and an unranked repository is not an unread one.

Agent surfaces

The whole issue is available as one markdown document at /github/gh-aw.md, and each skill at its own .md URL.

Publication

Set by Skills Docs from the source repository. Body text is Literata at the reader’s chosen size and measure; code is Geist Mono. Nothing on this page was written by us except this paragraph.

Contents