From 44b757a5e0a58cf4672a7f1935f876ecd73e462e Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 13 Jun 2026 11:45:59 +0000
Subject: [PATCH 1/4] feat: add optimize token consumption section to agent
 failure issues for guardrail failures

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 .github/aw/optimize-agentic-workflow.md       | 110 ++++++++++++++
 .github/skills/agentic-workflows/SKILL.md     |   1 +
 actions/setup/js/handle_agent_failure.cjs     |  39 +++++
 .../setup/js/handle_agent_failure.test.cjs    | 102 +++++++++++++
 actions/setup/md/agent_failure_issue.md       |   2 +-
 .../md/optimize_token_consumption_context.md  |  13 ++
 optimize.md                                   | 134 ++++++++++++++++++
 .../agentic_workflows_fallback_aw_files.json  |   1 +
 8 files changed, 401 insertions(+), 1 deletion(-)
 create mode 100644 .github/aw/optimize-agentic-workflow.md
 create mode 100644 actions/setup/md/optimize_token_consumption_context.md
 create mode 100644 optimize.md

diff --git a/.github/aw/optimize-agentic-workflow.md b/.github/aw/optimize-agentic-workflow.md
new file mode 100644
index 00000000000..0e557baabc1
--- /dev/null
+++ b/.github/aw/optimize-agentic-workflow.md
@@ -0,0 +1,110 @@
+---
+description: Analyze and reduce token consumption in agentic workflows — audit-based measurement, DataOps, gh-proxy, sub-agents, and prompt optimization.
+disable-model-invocation: true
+---
+
+# Agentic Workflow Token Optimizer
+
+Help users reduce the AI token usage and cost of GitHub Agentic Workflows in this repository.
+
+## Load These References First
+
+- [github-agentic-workflows.md](github-agentic-workflows.md)
+- [token-optimization.md](token-optimization.md)
+- [workflow-editing.md](workflow-editing.md)
+- [syntax.md](syntax.md)
+
+Load these only when relevant:
+
+- [experiments.md](experiments.md)
+- [safe-outputs.md](safe-outputs.md)
+
+## Available Commands
+
+```bash
+gh aw audit <run-id> --json
+gh aw audit <base-run-id> <optimized-run-id>
+gh aw logs <workflow-name> --json
+gh aw compile <workflow-name>
+gh aw status
+```
+
+## Start the Conversation
+
+Ask for one of these inputs:
+
+- a workflow run URL (or run ID) to analyze
+- a workflow name to review the source
+- the guardrail that was exceeded (max-ai-credits, max-daily-ai-credits, max-tool-denials, max-turns / timeout)
+
+## Fast Path: Run URL Provided
+
+If the user gives a GitHub Actions run URL:
+
+1. Extract the run ID
+2. Run `gh aw audit <run-id> --json`
+3. Inspect `agent_usage.aic`, `agent_usage.input_tokens`, `agent_usage.output_tokens`, `agent_usage.cache_read_tokens`
+4. Identify the most expensive phases before asking additional questions
+
+## Guardrail-Specific Entry Points
+
+### `max-ai-credits` exceeded
+
+The workflow was stopped because it consumed more AI Credits than the configured per-run budget.
+
+Priority checks:
+1. Which tool calls dominated token usage? (`token-usage.jsonl`)
+2. Is the prompt front-loading large payloads that could be fetched on demand?
+3. Are there repetitive extraction steps that sub-agents could handle cheaply?
+4. Does the frontier model handle tasks that a small model could do?
+
+### `max-daily-ai-credits` exceeded
+
+The workflow is being blocked because its 24-hour AI Credits budget is exhausted.
+
+Priority checks:
+1. What is the run cadence? (scheduled too frequently?)
+2. Does the workflow use cheap triage before escalating to the frontier model?
+3. Is batching or caching applicable to reduce run frequency?
+4. Are there noop early-exits for events that do not require agent action?
+
+### `max-tool-denials` exceeded
+
+The Copilot SDK hit the tool-denial threshold, indicating the prompt attempted actions outside the allowed tool policy.
+
+Priority checks:
+1. What tool was repeatedly denied? (last denied reason in the failure issue)
+2. Is the tool missing from the workflow's permissions/firewall config?
+3. Can the prompt be revised to avoid the denied operation entirely?
+4. Would a DataOps pre-step satisfy the data need without a tool call?
+
+### Timeout / `max-turns` exceeded
+
+The agent ran out of time or turns before completing the task.
+
+Priority checks:
+1. Is the task decomposable into smaller, faster sub-tasks?
+2. Are there long-running tool calls that could be replaced with DataOps pre-steps?
+3. Is the prompt asking the agent to do too much in one run?
+4. Can `max-turns` or `timeout-minutes` be raised, or should the task be split?
+
+## Optimization Analysis Plan
+
+After measuring token usage, produce a prioritized plan:
+
+1. **Measure** — run `gh aw audit <run-id>` and summarize AI Credits and per-call token breakdown
+2. **Identify top cost drivers** — list the three most expensive phases/tool calls
+3. **Apply quick wins first** — DataOps pre-steps, `gh-proxy`, `cli-proxy`, prompt trimming
+4. **Sub-agent delegation** — identify repetitive per-item loops suitable for small-model workers
+5. **Prompt caching** — verify stable context appears before dynamic content
+6. **Experiment** — add an `experiments:` entry with `metric: "aic"` to measure the change
+7. **Validate quality** — confirm the optimized run produces equivalent safe outputs
+
+Present the plan clearly before making any edits. Confirm with the user before applying changes.
+
+## Editing Workflow
+
+1. Edit `.github/workflows/<workflow-name>.md`
+2. Recompile: `gh aw compile <workflow-name>`
+3. Commit both the source and the generated `.lock.yml`
+4. Report the estimated savings and link to the PR or commit
diff --git a/.github/skills/agentic-workflows/SKILL.md b/.github/skills/agentic-workflows/SKILL.md
index b4505045ca5..ee714d339d8 100644
--- a/.github/skills/agentic-workflows/SKILL.md
+++ b/.github/skills/agentic-workflows/SKILL.md
@@ -32,6 +32,7 @@ Load these files from `github/gh-aw` (they are not available locally).
 - `.github/aw/memory.md`
 - `.github/aw/messages.md`
 - `.github/aw/network.md`
+- `.github/aw/optimize-agentic-workflow.md`
 - `.github/aw/patterns.md`
 - `.github/aw/pr-reviewer.md`
 - `.github/aw/report.md`
diff --git a/actions/setup/js/handle_agent_failure.cjs b/actions/setup/js/handle_agent_failure.cjs
index 6728a5012ec..b0aa6e10236 100644
--- a/actions/setup/js/handle_agent_failure.cjs
+++ b/actions/setup/js/handle_agent_failure.cjs
@@ -1665,6 +1665,40 @@ function buildDailyAICExceededContext(hasDailyAICExceeded, totalAIC, threshold)
   );
 }
 
+/**
+ * Build the "Optimize token consumption" details section for the failure issue when a guardrail
+ * limit was the root cause of the failure.
+ *
+ * Guardrails that trigger this section:
+ *   - max-ai-credits:       per-run AI Credits budget exceeded
+ *   - max-daily-ai-credits: 24-hour per-workflow AI Credits quota exhausted
+ *   - max-tool-denials:     Copilot SDK tool-denial threshold hit
+ *   - max-turns / timeout:  agent ran out of turns or wall-clock time
+ *
+ * @param {object} options
+ * @param {boolean} options.maxAICreditsExceeded       - max-ai-credits guardrail triggered
+ * @param {boolean} options.hasDailyAICExceeded        - max-daily-ai-credits guardrail triggered
+ * @param {boolean} options.hasToolDenialsExceeded     - max-tool-denials guardrail triggered
+ * @param {boolean} options.isTimedOut                 - timeout / max-turns guardrail triggered
+ * @param {string}  options.runUrl                     - URL to the failed workflow run
+ * @returns {string} Rendered section or empty string when no guardrail was triggered
+ */
+function buildOptimizeTokenConsumptionContext({ maxAICreditsExceeded, hasDailyAICExceeded, hasToolDenialsExceeded, isTimedOut, runUrl }) {
+  const guardrailTriggered = maxAICreditsExceeded || hasDailyAICExceeded || hasToolDenialsExceeded || isTimedOut;
+  if (!guardrailTriggered) {
+    return "";
+  }
+
+  let guardrailName = "guardrail limit";
+  if (maxAICreditsExceeded) guardrailName = "max-ai-credits";
+  else if (hasDailyAICExceeded) guardrailName = "max-daily-ai-credits";
+  else if (hasToolDenialsExceeded) guardrailName = "max-tool-denials";
+  else if (isTimedOut) guardrailName = "max-turns / timeout";
+
+  const templatePath = getPromptPath("optimize_token_consumption_context.md");
+  return renderTemplateFromFile(templatePath, { guardrail_name: guardrailName, run_url: runUrl });
+}
+
 // Maps engine ID (GH_AW_ENGINE_ID) to credential name for use with GH_AW_ENGINE_API_HOSTS.
 const ENGINE_ID_TO_CREDENTIAL = /** @type {Record<string, string>} */ {
   copilot: "`COPILOT_GITHUB_TOKEN`",
@@ -3116,6 +3150,9 @@ async function main() {
         // Build credential auth error context (firewall audit.jsonl 401/403 from provider endpoints)
         const credentialAuthErrorContext = buildCredentialAuthErrorContext();
 
+        // Build optimize token consumption context (shown when a guardrail was the failure root cause)
+        const optimizeTokenConsumptionContext = buildOptimizeTokenConsumptionContext({ maxAICreditsExceeded, hasDailyAICExceeded, hasToolDenialsExceeded, isTimedOut, runUrl });
+
         // Create template context with sanitized workflow name
         const templateContext = {
           workflow_name: sanitizedWorkflowName,
@@ -3151,6 +3188,7 @@ async function main() {
           lockdown_check_failed_context: lockdownCheckFailedContext,
           stale_lock_file_failed_context: staleLockFileFailedContext,
           daily_ai_credits_exceeded_context: dailyAICExceededContext,
+          optimize_token_consumption_context: optimizeTokenConsumptionContext,
         };
 
         // Render the issue template
@@ -3234,6 +3272,7 @@ module.exports = {
   buildLockdownCheckFailedContext,
   buildStaleLockFileFailedContext,
   buildDailyAICExceededContext,
+  buildOptimizeTokenConsumptionContext,
   buildTimeoutContext,
   shouldBuildEngineFailureContext,
   isIssueWritePermissionError,
diff --git a/actions/setup/js/handle_agent_failure.test.cjs b/actions/setup/js/handle_agent_failure.test.cjs
index 3d6b990df88..39b97df42d5 100644
--- a/actions/setup/js/handle_agent_failure.test.cjs
+++ b/actions/setup/js/handle_agent_failure.test.cjs
@@ -123,6 +123,7 @@ describe("handle_agent_failure", () => {
       fs.writeFileSync(path.join(promptsDir, "agent_failure_issue.md"), "ISSUE TEMPLATE CONTENT");
       fs.writeFileSync(path.join(promptsDir, "daily_cap_rollup_issue.md"), "Daily cap rollup issue body cap={cap} window={window_hours}");
       fs.writeFileSync(path.join(promptsDir, "daily_cap_rollup_comment.md"), "Failure suppressed workflow={workflow_name} run={run_url} categories={summary} cap={cap} window={window_hours}h");
+      fs.writeFileSync(path.join(promptsDir, "optimize_token_consumption_context.md"), "OPTIMIZE CONTEXT guardrail={guardrail_name} run={run_url}");
 
       process.env.RUNNER_TEMP = tmpDir;
       process.env.GH_AW_WORKFLOW_NAME = "Test Workflow";
@@ -405,6 +406,7 @@ describe("handle_agent_failure", () => {
       fs.writeFileSync(path.join(promptsDir, "agent_failure_issue.md"), "ISSUE TEMPLATE CONTENT");
       fs.writeFileSync(path.join(promptsDir, "daily_cap_rollup_issue.md"), "Daily cap rollup issue body cap={cap} window={window_hours}");
       fs.writeFileSync(path.join(promptsDir, "daily_cap_rollup_comment.md"), "Failure suppressed workflow={workflow_name} run={run_url} categories={summary} cap={cap} window={window_hours}h");
+      fs.writeFileSync(path.join(promptsDir, "optimize_token_consumption_context.md"), "OPTIMIZE CONTEXT guardrail={guardrail_name} run={run_url}");
 
       process.env.RUNNER_TEMP = tmpDir;
       process.env.GH_AW_WORKFLOW_NAME = "Test Workflow";
@@ -1151,6 +1153,7 @@ describe("handle_agent_failure", () => {
       fs.writeFileSync(path.join(promptsDir, "agent_failure_issue.md"), "ISSUE TEMPLATE CONTENT");
       fs.writeFileSync(path.join(promptsDir, "daily_cap_rollup_issue.md"), "Daily cap rollup issue body cap={cap} window={window_hours}");
       fs.writeFileSync(path.join(promptsDir, "daily_cap_rollup_comment.md"), "Failure suppressed workflow={workflow_name} run={run_url} categories={summary} cap={cap} window={window_hours}h");
+      fs.writeFileSync(path.join(promptsDir, "optimize_token_consumption_context.md"), "OPTIMIZE CONTEXT guardrail={guardrail_name} run={run_url}");
 
       process.env.RUNNER_TEMP = tmpDir;
       process.env.GH_AW_WORKFLOW_NAME = "Test Workflow";
@@ -1801,6 +1804,105 @@ describe("handle_agent_failure", () => {
     });
   });
 
+  // ──────────────────────────────────────────────────────
+  // buildOptimizeTokenConsumptionContext
+  // ──────────────────────────────────────────────────────
+
+  describe("buildOptimizeTokenConsumptionContext", () => {
+    let buildOptimizeTokenConsumptionContext;
+    const fs = require("fs");
+    const path = require("path");
+    const templateContent = fs.readFileSync(path.join(__dirname, "../md/optimize_token_consumption_context.md"), "utf8");
+    const originalReadFileSync = fs.readFileSync.bind(fs);
+
+    beforeEach(() => {
+      vi.resetModules();
+      process.env.RUNNER_TEMP = "/nonexistent";
+      // Stub readFileSync so the runtime path resolves to the source-tree template
+      fs.readFileSync = (filePath, encoding) => {
+        if (typeof filePath === "string" && filePath.includes("optimize_token_consumption_context.md")) {
+          return templateContent;
+        }
+        return originalReadFileSync(filePath, encoding);
+      };
+      ({ buildOptimizeTokenConsumptionContext } = require("./handle_agent_failure.cjs"));
+    });
+
+    afterEach(() => {
+      fs.readFileSync = originalReadFileSync;
+      delete process.env.RUNNER_TEMP;
+    });
+
+    it("returns empty string when no guardrail was triggered", () => {
+      const result = buildOptimizeTokenConsumptionContext({
+        maxAICreditsExceeded: false,
+        hasDailyAICExceeded: false,
+        hasToolDenialsExceeded: false,
+        isTimedOut: false,
+        runUrl: "https://github.com/owner/repo/actions/runs/123",
+      });
+      expect(result).toBe("");
+    });
+
+    it("returns optimize context when maxAICreditsExceeded is true", () => {
+      const result = buildOptimizeTokenConsumptionContext({
+        maxAICreditsExceeded: true,
+        hasDailyAICExceeded: false,
+        hasToolDenialsExceeded: false,
+        isTimedOut: false,
+        runUrl: "https://github.com/owner/repo/actions/runs/123",
+      });
+      expect(result).toContain("Optimize token consumption");
+      expect(result).toContain("max-ai-credits");
+      expect(result).toContain("https://github.com/owner/repo/actions/runs/123");
+      expect(result).toContain("optimize.md");
+    });
+
+    it("returns optimize context when hasDailyAICExceeded is true", () => {
+      const result = buildOptimizeTokenConsumptionContext({
+        maxAICreditsExceeded: false,
+        hasDailyAICExceeded: true,
+        hasToolDenialsExceeded: false,
+        isTimedOut: false,
+        runUrl: "https://github.com/owner/repo/actions/runs/456",
+      });
+      expect(result).toContain("max-daily-ai-credits");
+    });
+
+    it("returns optimize context when hasToolDenialsExceeded is true", () => {
+      const result = buildOptimizeTokenConsumptionContext({
+        maxAICreditsExceeded: false,
+        hasDailyAICExceeded: false,
+        hasToolDenialsExceeded: true,
+        isTimedOut: false,
+        runUrl: "https://github.com/owner/repo/actions/runs/456",
+      });
+      expect(result).toContain("max-tool-denials");
+    });
+
+    it("returns optimize context when isTimedOut is true", () => {
+      const result = buildOptimizeTokenConsumptionContext({
+        maxAICreditsExceeded: false,
+        hasDailyAICExceeded: false,
+        hasToolDenialsExceeded: false,
+        isTimedOut: true,
+        runUrl: "https://github.com/owner/repo/actions/runs/789",
+      });
+      expect(result).toContain("max-turns / timeout");
+    });
+
+    it("prefers maxAICreditsExceeded label when multiple guardrails are true", () => {
+      const result = buildOptimizeTokenConsumptionContext({
+        maxAICreditsExceeded: true,
+        hasDailyAICExceeded: true,
+        hasToolDenialsExceeded: false,
+        isTimedOut: false,
+        runUrl: "https://github.com/owner/repo/actions/runs/789",
+      });
+      expect(result).toContain("max-ai-credits");
+    });
+  });
+
   // ──────────────────────────────────────────────────────
   // timeout classification (isTimedOut logic in main)
   // ──────────────────────────────────────────────────────
diff --git a/actions/setup/md/agent_failure_issue.md b/actions/setup/md/agent_failure_issue.md
index a2162cf7391..0c26f376934 100644
--- a/actions/setup/md/agent_failure_issue.md
+++ b/actions/setup/md/agent_failure_issue.md
@@ -10,7 +10,7 @@
 
 **Assign this issue to an agent** to debug and fix the issue.
 
-<details>
+{optimize_token_consumption_context}<details>
 <summary>Debug with any coding agent</summary>
 
 Use this prompt with any coding agent (GitHub Copilot, Claude, Gemini, etc.):
diff --git a/actions/setup/md/optimize_token_consumption_context.md b/actions/setup/md/optimize_token_consumption_context.md
new file mode 100644
index 00000000000..df596d108c3
--- /dev/null
+++ b/actions/setup/md/optimize_token_consumption_context.md
@@ -0,0 +1,13 @@
+<details>
+<summary>Optimize token consumption</summary>
+
+This failure was triggered by a guardrail limit ({guardrail_name}). Use this prompt with any coding agent (GitHub Copilot, Claude, Gemini, etc.) to analyze token usage and reduce costs:
+
+````
+Optimize the agentic workflow token consumption using https://raw.githubusercontent.com/github/gh-aw/main/optimize.md
+
+The workflow run is at {run_url}
+````
+
+</details>
+
diff --git a/optimize.md b/optimize.md
new file mode 100644
index 00000000000..7c7e0ad2562
--- /dev/null
+++ b/optimize.md
@@ -0,0 +1,134 @@
+# Optimizing Agentic Workflow Token Consumption
+
+This prompt guides you, a coding agent, to reduce the AI token usage and cost of a **GitHub Agentic Workflow (gh-aw)**.
+
+## How to Use This Prompt
+
+There are two ways to invoke this optimization workflow:
+
+### Option A: Through Copilot
+
+If your repository is configured with the `agentic-workflows` skill, use Copilot Chat:
+
+```text
+agentic-workflows optimize https://github.com/OWNER/REPO/actions/runs/RUN_ID
+```
+
+### Option B: Self-Contained (with URL)
+
+Share this file's URL with any AI assistant or coding agent:
+
+```text
+Optimize the agentic workflow token consumption using https://raw.githubusercontent.com/github/gh-aw/main/optimize.md
+
+The workflow run is at https://github.com/OWNER/REPO/actions/runs/RUN_ID
+```
+
+The agent will follow the steps below to install `gh aw`, analyze the run, and apply cost-reducing changes.
+
+---
+
+## Step 1: Install GitHub Agentic Workflows CLI Extension
+
+Check if `gh aw` is installed by running
+
+```bash
+gh aw version
+```
+
+If it is installed, run:
+
+```bash
+gh extension upgrade aw
+```
+
+to upgrade to latest. If it is not installed, run the installation script from the main branch of the gh-aw repository:
+
+```bash
+curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash
+```
+
+**What this does**: Downloads and installs the gh-aw binary to `~/.local/share/gh/extensions/gh-aw/`
+
+**Verify installation**:
+
+```bash
+gh aw version
+```
+
+You should see version information displayed. If you encounter an error, check that:
+
+- GitHub CLI (`gh`) is installed and authenticated
+- The installation script completed without errors
+- `~/.local/share/gh/extensions` is in your PATH
+
+## Step 2: Optimize Token Consumption
+
+Follow carefully the instructions in the appropriate prompt file. Read ALL the instructions in the prompt file before taking any action.
+
+Below, ROOT is the location where you found this file. For example,
+
+- if this file is at `https://raw.githubusercontent.com/github/gh-aw/main/optimize.md` then the ROOT is `https://raw.githubusercontent.com/github/gh-aw/main`
+- if this file is at `https://raw.githubusercontent.com/github/gh-aw/v0.35.1/optimize.md` then the ROOT is `https://raw.githubusercontent.com/github/gh-aw/v0.35.1`
+
+**Prompt file**: `ROOT/.github/aw/optimize-agentic-workflow.md`
+
+**Use cases**:
+
+- "Why is this workflow consuming so many tokens?"
+- "Reduce the AI credit usage for workflow X"
+- "Optimize the run that hit the max-ai-credits guardrail"
+- "This workflow exceeded max_turns — how do I make it more efficient?"
+
+## Step 3: Apply Optimizations
+
+After identifying the root cause:
+
+1. Edit the workflow markdown file (`.github/workflows/<workflow-name>.md`)
+2. Recompile the workflow:
+
+```bash
+gh aw compile <workflow-name>
+```
+
+3. Check for syntax errors or validation warnings.
+
+## Step 4: Commit and Push Changes
+
+Commit the changes, e.g.
+
+```bash
+git add .github/workflows/<workflow-name>.md .github/workflows/<workflow-name>.lock.yml
+git commit -m "Optimize agentic workflow: <describe optimization>"
+git push
+```
+
+If there is branch protection on the default branch, create a pull request instead and report the link to the pull request.
+
+## Instructions
+
+When a user interacts with you:
+
+1. **Extract the run URL or workflow name** from the user's request
+2. **Fetch and read the optimization prompt** from `ROOT/.github/aw/optimize-agentic-workflow.md`
+3. **Follow the loaded prompt's instructions** exactly
+4. **If uncertain**, ask clarifying questions
+
+## Quick Reference
+
+```bash
+# Audit a specific workflow run (includes token usage)
+gh aw audit <run-id> --json
+
+# Diff two or more workflow runs to measure improvement
+gh aw audit <base-run-id> <optimized-run-id>
+
+# Download and analyze workflow logs
+gh aw logs <workflow-name>
+
+# Compile workflows after optimizing
+gh aw compile <workflow-name>
+
+# Show status of all workflows
+gh aw status
+```
diff --git a/pkg/cli/data/agentic_workflows_fallback_aw_files.json b/pkg/cli/data/agentic_workflows_fallback_aw_files.json
index ba30621eed7..d56b0e2142e 100644
--- a/pkg/cli/data/agentic_workflows_fallback_aw_files.json
+++ b/pkg/cli/data/agentic_workflows_fallback_aw_files.json
@@ -20,6 +20,7 @@
   "memory.md",
   "messages.md",
   "network.md",
+  "optimize-agentic-workflow.md",
   "patterns.md",
   "pr-reviewer.md",
   "report.md",

From 2f12fb4c550a2b38412b39fefc47a59b7f49e04f Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 13 Jun 2026 12:37:20 +0000
Subject: [PATCH 2/4] plan: refactor optimize-agentic-workflow.md as a skill

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 .github/skills/agentic-workflows/SKILL.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/.github/skills/agentic-workflows/SKILL.md b/.github/skills/agentic-workflows/SKILL.md
index ee714d339d8..b4505045ca5 100644
--- a/.github/skills/agentic-workflows/SKILL.md
+++ b/.github/skills/agentic-workflows/SKILL.md
@@ -32,7 +32,6 @@ Load these files from `github/gh-aw` (they are not available locally).
 - `.github/aw/memory.md`
 - `.github/aw/messages.md`
 - `.github/aw/network.md`
-- `.github/aw/optimize-agentic-workflow.md`
 - `.github/aw/patterns.md`
 - `.github/aw/pr-reviewer.md`
 - `.github/aw/report.md`

From efb4bd8c3c1bc90d2d7bc76ba9a5bae80d66c55b Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 13 Jun 2026 12:46:28 +0000
Subject: [PATCH 3/4] feat: refactor optimize-agentic-workflow.md as a proper
 skill

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 .github/skills/agentic-workflows/SKILL.md     |   1 +
 .../skills/optimize-agentic-workflow/SKILL.md | 112 ++++++++++++++++++
 2 files changed, 113 insertions(+)
 create mode 100644 .github/skills/optimize-agentic-workflow/SKILL.md

diff --git a/.github/skills/agentic-workflows/SKILL.md b/.github/skills/agentic-workflows/SKILL.md
index b4505045ca5..ee714d339d8 100644
--- a/.github/skills/agentic-workflows/SKILL.md
+++ b/.github/skills/agentic-workflows/SKILL.md
@@ -32,6 +32,7 @@ Load these files from `github/gh-aw` (they are not available locally).
 - `.github/aw/memory.md`
 - `.github/aw/messages.md`
 - `.github/aw/network.md`
+- `.github/aw/optimize-agentic-workflow.md`
 - `.github/aw/patterns.md`
 - `.github/aw/pr-reviewer.md`
 - `.github/aw/report.md`
diff --git a/.github/skills/optimize-agentic-workflow/SKILL.md b/.github/skills/optimize-agentic-workflow/SKILL.md
new file mode 100644
index 00000000000..86a10883600
--- /dev/null
+++ b/.github/skills/optimize-agentic-workflow/SKILL.md
@@ -0,0 +1,112 @@
+---
+name: optimize-agentic-workflow
+description: Analyze and reduce token consumption in agentic workflows — guardrail-specific entry points, measurement, and optimization techniques.
+---
+
+# Agentic Workflow Token Optimizer
+
+Help users reduce the AI token usage and cost of GitHub Agentic Workflows in this repository.
+
+## Load These References First
+
+Load these files from `github/gh-aw` (they are not available locally).
+
+- `.github/aw/github-agentic-workflows.md`
+- `.github/aw/token-optimization.md`
+- `.github/aw/workflow-editing.md`
+- `.github/aw/syntax.md`
+
+Load these only when relevant:
+
+- `.github/aw/experiments.md`
+- `.github/aw/safe-outputs.md`
+
+## Available Commands
+
+```bash
+gh aw audit <run-id> --json
+gh aw audit <base-run-id> <optimized-run-id>
+gh aw logs <workflow-name> --json
+gh aw compile <workflow-name>
+gh aw status
+```
+
+## Start the Conversation
+
+Ask for one of these inputs:
+
+- a workflow run URL (or run ID) to analyze
+- a workflow name to review the source
+- the guardrail that was exceeded (max-ai-credits, max-daily-ai-credits, max-tool-denials, max-turns / timeout)
+
+## Fast Path: Run URL Provided
+
+If the user gives a GitHub Actions run URL:
+
+1. Extract the run ID
+2. Run `gh aw audit <run-id> --json`
+3. Inspect `agent_usage.aic`, `agent_usage.input_tokens`, `agent_usage.output_tokens`, `agent_usage.cache_read_tokens`
+4. Identify the most expensive phases before asking additional questions
+
+## Guardrail-Specific Entry Points
+
+### `max-ai-credits` exceeded
+
+The workflow was stopped because it consumed more AI Credits than the configured per-run budget.
+
+Priority checks:
+1. Which tool calls dominated token usage? (`token-usage.jsonl`)
+2. Is the prompt front-loading large payloads that could be fetched on demand?
+3. Are there repetitive extraction steps that sub-agents could handle cheaply?
+4. Does the frontier model handle tasks that a small model could do?
+
+### `max-daily-ai-credits` exceeded
+
+The workflow is being blocked because its 24-hour AI Credits budget is exhausted.
+
+Priority checks:
+1. What is the run cadence? (scheduled too frequently?)
+2. Does the workflow use cheap triage before escalating to the frontier model?
+3. Is batching or caching applicable to reduce run frequency?
+4. Are there noop early-exits for events that do not require agent action?
+
+### `max-tool-denials` exceeded
+
+The Copilot SDK hit the tool-denial threshold, indicating the prompt attempted actions outside the allowed tool policy.
+
+Priority checks:
+1. What tool was repeatedly denied? (last denied reason in the failure issue)
+2. Is the tool missing from the workflow's permissions/firewall config?
+3. Can the prompt be revised to avoid the denied operation entirely?
+4. Would a DataOps pre-step satisfy the data need without a tool call?
+
+### Timeout / `max-turns` exceeded
+
+The agent ran out of time or turns before completing the task.
+
+Priority checks:
+1. Is the task decomposable into smaller, faster sub-tasks?
+2. Are there long-running tool calls that could be replaced with DataOps pre-steps?
+3. Is the prompt asking the agent to do too much in one run?
+4. Can `max-turns` or `timeout-minutes` be raised, or should the task be split?
+
+## Optimization Analysis Plan
+
+After measuring token usage, produce a prioritized plan:
+
+1. **Measure** — run `gh aw audit <run-id> --json` and summarize AI Credits and per-call token breakdown
+2. **Identify top cost drivers** — list the three most expensive phases/tool calls
+3. **Apply quick wins first** — DataOps pre-steps, `gh-proxy`, `cli-proxy`, prompt trimming
+4. **Sub-agent delegation** — identify repetitive per-item loops suitable for small-model workers
+5. **Prompt caching** — verify stable context appears before dynamic content
+6. **Experiment** — add an `experiments:` entry with `metric: "aic"` to measure the change
+7. **Validate quality** — confirm the optimized run produces equivalent safe outputs
+
+Present the plan clearly before making any edits. Confirm with the user before applying changes.
+
+## Editing Workflow
+
+1. Edit `.github/workflows/<workflow-name>.md`
+2. Recompile: `gh aw compile <workflow-name>`
+3. Commit both the source and the generated `.lock.yml`
+4. Report the estimated savings and link to the PR or commit

From 7626e21e95b46b15373455e0b45d1a8fb443468a Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 13 Jun 2026 13:50:44 +0000
Subject: [PATCH 4/4] fix: add newline between optimize context placeholder and
 debug details

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 actions/setup/md/agent_failure_issue.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/actions/setup/md/agent_failure_issue.md b/actions/setup/md/agent_failure_issue.md
index 0c26f376934..df928f97f83 100644
--- a/actions/setup/md/agent_failure_issue.md
+++ b/actions/setup/md/agent_failure_issue.md
@@ -10,7 +10,8 @@
 
 **Assign this issue to an agent** to debug and fix the issue.
 
-{optimize_token_consumption_context}<details>
+{optimize_token_consumption_context}
+<details>
 <summary>Debug with any coding agent</summary>
 
 Use this prompt with any coding agent (GitHub Copilot, Claude, Gemini, etc.):