Review Agentic Workflows

Use this skill when asked to review .github/workflows/*.md agentic workflows or their generated .lock.yml outputs. Reference workflow authoring skill guidance at: https://raw.githubusercontent.com/github/gh-aw/main/.github/skills/agentic-workflows/SKILL.md

Goals

1. Produce a security-first review of workflow changes.
2. Compile workflows with validation and security scanners.
3. Flag suspicious changes that weaken protections.
4. Use run history (logs/audit) when available to find optimization opportunities.

Agent ownership

The agent performs setup, source and runtime-dependency inspection, independent single-reviewer coordination, compilation/scanners, evidence collection, finding resolution and cleanup. Do not give the user a technical preflight checklist to execute. Report concrete blockers and request only authorization or decisions the agent cannot supply. For debugging and live-test gates, follow the shared security-review guidance; the agent prepares the evidence for human validation rather than asking the user to conduct the review.

Require exactly one read-only security-review agent per reviewed revision. Resolve coverage questions with that reviewer; do not require parallel judges, majority votes or a tie-breaker. Follow the shared single-reviewer rules.

The user may explicitly authorize live debugging for the current session rather than approve each run. Record the grant and agreed scope/bounds; reuse it for in-scope revisions only after the agent repeats the required technical review. Any compiler security warning invalidates session approval immediately, even if later fixed: resolve it, re-review, and obtain fresh explicit authorization. Follow the shared session authorization rules; a request to update this skill is not itself a session-wide execution grant.

Workflow registration/activation and secret presence, validity, or expiry are runtime readiness checks, not pre-dispatch review gates. Do not require workflow or secret inventories, organization-admin access, or proof of usable credentials before an otherwise authorized run. Dispatch and the workflow's startup/authentication checks establish readiness; report their actual failures without automatic retries or enabling workflows. Continue to review declared credential flows, authorized destinations, permissions, and redaction without retrieving secret values. Missing readiness metadata alone is not a security finding or an UNKNOWN safety verdict.

Self-contained setup (do not assume environment is ready)

Step 0) Verify CLI availability

Run from the repository root:

if gh aw --help >/dev/null 2>&1; then
  echo "gh aw is installed"
else
  if [ -f ./install-gh-aw.sh ]; then
    echo "gh aw is missing. The agent must run the install step before continuing:"
    echo "  bash ./install-gh-aw.sh"
    echo "The agent must then verify:"
    echo "  gh aw --help"
  else
    echo "gh aw is missing and ./install-gh-aw.sh is not present in this checkout."
  fi
  return 1 2>/dev/null || exit 1
fi

Review workflow

1) Scope the review

Run this scope check in the review step:

BASE_REF="${BASE_REF:-origin/main}"
if git rev-parse --verify "$BASE_REF" >/dev/null 2>&1; then
  git diff --name-only "$BASE_REF...HEAD" -- .github/workflows/
else
  git diff --name-only -- .github/workflows/
fi

If source .md files changed, treat generated .lock.yml drift as part of the review.

2) Compile with validation + security tools

For changed workflows, run strict compilation with validators:

gh aw compile --strict --actionlint --zizmor --poutine --runner-guard --yamllint --shellcheck

If gh aw extension is unavailable but local binary exists:

./gh-aw compile --strict --actionlint --zizmor --poutine --runner-guard --yamllint --shellcheck

For debug/dry-run reviews, the agent runs gh aw compile WORKFLOW --dry-run, adding available scanners as required by the shared guidance. Do not combine --dry-run with --no-emit: emitted locks are part of the evidence. A disposable checkout is optional. Running in the current checkout and reverting only compiler-generated changes is permitted after snapshotting all affected files, preserving diagnostic outputs, and checking for concurrent edits. Restore pre-existing user changes exactly; never use a broad worktree reset. See the snapshot/restore rules.

Fail review on compilation errors or High/Critical security findings unless explicitly justified.

3) Enforce security best practices

Require and verify:

• least-privilege permissions: (no write-all without explicit rationale)
• pinned third-party actions by full commit SHA
• safe handling of untrusted GitHub event data (no direct template injection into shell)
• explicit safe-outputs limits (max, constrained event/action sets)
• no broadening of network/tool access without justification
• no integrity downgrades (for example lower min-integrity)

4) Detect suspicious weakening changes

Treat these as suspicious until proven safe:

• permission expansion (especially new write scopes or global writes)
• relaxed security controls (strict: false, reduced guardrails, disabled scans)
• larger write blast radius (safe-outputs limits removed or sharply increased)
• reduced provenance controls (unpinning actions, mutable refs)
• wider external access (new unrestricted network domains/ecosystems)
• prompt or script edits that reintroduce command/template injection risk

Use targeted diffs and call out before/after impact.

5) Audit history and optimize (when run data exists)

If workflow run IDs/URLs are available, audit them:

gh aw audit <run-id-or-url>
gh aw logs --start-date -14d --workflow-name <workflow-name>

Look for optimization opportunities:

• high token/cost usage
• repeated retries/tool failures
• long-running steps or bottleneck jobs
• unnecessary MCP/tool invocations
• firewall denials causing retries or wasted turns

Recommend minimal, safe optimizations that keep or improve security posture.

Review output contract

Show an annotated overview of changed authored .md files, excluding generated .lock.yml diffs from the overview. Link source lines, describe before/after behavior, and explain the security impact of each relevant change in plain language. Include preserved controls and unresolved evidence, not just findings. Keep generated locks in the execution-review evidence. Follow the shared annotated overview contract.

Always provide a short user-visible result sentence for each security review and dry-run attempt, including failed, blocked, or unavailable checks. State the artifact/scope, outcome, what was actually checked, and any material finding or coverage gap. Do not leave results only in logs, artifacts, or subagent replies. Keep security-review and dry-run results separate; neither implies live execution or authorization. Follow the shared review result and dry-run result rules.

Return findings in three sections:

1. Security regressions (must-fix) — high-confidence weakening changes.
2. Validation/scanner results — compile and tool outcomes.
3. Optimization opportunities — optional improvements backed by logs/audit evidence.

Each finding should include severity, file(s), rationale, and a concrete remediation direction.