[docs] docs: reduce bloat in Copilot Agent Files reference page#24223
[docs] docs: reduce bloat in Copilot Agent Files reference page#24223
Conversation
Remove redundant debugging examples, collapsed TIP callout that repeated the URL format, and vague "Other Agents and Chats" section. Condense the post-init description and import customization examples. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
github-actions
bot
added
automation
documentation
There was a problem hiding this comment.
Pull request overview
Reduces verbosity on the “Copilot Agent Files support for Agentic Workflows” reference page while keeping the core setup, import, and debugging guidance.
Changes:
- Removes redundant explanatory bullets around initialization and debugging examples.
- Consolidates debugging guidance into a single recommended “run URL” approach.
- Trims duplicate import-customization examples and removes the “Other Agents and Chats” section.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| 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. |
There was a problem hiding this comment.
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).
| 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. |
| 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 | ||
| ``` |
There was a problem hiding this comment.
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.
| 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. |
There was a problem hiding this comment.
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.
Reduces
docs/src/content/docs/reference/custom-agent-for-aw.mdxfrom 167 → 125 lines (25.1% reduction) without losing any essential information.What was removed
debug <description>pattern; replaced with one sentence listing the scenario typesWhat was preserved
All links, code examples (with one duplicate removed), technical accuracy, and the
CopyEntireFileButtoncomponents are intact.Screenshots
Visual screenshots were unavailable due to Playwright network isolation in this workflow configuration. The page was verified to serve HTTP 200 via curl during the preview server check.
Blocked Domains
No domain blocking was observed (screenshot capture was skipped).
References: §23932600793