Authoring Workflows with AI

You can author new agentic workflows using AI under your guidance.

In this guide, we show you how to create agentic workflows in the GitHub web interface (github.com), your coding agent, or in VS Code chat.

Creating Agentic Workflows using VSCode or a Coding Agent

To create agentic workflows using VSCode or a Coding Agent (Claude Code, Codex etc.), follow these steps

Start VSCode or your Coding Agent in your repository

Open VSCode Agent Chat or your Coding Agent and enter the following prompt:

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

Then follow the instructions in .github/agents/agentic-workflows.agent.md to create a workflow.

The purpose of the workflow is to triage issues.

You can replace the last line with your desired workflow purpose and as much additional detail, context, goals, guardrails and purpose as you like.

If you haven’t done so already, set up your repository secrets for the coding agent your workflow use (Copilot, Claude, Codex). Also adjust the engine: setting in your generated workflow to match if not using Copilot CLI.

Creating Agentic Workflows on github.com

Follow these steps to create agentic workflows on github.com.

Step 1 - Prepare Your Repository

Navigate to your repository on https://github.com and click the “Agents” tab, then use this prompt:

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

This will guide the Copilot agent to:

Install the gh-aw CLI extension
Run gh aw init to create necessary configuration files
Commit and push the changes, or create a pull request

After initialization, you’ll have:

.github/agents/agentic-workflows.agent.md - A Copilot file (custom AI instructions) for the /agent agentic-workflows command in Copilot Chat
Additional configuration files for workflow authoring

Step 2 - Create an agentic workflow

Navigate to your repository on https://github.com and click the “Agents” tab, then use this prompt:

# Create a new workflow
/agent agentic-workflows create a workflow that triages issues

The agent will understand your intent and route to the appropriate specialized prompt for your task.

Step 3 - Setup required secrets

If you haven’t done so already, set up your repository secrets for the coding agent your workflow will be using (Copilot, Claude, Codex). Also need to adjust the engine: setting in your generated workflow to match if not using Copilot CLI.

Going Further

Once your repository is set up for agentic workflows, you can use the agentic-workflows agent from VSCode or GitHub.com to perform a variety of tasks:

Updating Existing Workflows

Modify or improve existing workflows using natural language prompts. The agentic-workflows agent can analyze your current workflow and suggest or implement changes:

/agent agentic-workflows update the issue-triage workflow to add web-fetch tool and
  improve the prompt for better accuracy

The agent will:

Load the existing workflow file
Analyze the current configuration and prompt
Apply requested changes to tools, prompts, triggers, or permissions
Recompile the workflow to .lock.yml

Upgrading Agentic Workflows

Keep your agentic workflows up-to-date with the latest gh-aw versions and features using the unified agentic-workflows agent:

/agent agentic-workflows upgrade all workflows to latest version

The agent will:

Detect all workflows in your repository
Check for available updates to gh-aw version
Update deprecated frontmatter configurations
Fix compatibility issues with new features
Recompile workflows after changes
Generate a summary of upgraded workflows

Importing Workflows

Import existing workflows from GitHub repositories using natural language prompts. The agentic-workflows agent can fetch, install, and configure workflows from any accessible GitHub repository:

/agent agentic-workflows import workflow from https://github.com/githubnext/agentics/blob/main/workflows/ci-doctor.md

The agent will:

Fetch the workflow file from the GitHub URL
Install it in your .github/workflows/ directory
Update frontmatter with source tracking
Configure necessary secrets and permissions
Compile the workflow to .lock.yml
Commit and push changes

When importing, you can specify customizations:

# Import and change engine
/agent agentic-workflows import issue-triage from githubnext/agentics and use claude engine

# Import and add tools
/agent agentic-workflows import pr-review from owner/repo and add web-fetch tool

Debugging Agentic Workflows

When workflows fail or behave unexpectedly, use the agentic-workflows agent to investigate and diagnose issues:

/agent agentic-workflows debug why is my issue-triage workflow failing?

The debugging agent will:

Download and analyze workflow run logs
Identify errors and warnings
Check tool and permission configurations
Review MCP server connectivity
Examine safe-input and safe-output configurations
Suggest specific fixes for identified issues

You can investigate a specific workflow run using its ID or URL:

# Debug by run ID
/agent agentic-workflows debug run 1234567890

# Debug from GitHub Actions URL
/agent agentic-workflows debug https://github.com/owner/repo/actions/runs/1234567890

The agent can help with various debugging scenarios:

# Permission errors
/agent agentic-workflows debug getting 403 errors in my workflow

# Missing tools
/agent agentic-workflows debug workflow says tool not found

# Network access issues
/agent agentic-workflows debug workflow cannot access external API

# Safe-output problems
/agent agentic-workflows debug agent output not creating issues

Other Agents and Chats

The agent file can be loaded into other AI chat interfaces that support custom instructions. The agent is designed to be compatible with various AI tools, although some features might require configuration and you’ll need to allow running the compiler.

Creating Agentic Workflows with ChatGPT

If you prefer to use ChatGPT to author agentic workflow, you can use the agentic-chat instructions with ChatGPT or other conversational AI applications to create clear, actionable task descriptions. Use the button below to copy the full instructions: .

The agentic-chat assistant helps you:

Break down complex problems into clear, actionable phases
Structure task descriptions for AI coding agents
Write specifications without implementation details
Follow best practices for agentic workflow task descriptions

To use the agentic-chat instructions:

Copy the full instructions using the button above
Paste them into your ChatGPT or other AI chat interface
Describe your workflow goal or problem
The assistant will ask clarifying questions and generate a structured task description
Copy the generated task description (wrapped in 5 backticks) and use it in your workflow

The assistant uses a neutral, technical tone and focuses on what needs to be done rather than how to implement it, making it ideal for creating specifications that AI coding agents can execute.

Dictating Agentic Workflows

When creating agentic workflows using speech-to-text (dictation), you may encounter terminology mismatches and formatting issues common to voice recognition systems. To help correct these issues, use the dictation instructions prompt or .

This prompt helps rephrase text captured through speech-to-text recognition by:

Correcting project-specific terminology (e.g., “ghaw” → “gh-aw”, “work flow” → “workflow”)
Transforming casual dictated sentences into clear, imperative task descriptions
Removing filler words and improving technical tone
Adding necessary context that might be implicit in spoken requests

Load the dictation prompt into your AI assistant before or after dictating your workflow instructions to improve accuracy and clarity.