New: 97,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Official agent skill

Debugging Workflows

by github in github/gh-aw-firewall

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

OfficialMITAuto-check: notesDevelopment

Install Debugging Workflows

skills CLI
$ npx skills add github/gh-aw-firewall --skill debugging-workflows -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install github/gh-aw-firewall debugging-workflows --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/github/gh-aw-firewall.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.github/skills/debugging-workflows .claude/skills/debugging-workflows && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
debugging-workflows
GitHub stars
148
Token cost
~2.7k tokens
SKILL.md length
586 words
Files
3
Skills in repo
6
Repo updated
First seen
Licence
MIT

At a glance

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

  • Works in 4 steps: Workflow File Format:… → Triggers (on: field) → Safe Outputs: Controlled way for AI to… → …
  • Tasks that involve Debugging
  • SKILL.md covers Quick Start, GitHub CLI Commands, Understanding Agentic Workflows and Understanding the AWF Firewall, plus 3 more sections
  • Runs TypeScript scripts from its folder; calls gh, npx and docker; reaches api.github.com

What it does

Debugging Workflows is an agent skill from github/gh-aw-firewall, published by the product's own GitHub organization. Debug GitHub Actions workflows by downloading logs, analyzing summaries, and understanding how agentic workflows and the AWF firewall work together.

Its SKILL.md is about 2.7k tokens, which your agent loads only when the skill is triggered. The skill folder holds 2 other files (for example `download-workflow-logs.ts` and `download-workflow-summary.ts`).

It sits in Development, covering Debugging and CI/CD. It works with GitHub and GitHub Actions. The repository describes itself as: GitHub Agentic Workflows Firewall. The licence is MIT.

When your agent uses it

  • Tasks that involve Debugging
  • Tasks that involve CI/CD

Example prompts

  • “/debugging-workflows”

Requirements

  • Node.js
  • Docker
  • Pre-approved tools (allowed-tools): Bash(gh:*), Bash(curl:*), Bash(npx:*), Bash(node:*), Bash(cat:*), Bash(ls:*), Bash(grep:*), Bash(jq:*), Read

Workflow steps

4 steps, taken from the first numbered list in SKILL.md.

  1. Workflow File Format: .github/workflows/.md
  2. Triggers (on: field)
  3. Safe Outputs: Controlled way for AI to create GitHub entities
  4. Tools Configuration (tools: field)

What it can do on your machine

Read from SKILL.md and the folder at commit 681e932. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves these tools, so the agent can use them without asking each time:

    • Bash(gh:*)
    • Bash(curl:*)
    • Bash(npx:*)
    • Bash(node:*)
    • Bash(cat:*)
    • Bash(ls:*)
    • Bash(grep:*)
    • Bash(jq:*)
    • Read

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships script files (TypeScript), which the agent can run.

    Shell commands in SKILL.md call:

    • gh
    • npx
    • docker

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Hosts in commands or code, which the agent is likely to contact:

    • api.github.com

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Debugging Workflows loads about 2.7k tokens when it runs. Until then it costs about 42 tokens; SKILL.md has 586 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~42
When it runs · the whole SKILL.md, loaded when a task matches
~2.7k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

  • NoteRuns commands with sudoSKILL.md:263
    sudo awf --allow-domains github.com 'curl https://api.github.com'
  • NoteRuns commands with sudoSKILL.md:266
    sudo awf --allow-domains github.com --log-level debug 'your-command'
  • NoteRuns commands with sudoSKILL.md:269
    sudo awf --allow-domains github.com --keep-containers 'your-command'
  • NoteRuns commands with sudoSKILL.md:287
    sudo cat $(ls -t /tmp/squid-logs-*/access.log 2>/dev/null | head -1)
  • NoteRuns commands with sudoSKILL.md:328
    sudo cat /tmp/squid-logs-*/access.log

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from github/gh-aw-firewall at commit 681e932, republished under its MIT licence (© github). 586 words, ~2,728 tokens.

Download SKILL.mdSave it as .claude/skills/debugging-workflows/SKILL.md (or your agent's skills folder). This skill also uses 2 other files; get the full folder from GitHub.
name
debugging-workflows
description
Debug GitHub Actions workflows by downloading logs, analyzing summaries, and understanding how agentic workflows and the AWF firewall work together.
allowed-tools
Bash(gh:*), Bash(curl:*), Bash(npx:*), Bash(node:*), Bash(cat:*), Bash(ls:*), Bash(grep:*), Bash(jq:*), Read

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:

bash
# 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:

bash
# 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
bash
# 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
bash
# 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
bash
# 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
bash
# 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
bash
# 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

  1. Workflow File Format: .github/workflows/<name>.md

    • YAML frontmatter for configuration
    • Markdown body for AI instructions
    • Compiles to .github/workflows/<name>.lock.yml

  2. Triggers (on: field):

    • Standard GitHub events: issues, pull_request, push, schedule
    • Command triggers: /mention in issues/comments
    • workflow_dispatch for manual triggers

  3. 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

  4. 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
bash
# 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
bash
# 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
  1. Missing Tool Calls: Check missing_tools in audit output
  2. Safe Output Failures: Review safe_outputs.jsonl artifact
  3. Permission Issues: Verify permissions: block in frontmatter
  4. 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
  1. Command runs in agent container
  2. All HTTP/HTTPS traffic → iptables DNAT → Squid proxy
  3. Squid checks domain against allowlist
  4. Allowed → forward to destination
  5. Blocked → return 403 Forbidden
Show full SKILL.md (242 more words)Show less
Squid Log Analysis
bash
# 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
bash
# 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>/
bash
# 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

  1. Identify the failing workflow run

    bash
    gh run list --status failure --limit 5

  2. Get run details

    bash
    gh run view <run-id> --verbose

  3. Download logs

    bash
    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>

  4. Analyze the failure

    • Check job logs for error messages
    • Look for timeout issues
    • Check for permission errors
    • Review network-related errors

  5. For agentic workflows, audit the run

    bash
    gh aw audit <run-id> --json

  6. If firewall-related, check Squid logs

    bash
    # 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

Start here for diagnosis

If you are diagnosing a failure rather than exploring, enter through the diagnose-awf skill and the canonical diagnosis registry in docs/diagnostics/README.md. This skill is one of the specialist references it routes to.

© github, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 2 other files in .github/skills/debugging-workflows of github/gh-aw-firewall.

  • SKILL.md
  • download-workflow-logs.ts
  • download-workflow-summary.ts

Open the folder on GitHubat commit 681e932

Compare with similar skills

Debugging Workflows next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Debugging Workflows compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Debugging Workflows this skillgithub/gh-aw-firewall148—~2.7kAutomated safety check: NotesMIT
gh-aw Workflow Diagnosisgithub/gh-aw5.3k—~3.9kAutomated safety check: PassMIT
Authoring CI WorkflowsPostHog/posthog-foss721—~11kAutomated safety check: PassMIT
CI/CD Failure Troubleshootingruby-git/ruby-git1.8k—~1.9kAutomated safety check: PassMIT
GitHub Actions Failure Analysisykdojo/claude-code-tips10k—~639Automated safety check: PassCustom licence
Debugging CI FailuresPostHog/posthog-foss721—~5.7kAutomated safety check: PassMIT

Similar skills

  • gh-aw Workflow Diagnosis

    github/gh-aw

    Official

    Guides your agent through diagnosing failed GitHub Agentic Workflows by downloading run logs, auditing individual runs and reading the artifacts they leave behind.

    5.3k GitHub stars~3.9k tokensUpdated today
    DevelopmentAuto-check passed

  • Authoring CI Workflows

    PostHog/posthog-foss

    Official

    A skill your agent uses when adding or editing a GitHub Actions workflow, composite action, or reusable workflow under .github/ — new CI jobs, triggers, matrices, checkout/clone tuning, action…

    721 GitHub stars~11k tokensUpdated today
    DevelopmentAuto-check passed

  • CI/CD Failure Troubleshooting

    ruby-git/ruby-git

    Diagnoses and fixes failing GitHub Actions runs by identifying the failure, fetching only the relevant logs, finding the root cause and reproducing it locally.

    1.8k GitHub stars~1.9k tokensUpdated 5 days ago
    DevOps & CloudAuto-check passed

  • GitHub Actions Failure Analysis

    ykdojo/claude-code-tips

    Investigates a failed GitHub Actions run from its URL: pinpoints the real failure, checks the job's history for flakiness, and finds the breaking commit and any existing fix PR.

    10k GitHub stars~639 tokensUpdated 12 days ago
    DevOps & CloudAuto-check passed

  • Debugging CI Failures

    PostHog/posthog-foss

    Official

    Debugs failing GitHub Actions CI runs for PostHog PRs, commits, and branches, and answers broad CI-health questions ("is CI red?", "is master green today?", "what's broken right now?").

    721 GitHub stars~5.7k tokensUpdated today
    Testing & QAAuto-check passed

  • Renovate Actions PR Review

    backnotprop/plannotator

    Reviews Renovate pull requests that bump GitHub Actions by checking pinned SHAs against upstream tags, scanning changelogs and confirming workflows stay compatible.

    9.2k GitHub stars~640 tokensUpdated yesterday
    DevelopmentAuto-check passed

More from github/gh-aw-firewall

  • Awf Debug Tools

    github/gh-aw-firewall

    Official

    Practical Python scripts for debugging awf - parse logs, diagnose issues, inspect containers, test domains

    148 GitHub stars~2.6k tokensUpdated today
    Auto-check: notes

  • Recompile Workflows

    github/gh-aw-firewall

    Official

    Regenerate and post-process all agentic workflows. An agent skill from github/gh-aw-firewall.

    148 GitHub stars~568 tokensUpdated today
    Auto-check passed

  • Add LLM Provider

    github/gh-aw-firewall

    Official

    Decide and implement how to support a new LLM provider or agent engine in AWF - either as a proxied provider (api-proxy adapter) or a direct-API engine (domain allowlist only), e.g.

    148 GitHub stars~1.4k tokensUpdated today
    Auto-check passed

  • Debug Firewall

    github/gh-aw-firewall

    Official

    Debug the AWF firewall by inspecting Docker containers (awf-squid, awf-agent), analyzing Squid access logs, checking iptables rules, and troubleshooting blocked domains or network issues.

    148 GitHub stars~1.2k tokensUpdated today
    Auto-check: notes

  • Diagnose Awf

    github/gh-aw-firewall

    Official

    Diagnose an AWF (Agentic Workflow Firewall) failure from an error, workflow run URL, or symptom.

    148 GitHub stars~829 tokensUpdated today
    Auto-check passed

Works with

Categories

Questions about Debugging Workflows

What does Debugging Workflows do?

Debug GitHub Actions workflows by downloading logs, analyzing summaries, and understanding how agentic workflows and the AWF firewall work together. Debugging Workflows is an agent skill from github/gh-aw-firewall, published by the product's own GitHub organization. Debug GitHub Actions workflows by downloading logs, analyzing summaries, and understanding how agentic workflows and the AWF firewall work together.

When should I use Debugging Workflows?

Debugging Workflows fits situations like: tasks that involve Debugging; tasks that involve CI/CD.

How do I install Debugging Workflows in Claude Code?

Run `npx skills add github/gh-aw-firewall --skill debugging-workflows -a claude-code`. Or copy the skill folder (.github/skills/debugging-workflows in github/gh-aw-firewall) into .claude/skills/debugging-workflows in your project. Claude Code loads it when a task matches its description.

How do I install Debugging Workflows in Codex?

Run `npx skills add github/gh-aw-firewall --skill debugging-workflows -a codex`. Or copy the skill folder (.github/skills/debugging-workflows in github/gh-aw-firewall) into .agents/skills/debugging-workflows in your project. Codex loads it when a task matches its description.

Can I use Debugging Workflows in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add github/gh-aw-firewall --skill debugging-workflows -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/debugging-workflows, .gemini/skills/debugging-workflows, .github/skills/debugging-workflows and .opencode/skills/debugging-workflows in your project.

What does Debugging Workflows need to run?

Going by SKILL.md and its folder, Debugging Workflows needs TypeScript for the scripts in its folder and the command-line tools its instructions call (gh, npx and docker). Our summary lists: Node.js; Docker. Its frontmatter pre-approves these tools: Bash(gh:*), Bash(curl:*), Bash(npx:*), Bash(node:*), Bash(cat:*), Bash(ls:*), Bash(grep:*), Bash(jq:*), Read.

Does Debugging Workflows access the network?

SKILL.md names 1 domain. In commands or code: api.github.com; the agent is likely to contact it when it follows the instructions. This is read from the text; nothing was executed.

Is Debugging Workflows safe to install?

Our automated static check of SKILL.md found notes only (runs commands with sudo), nothing it rates as a warning. It is not a guarantee. Review the folder before installing.

What licence does Debugging Workflows use?

Debugging Workflows is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Debugging Workflows use?

About 2.7k tokens (SKILL.md is roughly 11k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Debugging Workflows?

Skills that share tags, products or a category with Debugging Workflows: gh-aw Workflow Diagnosis (github/gh-aw, 5.3k stars), Authoring CI Workflows (PostHog/posthog-foss, 721 stars), CI/CD Failure Troubleshooting (ruby-git/ruby-git, 1.8k stars) and GitHub Actions Failure Analysis (ykdojo/claude-code-tips, 10k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Debugging Workflows?

github (a GitHub organization, an official publisher) maintains it in github/gh-aw-firewall, which has 148 GitHub stars. The repository holds 6 skills in this directory. The repository was last updated on October 7, 2026.

Source: github/gh-aw-firewall on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.