docs: add self-contained and Copilot debugging prompts to authoring guides and debug.md

[Copilot]

Debugging docs lacked copy-paste prompts showing users how to invoke the agentic workflows agent to diagnose a failing run. Two approaches are now documented in the authoring guide, the agent reference, and the root-level debug.md template.

Changes

• guides/agentic-authoring.mdx — New "Debugging Workflows" section with two sub-sections:

  • Through Copilot — /agent agentic-workflows debug <URL> for repos with the agent installed
  • Self-Contained (with URL) — uses debug.md raw URL, works with any AI assistant; includes a CopyEntireFileButton

• reference/custom-agent-for-aw.mdx — New "Self-Contained Debugging (Without Copilot)" sub-section added after existing Copilot examples, covering repos not yet set up with the agent

• debug.md — New "How to Use This Prompt" section at the top presenting both approaches side by side before the step-by-step instructions:

  • Option A (Copilot): /agent agentic-workflows debug <URL>
  • Option B (self-contained): share the raw debug.md URL with any AI assistant

Self-contained prompt template

Debug this workflow run using https://raw.githubusercontent.com/github/gh-aw/main/debug.md

Run URL: https://github.com/OWNER/REPO/actions/runs/RUN_ID

Follows the same URL-based pattern already used for repository initialization (install.md).

Original prompt

Update debugging docs with prompt to use the agentic workflows agent to diagnose a run (prompt used in template).

Provide both the self contained version (with url) or through copilot.

Custom agent used: technical-doc-writer
AI technical documentation writer for GitHub Actions library using GitHub Docs voice

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[pelikhan]

@copilot update debug page as well

[Copilot]

@copilot update debug page as well

Done in b8e7443. Added a "How to Use This Prompt" section at the top of debug.md with both approaches side by side:

• Option A (Copilot): /agent agentic-workflows debug <URL>
• Option B (self-contained): share the raw debug.md URL with any AI assistant

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: /opt/hostedtoolcache/node/24.14.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build tion instructio (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[Copilot]

Pull request overview

Updates the documentation to provide copy-pasteable prompts for debugging failing GitHub Actions runs via the agentic-workflows agent (Copilot) or a self-contained debug.md URL that works with other assistants.

Changes:

• Adds a “Debugging Workflows” section to the authoring guide with Copilot and self-contained invocation options.
• Adds a “Self-Contained Debugging (Without Copilot)” section to the custom agent reference, including a copy button for debug.md.
• Enhances the root debug.md template with a new “How to Use This Prompt” section showing both invocation approaches.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
docs/src/content/docs/reference/custom-agent-for-aw.mdx	Documents a self-contained debugging prompt (URL-based) alongside existing Copilot examples.
docs/src/content/docs/guides/agentic-authoring.mdx	Adds a dedicated debugging section with both Copilot and self-contained flows plus a copy button.
debug.md	Adds top-level usage guidance presenting both Copilot and self-contained invocation options.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

In debug.md, the new “How to Use This Prompt” section is written as end-user instructions, but the file itself is explicitly addressed to “you, a coding agent”. Option A (“Through Copilot”) doesn’t actually use this prompt and may distract/confuse agents consuming the file via the self-contained flow. Consider rewording this section to clearly separate human invocation options from the agent instructions (e.g., rename to “How to Debug a Run”, and/or add a one-line directive like “If you are an AI reading this file as the prompt, skip to Step 1”).