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

This will guide your coding 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

Alternatively just run

gh aw init

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

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:

# 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?

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 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.