mcpbeat Sign in

Debugging Workflows Skill for Claude

by github

Debug GitHub Actions workflows by downloading logs, analyzing summaries, and understanding how agentic workflows and the AWF firewall work together.

9k tokens
context cost
the whole folder, loaded on every use
3
files
ships runnable scripts
0
copies elsewhere
how many repositories repackaged it
119
stars on the repo
on the repository, not the skill itself

Install

one command, takes just this skill from the repository 
npx skills add https://github.com/github/gh-aw --skill debugging-workflows

What comes with it

24 220 bytes besides the instruction
download-workflow-logs.ts
download-workflow-summary.ts

What it tells the agent to use

found in the instruction text
Bash runs shell commands — read the instruction before connecting

The instruction itself

33 sections, as written by the author

Debugging Workflows Skill

Use this skill when you need to debug GitHub Actions workflows, download workflow logs or summaries, or understand how agentic workflows and the AWF firewall work together.

Quick Start

Download Workflow Logs

Use the download-workflow-logs.ts script to download logs from a workflow run:

# Download logs from the latest workflow run
npx tsx .github/skills/debugging-workflows/download-workflow-logs.ts

# Download logs from a specific run ID
npx tsx .github/skills/debugging-workflows/download-workflow-logs.ts --run-id 1234567890

# Download logs from a specific workflow
npx tsx .github/skills/debugging-workflows/download-workflow-logs.ts --workflow test-integration.yml

# Save logs to a specific directory
npx tsx .github/skills/debugging-workflows/download-workflow-logs.ts --output ./my-logs

Download Workflow Summary

Use the download-workflow-summary.ts script to get a summary of workflow runs:

# Get summary of latest workflow runs
npx tsx .github/skills/debugging-workflows/download-workflow-summary.ts

# Get summary for a specific workflow run
npx tsx .github/skills/debugging-workflows/download-workflow-summary.ts --run-id 1234567890

# Get summary for a specific workflow file
npx tsx .github/skills/debugging-workflows/download-workflow-summary.ts --workflow test-integration.yml

# Get summary as JSON
npx tsx .github/skills/debugging-workflows/download-workflow-summary.ts --format json

GitHub CLI Commands

The gh CLI is essential for debugging workflows. Here are the most useful commands:

List Workflow Runs

# List recent workflow runs
gh run list --limit 10

# List runs for a specific workflow
gh run list --workflow test-integration.yml --limit 10

# List only failed runs
gh run list --status failure --limit 10

# List runs in JSON format for parsing
gh run list --json databaseId,name,status,conclusion,createdAt --limit 10

View Workflow Run Details

# View a specific run
gh run view <run-id>

# View run with job details
gh run view <run-id> --verbose

# View run as JSON
gh run view <run-id> --json jobs,conclusion,status

Download Run Logs

# Download all logs for a run
gh run download <run-id>

# Download specific artifact
gh run download <run-id> --name <artifact-name>

# Download to specific directory
gh run download <run-id> --dir ./logs

Watch a Running Workflow

# Watch a workflow run in real-time
gh run watch <run-id>

# Watch with exit code (useful for CI)
gh run watch <run-id> --exit-status

Re-run Failed Jobs

# Re-run failed jobs only
gh run rerun <run-id> --failed

# Re-run all jobs
gh run rerun <run-id>

Understanding Agentic Workflows

What are Agentic Workflows?

Agentic workflows are GitHub Actions workflows that use AI agents (like GitHub Copilot or Claude) to perform tasks. They are defined using markdown + YAML frontmatter format in .github/workflows/*.md files and compiled to GitHub Actions YAML (.lock.yml files).

Key Components

  • Workflow File Format: .github/workflows/<name>.md
  • YAML frontmatter for configuration
  • Markdown body for AI instructions
  • Compiles to .github/workflows/<name>.lock.yml
  • Triggers (on: field):
  • Standard GitHub events: issues, pull_request, push, schedule
  • Command triggers: /mention in issues/comments
  • workflow_dispatch for manual triggers
  • Safe Outputs: Controlled way for AI to create GitHub entities
  • create-issue: - Create GitHub issues
  • create-pull-request: - Create PRs with git patches
  • add-comment: - Add comments to issues/PRs
  • add-labels: - Add labels to issues/PRs
  • create-discussion: - Create GitHub discussions
  • Tools Configuration (tools: field):
  • github: - GitHub API tools
  • agentic-workflows: - Workflow introspection tools
  • edit: - File editing tools
  • web-fetch: / web-search: - Web access tools
  • bash: - Shell command tools

Compiling Workflows

# Compile all workflows
gh aw compile

# Compile a specific workflow
gh aw compile <workflow-name>

# Compile with strict security checks
gh aw compile --strict

Debugging Agentic Workflows

# View status of all agentic workflows
gh aw status

# Download and analyze logs from previous runs
gh aw logs <workflow-name> --json

# Audit a specific run for issues
gh aw audit <run-id> --json

Common Issues

  • Missing Tool Calls: Check missing_tools in audit output
  • Safe Output Failures: Review safe_outputs.jsonl artifact
  • Permission Issues: Verify permissions: block in frontmatter
  • Network Blocked: Check network: configuration for allowed domains

Understanding the AWF Firewall

What is AWF?

AWF (Agent Workflow Firewall) is a tool that provides L7 (HTTP/HTTPS) egress control for GitHub Copilot CLI and other agents. It restricts network access to a whitelist of approved domains using Squid proxy and Docker containers.

Architecture Overview

┌─────────────────────────────────────────┐
│  Host (GitHub Actions Runner / Local)   │
│                                          │
│  ┌────────────────────────────────────┐ │
│  │   Firewall CLI (awf)              │ │
│  │   - Parse arguments                │ │
│  │   - Generate Squid config          │ │
│  │   - Start Docker Compose           │ │
│  └────────────────────────────────────┘ │
│           │                              │
│           ▼                              │
│  ┌──────────────────────────────────┐   │
│  │   Docker Compose                 │   │
│  │  ┌────────────────────────────┐  │   │
│  │  │  Squid Proxy Container     │  │   │
│  │  │  - Domain ACL filtering    │  │   │
│  │  │  - HTTP/HTTPS proxy        │  │   │
│  │  └────────────────────────────┘  │   │
│  │           ▲                       │   │
│  │  ┌────────┼───────────────────┐  │   │
│  │  │ Agent Container            │  │   │
│  │  │ - Full filesystem access   │  │   │
│  │  │ - iptables redirect        │  │   │
│  │  │ - All traffic → Squid      │  │   │
│  │  └────────────────────────────┘  │   │
│  └──────────────────────────────────┘   │
└─────────────────────────────────────────┘

Key Containers

  • awf-squid - Squid proxy container (IP: 172.30.0.10)
  • Filters HTTP/HTTPS traffic based on domain allowlist
  • Logs all traffic decisions
  • awf-agent - Agent execution container (IP: 172.30.0.20)
  • Runs the actual command/agent
  • Has iptables rules to redirect traffic to Squid
  • Full filesystem access via /host mount

Traffic Flow

  • Command runs in agent container
  • All HTTP/HTTPS traffic → iptables DNAT → Squid proxy
  • Squid checks domain against allowlist
  • Allowed → forward to destination
  • Blocked → return 403 Forbidden

Squid Log Analysis

# View Squid access log (shows traffic decisions)
docker exec awf-squid cat /var/log/squid/access.log

# Find blocked domains
docker exec awf-squid grep "TCP_DENIED" /var/log/squid/access.log | awk '{print $3}' | sort -u

# Count blocked by domain
docker exec awf-squid grep "TCP_DENIED" /var/log/squid/access.log | awk '{print $3}' | sort | uniq -c | sort -rn

# Real-time blocked traffic
docker exec awf-squid tail -f /var/log/squid/access.log | grep --line-buffered TCP_DENIED

Squid Decision Codes

  • TCP_TUNNEL:HIER_DIRECT = ALLOWED (HTTPS)
  • TCP_MISS:HIER_DIRECT = ALLOWED (HTTP)
  • TCP_DENIED:HIER_NONE = BLOCKED

Running Commands Through Firewall

# Basic usage
sudo awf --allow-domains github.com 'curl https://api.github.com'

# With debug logging
sudo awf --allow-domains github.com --log-level debug 'your-command'

# Keep containers for inspection
sudo awf --allow-domains github.com --keep-containers 'your-command'

Preserved Logs Locations

With --keep-containers:

  • Squid: /tmp/awf-<timestamp>/squid-logs/access.log
  • Agent: /tmp/awf-<timestamp>/agent-logs/

Normal execution (after cleanup):

  • Squid: /tmp/squid-logs-<timestamp>/access.log
  • Agent: /tmp/awf-agent-logs-<timestamp>/
# Find preserved logs
ls -ldt /tmp/awf-* /tmp/squid-logs-* 2>/dev/null | head -5

# View preserved Squid logs
sudo cat $(ls -t /tmp/squid-logs-*/access.log 2>/dev/null | head -1)

Debugging Workflow Failures

Step-by-Step Process

  • Identify the failing workflow run
   gh run list --status failure --limit 5
  • Get run details
   gh run view <run-id> --verbose
  • Download logs
   gh run download <run-id> --dir ./logs
   # Or use the script:
   npx tsx .github/skills/debugging-workflows/download-workflow-logs.ts --run-id <run-id>
  • Analyze the failure
  • Check job logs for error messages
  • Look for timeout issues
  • Check for permission errors
  • Review network-related errors
  • For agentic workflows, audit the run
   gh aw audit <run-id> --json
  • If firewall-related, check Squid logs
   # If containers are still running
   docker exec awf-squid cat /var/log/squid/access.log
   
   # Or check preserved logs
   sudo cat /tmp/squid-logs-*/access.log

Common Failure Patterns

Permission Denied
Error: Resource not accessible by integration

Fix: Check permissions: in workflow frontmatter

Domain Blocked
curl: (56) Recv failure: Connection reset by peer

Fix: Add domain to --allow-domains or network: configuration

Timeout
Error: The operation was canceled.

Fix: Increase timeout-minutes in workflow configuration

Missing Tool
Tool 'xyz' not found

Fix: Add tool to tools: configuration in workflow frontmatter

Related Documentation

  • Architecture - System architecture details
  • Troubleshooting - Common issues and solutions
  • GitHub Actions Integration - CI/CD setup
  • Logging Documentation - Comprehensive logging guide
  • Debug Firewall Skill - Firewall-specific debugging

Other skills for the same job

different authors, same section of the catalogue
Workflow Patterns
by ComeOnOliver
×2

Use this skill when implementing tasks according to Conductor's TDD workflow, handling phase checkpoints, managing git commits for tasks, or understanding the verification protocol.

6k tokens
Iso Standards Readiness
by K-Dense-AI
×1

Prepares and structurally reviews readiness evidence for ISO management-system and laboratory-competence standards - ISO 13485 medical device QMS, ISO 14971 device risk management, ISO/IEC 17025 testing and calibration laboratories, and ISO 15189 medical laboratories. Use when organizing declared scope, controlled documents, risk-management files, scope of accreditation, traceability, CAPA, external-provider controls, or bounded local evidence manifests, and when separating ISO certification from laboratory accreditation, FDA QMSR inspection, CLIA certification, MDSAP, and EU MDR/IVDR evidence boundaries. Not for legal applicability, compliance, certification, or accreditation decisions; contains no clause text.

67k tokens scripts
Statistical Power
by K-Dense-AI
×1

Sample-size and statistical power calculations for planning studies. Use whenever someone asks "how many subjects/samples/replicates do I need", wants an a priori power analysis, a minimum detectable effect (MDE), a power curve, or needs to justify a sample size for a grant, IRB protocol, or pre-registration. Covers closed-form power for t-tests, ANOVA, proportions, correlations, chi-square, and regression, plus simulation-based (Monte Carlo) power for designs with no formula — logistic/Poisson regression, mixed models, cluster-randomized trials, survival, and interactions. Use this skill even when the request only mentions an effect size, alpha, or "80% power" without saying "power analysis" explicitly. For laying out the study (randomization, blocking, factorial/DOE, crossover, sequential designs) use experimental-design; for analyzing data already collected and reporting it use statistical-analysis.

13k tokens scripts
General Figure Guide
by BioTender-max
×1

Universal QA checklist for generated scientific plots: overlapping labels, clipped text, missing axes/legends, overcrowded data, and cross-journal resolution/format guidance.

2k tokens
Nerdzao Elite
by ComeOnOliver
×1

Senior Elite Software Engineer (15+) and Senior Product Designer. Full workflow with planning, architecture, TDD, clean code, and pixel-perfect UX validation.

3k tokens
Pinchbench
by ComeOnOliver
×1

Run PinchBench benchmarks to evaluate OpenClaw agent performance across real-world tasks. Use when testing model capabilities, comparing models, submitting benchmark results to the leaderboard, or checking how well your OpenClaw setup handles calendar, email, research, coding, and multi-step workflows.

2096k tokens scripts
Workflow Patterns
by ComeOnOliver
×1

Use this skill when implementing tasks according to Conductor's TDD workflow, handling phase checkpoints, managing git commits for tasks, or understanding the verification protocol.

6k tokens
Powertoys Verification
by microsoft
vendor

Verify PowerToys behavior end-to-end with the winapp CLI across two scenarios: (A) a module's release checklist against the installed build; (B) PR validation — derive each PR's checklist from its description + diff, then drive it against the installed build (a merged/shipped PR, or a whole release/hotfix set) or by building + sideloading the module when the PR isn't in the build yet (unmerged or not-yet-released). Drive each item via UIA invoke / Named Events / settings.json edits / clipboard / GPO / SendInput, and emit a structured PASS / FAIL / BLOCKED verdict per item with evidence (FAIL distinguishes product defects from stale/ambiguous checklist items). Use when asked to verify a module checklist, validate a PR, sign off a release/hotfix's PRs, or QA installed/sideloaded PowerToys bits. Combines generic winapp ui mechanics (references/winapp-ui-testing.md) with PT-specific recipes, per-scenario playbooks (references/scenarios/), and the helper .ps1 files shipped with this skill.

86k tokens scripts

How to use it

Copy the folder

Take github/debugging-workflows from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

The agent identifies a skill by the name field in its header. Two skills with the same name cannot sit side by side — one of them will be ignored.

Install what it needs

The instructions reference npx. Without those the skill loads but fails at the first command.