Agentic Authoring

Using our authoring agent is an effective way to create, debug, optimize your agentic workflows. This is a continuation of the Create Agentic Workflows page.

Configuring Your Repository

In order to enable the agentic authoring experience, you will need to configure your repository with a few files. Run this prompt or the init command.

Initialize this repository for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/install.md

or

gh aw init

Make sure to commit and push the files to your repository.

Using the GitHub Web Interface

If you have access to GitHub Copilot, you can create and edit Agentic Workflows directly from the web interface. While non-interactive, it’s useful for quickly turning an idea into a working workflow. For a more interactive experience, use a coding agent (see below).

Create an agentic workflow from the GitHub web interface

Tip

On the first run in a new repository, the workflow will surely fail because the secrets are not configured. The agentic workflow should detect the missing tokens and create an issue with instructions on how to configure them.

Remixing Workflows Between Repositories

When you need to adapt an existing workflow from another repository, use the create-agentic-agent to perform AI-assisted migration. The agent analyzes the source workflow, identifies dependencies, adapts configuration for your repository, and validates the result. This is useful for forking workflows as starting points or one-time migrations requiring substantial changes. For synchronized updates across repositories, use Reusing Workflows with gh aw add instead.

Example prompt for migration:

Migrate the release.md workflow from github/gh-aw to this repository.
Adapt permissions and repository-specific references for our structure.

Debugging Workflows

Use the agentic workflows agent to diagnose and fix failing workflow runs.

Through Copilot

If your repository is configured for agentic authoring, use the agentic-workflows agent in Copilot Chat:

/agent agentic-workflows debug https://github.com/OWNER/REPO/actions/runs/RUN_ID

The agent audits the run, identifies the root cause (missing tools, permission errors, network blocks), and suggests targeted fixes.

Tip

Copy this prompt, replace OWNER, REPO, and RUN_ID with your values, and paste it into Copilot Chat. You can find the run URL on the GitHub Actions run page.

Self-Contained (with URL)

For any AI assistant or coding agent, share the URL to the standalone debugging prompt:

Debug this workflow run using https://raw.githubusercontent.com/github/gh-aw/main/debug.md

The failed workflow run is at https://github.com/OWNER/REPO/actions/runs/RUN_ID

Copy debug instructions

The debug.md file is a self-contained prompt. The agent fetches it and follows the instructions to install the gh aw CLI, analyze logs, apply fixes, and open a pull request with the changes.

Advanced Techniques

Planner

If you prefer to use an AI chatbot to author agentic workflows, use the agentic-chat instructions with any conversational AI to create clear, actionable task descriptions. Copy agentic-chat instructions

Copy the instructions, paste into your AI chat, then describe your workflow goal. The assistant asks clarifying questions and generates a structured task description (wrapped in 5 backticks) ready to use in your workflow. It focuses on what needs to be done rather than how, making it ideal for creating specifications that coding agents can execute.

Dictation

When creating agentic workflows using speech-to-text, use the dictation instructions prompt to correct terminology mismatches and formatting issues. Copy dictation instructions

This prompt corrects terminology (e.g., “ghaw” → “gh-aw”, “work flow” → “workflow”), transforms casual speech into imperative task descriptions, removes filler words, and adds implicit context. Load it into your AI assistant before or after dictating.