review-agentic-workflows

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.

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. Run the install step before continuing:"
    echo "  bash ./install-gh-aw.sh"
    echo "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

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

3) Enforce security best practices