Automate unstructured repo work with GitHub Agentic Workflows
Install gh aw, initialise the repo, have a coding agent write a Markdown workflow, compile it to lock.yml, commit both, and put a drift check in CI so you never ship Markdown without its compiled Actions file.
Tools used
- GitHub Agentic WorkflowsMarkdown workflows that compile to Actions and run a coding agent
- gh aw CLIInit, compile and run agentic workflows
- GitHub Copilot CLIDefault engine Fränkel used to author the Markdown workflow
Step navigator
A Markdown agentic workflow plus its compiled .lock.yml in .github/workflows/, running on Actions with safe-outputs, and a CI check that fails if the lock file drifts.
Teams with GitHub Actions enabled who need an agent for semi-structured repo work (release notes, triage, docs) that deterministic scripts cannot parse.
Before you start
GitHub Agentic Workflows went generally available on 28 October 2026. Nicolas Fränkel (long-time HN account) used them earlier in 2026 to parse unstructured release notes for deprecations that no regex could catch, then reused the same lessons to keep README, wiki, Copilot instructions and changelog in sync. This guide sticks to his write-up and the official docs. Gaps he left (the exact release-notes prompt, the full CI YAML) are left as gaps.
Step-by-step instructions
Install the gh aw extension and initialise the repo
Fränkel's kickoff: install the gh aw extension, then run gh aw init (or use the GitHub GUI). Official docs say gh aw init adds skills and instructions so a coding agent can create and edit workflows more effectively.
gh extension install github/gh-aw && gh aw init
Why this works
Without the skills from init, the coding agent has no project-local guidance for this format.
Ask a coding agent to create the Markdown workflow with the agentic-workflows skill
Fränkel used Copilot CLI for "development proper." The docs recommend starting your coding agent in the repo and prompting with the agentic-workflows skill, for example a PR reviewer or a daily activity report. The agent creates a Markdown file under .github/workflows/ with YAML frontmatter (on, permissions, safe-outputs, engine) and a natural-language body.
/agentic-workflows Create a workflow that reviews each pull request and checks that the changes include enough tests.
Compile the Markdown to .lock.yml before you push
Fränkel's first hard lesson: "GitHub doesn't execute the Markdown workflow, but the YAML one." He once pushed only the Markdown and saw no change. Compile with gh aw compile (or gh aw compile my-workflow). Commit both files. Docs say the same: commit the .md and the compiled .lock.yml.
gh aw compile --validate --strict
Why this works
Actions only sees the compiled YAML; Markdown alone is a silent no-op.
Add the engine token the workflow expects
Fränkel: the compiled workflow looks for GITHUB_COPILOT_TOKEN, a fine-grained token with at least Copilot requests permission. Docs add that each engine (Copilot, Claude, Codex, Gemini) needs its own authentication secret in the repository, and Copilot is the default when engine is omitted.
Check lock-file drift in CI; do not let a workflow rewrite other workflows
Fränkel first tried a workflow that recompiled agentic workflows on change and hit permission issues. He decided that was a bad idea: "if an attacker manages to control a workflow, they can do whatever the workflow's permissions allow." His next best thing: a CI job that compiles under the same conditions and fails if the result differs from the committed lock files. On Windows vs Ubuntu he also needed a proper .gitattributes file for line endings.
Why this works
A failing drift check catches a forgotten compile without giving the pipeline write access to workflow files.
Pick a use case deterministic scripts cannot handle
Fränkel's winning case was upgrade-impact config files: some deprecations lived in code (@Deprecated, custom annotations), but plugin deprecations lived only in unstructured release notes. "I can't use standard deterministic automations. Release notes don't have a regular structure." After that worked, he got continuous documentation working too: every relevant change opens a PR updating README, wiki, Copilot instructions.md and the changelog. He did not publish the exact system prompt for the release-notes job beyond GitHub's sandbox policy block.
Why this works
Agents earn their keep on semi-structured text; keep regex for the structured half.
End of guide · Reviewed Oct 29, 2026
Pro tips2
- Commit both the .md and the .lock.yml; Actions runs the YAML, not the Markdown.
- Keep write operations behind safe-outputs such as create-issue or create-pull-request.
Common mistakes2
- Pushing only the Markdown and wondering why nothing runs.
- Letting a workflow rewrite other workflows automatically; Fränkel hit permission walls and later called that a bad idea for security.
FAQ2
Do I need Copilot?
Can I use Marketplace actions inside an agentic workflow?
Related field guides.
Grow a shared CLAUDE.md from every PR mistake
Check one CLAUDE.md into git, add a rule whenever Claude repeats a mistake, tag @claude on review to capture learnings, start in Plan mode, and give Claude a way to verify its own work.
Reduce attack surface with Claude before you chase individual CVEs
Have Claude inventory what code is reachable by default, before authentication, and under conflicting config options, then gate or feature-flag what you do not need, and prove the change with the project tests.
Ship AI-written code you can still explain: own the design, make the agent show its assumptions
Decide the abstractions yourself, pin them in a sketch or diagram, have the agent describe every change and flag what it assumed, then ask it to explain the diff before you commit.
Keep a Claude Code session running on a remote box and steer it from your phone
Run Claude Code inside tmux on a server, use mosh for flaky links, connect Remote Control so you can steer and approve from your phone, and keep your SSH keys out of the agent's reach.
Run parallel Claude Code agents in git worktrees without merge hell
Give each agent its own worktree, scope tasks so their files do not overlap, merge one stream at a time, and rebase the rest on the new main.
Make a coding agent write the failing tests first, then implement
Split the work into separate prompts: tests only, confirm they fail for the right reason, commit, then implement without touching the tests.
Set up Claude Code hooks for formatting, tests and protected files
Add PostToolUse hooks that format and test after edits, a PreToolUse hook that blocks protected files, and a notification for long runs.
Turn a checklist you keep forgetting into a Claude Code skill
When you catch yourself re-typing the same multi-step instructions, put them in .claude/skills/<name>/SKILL.md and run them with a slash command.