Skip to content

[docs] docs: reduce bloat in Copilot Agent Files reference page #24223

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 1 commit into from
Apr 3, 2026
+5 −47
Merged

[docs] docs: reduce bloat in Copilot Agent Files reference page #24223

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 5 additions & 47 deletions docs/src/content/docs/reference/custom-agent-for-aw.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,20 +27,13 @@ Follow these steps to set up your repository for agentic workflows using the cus
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

```bash
gh aw init
```

After initialization, you'll have:
- `.github/agents/agentic-workflows.agent.md` - [A Copilot file](/gh-aw/reference/glossary/#agent-files) (custom AI instructions) for the `/agent agentic-workflows` command in Copilot Chat
- Additional configuration files for workflow authoring
After initialization, you'll have `.github/agents/agentic-workflows.agent.md`, a [Copilot agent file](/gh-aw/reference/glossary/#agent-files) that registers the `/agent agentic-workflows` command in Copilot Chat.
Copy link

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The phrasing "registers the /agent agentic-workflows command" is a bit inaccurate/ambiguous relative to the glossary definition of Agent Files (they define an agent invoked via the /agent command). Consider rewording to something like "registers the agentic-workflows agent for use with /agent in Copilot Chat" to match the terminology used elsewhere (see docs/src/content/docs/reference/glossary.md:332-335).

Suggested change
After initialization, you'll have `.github/agents/agentic-workflows.agent.md`, a [Copilot agent file](/gh-aw/reference/glossary/#agent-files) that registers the `/agent agentic-workflows` command in Copilot Chat.
After initialization, you'll have `.github/agents/agentic-workflows.agent.md`, a [Copilot agent file](/gh-aw/reference/glossary/#agent-files) that registers the `agentic-workflows` agent for use with `/agent` in Copilot Chat.

Copilot uses AI. Check for mistakes.

## Using the Copilot Agent Files for Agentic Workflows

Expand Down Expand Up @@ -82,14 +75,10 @@ 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:
When importing, you can specify customizations such as engine or tools:

```text wrap
# 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
```
Comment on lines +78 to 82
Copy link

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence mentions customizing imports with "engine or tools", but the only example shown is for changing the engine. Either adjust the sentence to match the single example, or add a second short example demonstrating tool customization so readers can infer the syntax.

Copilot uses AI. Check for mistakes.

### Debugging Agentic Workflows
Expand All @@ -100,40 +89,13 @@ When workflows fail or behave unexpectedly, use the agentic-workflows agent to i
/agent agentic-workflows debug why is my issue-triage workflow failing?
```

You can investigate a specific workflow run using its ID or URL:
For the fastest diagnosis, pass the full run URL from the GitHub Actions page:

```text wrap
# 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
/agent agentic-workflows debug https://github.com/OWNER/REPO/actions/runs/RUN_ID
```

> [!TIP]
> For the fastest diagnosis, give the agent the full run URL from the GitHub Actions page:
>
> ```text wrap
> /agent agentic-workflows debug https://github.com/OWNER/REPO/actions/runs/RUN_ID
> ```
>
> Replace `OWNER`, `REPO`, and `RUN_ID` with your values. The agent will audit logs, identify the root cause, and suggest targeted fixes.

The agent can help with various debugging scenarios:

```text wrap
# 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
```
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.
Comment on lines +92 to +98
Copy link

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The example uses placeholder values (OWNER, REPO, RUN_ID) but no longer tells readers to replace them. Other docs that use the same placeholder URL explicitly instruct replacement (e.g., docs/src/content/docs/guides/agentic-authoring.mdx:66-68, docs/src/content/docs/troubleshooting/common-issues.md:539-540). Consider adding a short sentence after the code block to keep this page self-contained.

Copilot uses AI. Check for mistakes.

### Self-Contained Debugging (Without Copilot)

Expand All @@ -149,10 +111,6 @@ 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.

## 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](https://raw.githubusercontent.com/github/gh-aw/main/.github/aw/agentic-chat.md) with any conversational AI application. <CopyEntireFileButton filePath="https://raw.githubusercontent.com/github/gh-aw/main/.github/aw/agentic-chat.md" label="Copy agentic-chat instructions" />
Expand Down
Loading