[refactoring] Extract Agentic Workflows MCP Tool Guide into shared component

[github-actions]

Skill Overview

26 workflows use the agentic-workflows: tool but there is no shared component providing guidance on how to use it correctly. Multiple workflows contain verbatim-identical prompt blocks warning agents about authentication requirements and explaining the status, logs, and audit MCP operations. Extracting this into shared/agentic-workflows-guide.md would reduce duplication and eliminate a common agent mistake (calling gh aw directly instead of using MCP tools).

Two workflows (safe-output-health.md and daily-safe-output-optimizer.md) contain byte-for-byte identical setup sections:

- DO NOT ATTEMPT TO USE GH AW DIRECTLY, it is not authenticated. Use the MCP server instead.
- Do not attempt to download the `gh aw` extension or build it. If the MCP fails, give up.
- Run the `status` tool of `gh-aw` MCP server to verify configuration.

And nearly identical log-collection instructions referencing the logs MCP tool, download path /tmp/gh-aw/aw-mcp/logs, and verification steps.

Current Usage

This skill appears across the following workflows:

• safe-output-health.md (lines 49–80 — identical setup block)
• daily-safe-output-optimizer.md (lines 64–95 — identical setup block)
• daily-observability-report.md (lines 53–110 — equivalent guidance, different wording)
• audit-workflows.md (tool config only, no guide text yet)
• daily-firewall-report.md (tool config, similar log analysis pattern)
• agent-performance-analyzer.md (tool config + log-fetch pattern)
• workflow-health-manager.md (tool config + run analysis)
• metrics-collector.md (tool config + status/logs pattern)
• portfolio-analyst.md (pre-downloads logs, similar MCP usage)
• deep-report.md (tool config + log analysis)
• prompt-clustering-analysis.md (tool config + log analysis)
• daily-cli-tools-tester.md (tool config + audit usage)
• example-workflow-analyzer.md (tool config + logs/audit guide)
• … and 13 more workflows with agentic-workflows: tool

Proposed Shared Component

File: .github/workflows/shared/agentic-workflows-guide.md

Configuration:

---
tools:
  agentic-workflows:
---

Guidance content (prompt body — this is the high-value part):

## Using the agentic-workflows MCP Server

**⚠️ CRITICAL**: The `status`, `logs`, and `audit` operations are MCP server tools,
NOT shell commands. Do NOT run `gh aw` directly — it is not authenticated in this context.
Call them as MCP tools with JSON parameters.

- Run the `status` tool to verify configuration and list all workflows
- Use the `logs` tool to download run logs (saves to `/tmp/gh-aw/aw-mcp/logs/`)
- Use the `audit` tool with a `run_id` to investigate specific failed runs

### Common Tool Parameters

#### `status` — List all workflows
…

#### `logs` — Download workflow run logs
- `workflow_name`: filter to specific workflow (leave empty for all)
- `count`: number of runs (default 30, max 5000)
- `start_date`: relative date, e.g. `-1d`, `-7d`, `-30d`
- `engine`: filter by AI engine (copilot, claude, codex)
- Logs saved to `/tmp/gh-aw/aw-mcp/logs/`

#### `audit` — Inspect a specific run
- `run_id`: GitHub Actions run ID (numeric)

Usage Example:

imports:
  - shared/agentic-workflows-guide.md

Impact

• Workflows affected: 26 workflows
• Lines saved: ~25–35 lines per workflow that adds the guide text → ~650–910 lines total across workflows that need the guidance
• Maintenance benefit: Single source of truth for MCP tool usage instructions; fixes propagate to all workflows at once
• Quality benefit: Eliminates agent errors caused by calling gh aw directly instead of via MCP

Implementation Plan

1. Create shared/agentic-workflows-guide.md with tools: agentic-workflows: and comprehensive MCP usage guide
2. Update safe-output-health.md — replace duplicated setup block with import
3. Update daily-safe-output-optimizer.md — replace duplicated setup block with import
4. Update daily-observability-report.md — integrate shared guide, remove duplicated warnings
5. Update audit-workflows.md, daily-firewall-report.md, agent-performance-analyzer.md to import the guide
6. Recompile all affected .lock.yml files with make recompile
7. Verify CI passes

Related Analysis

This recommendation comes from the Workflow Skill Extractor analysis run on 2026-03-15.

See the full analysis report in discussions.

Generated by Workflow Skill Extractor · ◷

• expires on Mar 17, 2026, 4:24 PM UTC

[pelikhan]

@copilot move this prompt as an internal prompt that gets injected by the compiler as a system prompt. This is a builtin . Store prompt text in actions/setup/md