Copilot Agent Files support for Agentic Workflows

“Custom Agents” are added prompts that can be used with Copilot, Copilot CLI and VSCode Agent Mode to provide specialized behavior for specific tasks.

In this guide, we show you how to install and use the custom agent agentic-workflows to create, update, import, and debug agentic workflows in your repository.

Installing the Copilot Agent Files for Agentic Workflows

Follow these steps to set up your repository for agentic workflows using the custom agentic-workflows agent.

Start your coding agent.
- Navigate to your repository on https://github.com and click the “Agents” tab, or
- Start VSCode Agent Mode, or
- Start your coding agent in your repository

Install the Copilot Agent Files for Agentic Workflows into your repository.

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

Alternatively just run

gh aw init

After initialization, you’ll have .github/agents/agentic-workflows.agent.md, a Copilot agent file that registers the /agent agentic-workflows command in Copilot Chat.

Using the Copilot Agent Files for Agentic Workflows

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:

Creating New Agentic Workflows

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 generate a workflow file in .github/workflows/, write the frontmatter and prompt, configure tools and permissions, and compile to .lock.yml.

Updating Existing Workflows

Modify or improve existing workflows using natural language prompts:

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

Upgrading Agentic Workflows

Keep workflows up-to-date with the latest gh-aw versions and features:

/agent agentic-workflows upgrade all workflows to latest version

Importing Workflows

Import workflows from any accessible GitHub repository:

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

When importing, you can specify customizations such as engine or tools:

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

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?

For the fastest diagnosis, pass the full run URL from the GitHub Actions page:

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

The agent audits logs, identifies the root cause, and suggests targeted fixes. It handles permission errors, missing tools, network access issues, and safe-output problems — just describe the issue in natural language.

Self-Contained Debugging (Without Copilot)

If your repository is not yet set up with the agentic-workflows agent, or if you prefer to use a different AI assistant, use the standalone debugging prompt by sharing its URL:

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

The debug.md file is a self-contained prompt that works with any coding agent or AI assistant. It guides the agent to install gh aw, analyze the run logs, identify the root cause, and open a pull request with the fix.

Creating Agentic Workflows with an AI Chatbot

If you prefer to use an AI chatbot to author agentic workflows, use the agentic-chat instructions with any conversational AI application.

Copy the instructions into your AI chat interface, describe your workflow goal, and the assistant will generate a structured task description you can use in your workflow. It focuses on clear, actionable specifications rather than implementation details.

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 corrects terminology (e.g., “ghaw” → “gh-aw”), removes filler words, and transforms dictated sentences into clear, imperative task descriptions. Load it into your AI assistant before or after dictating to improve accuracy.