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

Awf Debug Tools

by github in github/gh-aw-firewall

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

OfficialMITAuto-check: notesDevelopment

Install Awf Debug Tools

skills CLI
$ npx skills add github/gh-aw-firewall --skill awf-debug-tools -a claude-code

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

GitHub CLI
$ gh skill install github/gh-aw-firewall awf-debug-tools --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/.claude/skills/awf-debug-tools .claude/skills/awf-debug-tools && 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
awf-debug-tools
GitHub stars
148
Token cost
~2.6k tokens
SKILL.md length
696 words
Files
7 (incl. scripts)
Skills in repo
6
Repo updated
First seen
Licence
MIT

At a glance

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

  • Works in 4 steps: parse-squid-logs.py - Parse Squid logs… → diagnose-awf.py - Run automated… → inspect-containers.py - Show concise… → …
  • Tasks that involve Debugging
  • SKILL.md covers Why These Scripts?, Available Scripts, Quick Start and Common Workflows, plus 11 more sections
  • Runs Python scripts from its folder; calls python, jq and pip; reaches api.github.com

What it does

Awf Debug Tools is an agent skill from github/gh-aw-firewall, published by the product's own GitHub organization. Practical Python scripts for debugging awf - parse logs, diagnose issues, inspect containers, test domains

Its SKILL.md is about 2.6k tokens, which your agent loads only when the skill is triggered. The skill folder holds 7 other files, including scripts (for example `scripts/common.py`, `scripts/diagnose-awf.py` and `scripts/inspect-containers.py`).

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

When your agent uses it

  • Tasks that involve Debugging

Example prompts

  • “/awf-debug-tools”

Requirements

  • Python 3
  • Docker
  • Pre-approved tools (allowed-tools): Bash(python:*), Bash(docker:*), Bash(sudo:*), Read

Workflow steps

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

  1. parse-squid-logs.py - Parse Squid logs and extract blocked domains with counts
  2. diagnose-awf.py - Run automated diagnostic checks on container health and configuration
  3. inspect-containers.py - Show concise container status without verbose docker output
  4. test-domain.py - Test if specific domain is reachable through the firewall

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(python:*)
    • Bash(docker:*)
    • Bash(sudo:*)
    • Read

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 6 files in scripts/ (Python), which the agent can run.

    Shell commands in SKILL.md call:

    • python
    • jq
    • pip

    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

Awf Debug Tools loads about 2.6k tokens when it runs. Until then it costs about 31 tokens; SKILL.md has 696 words of instructions outside code blocks.

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

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:106
    sudo awf --allow-domains github.com,npmjs.org 'your-command'
  • NoteRuns commands with sudoSKILL.md:305
    # Squid logs require sudo to read
  • NoteRuns commands with sudoSKILL.md:306
    sudo python .claude/skills/awf-debug-tools/scripts/parse-squid-logs.py --log-file /tmp/squid-logs-*/access.log
  • NoteRuns commands with sudoSKILL.md:312
    sudo awf --allow-domains github.com 'curl https://api.github.com'

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); the scripts in this folder are not scanned.

SKILL.md

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

Download SKILL.mdSave it as .claude/skills/awf-debug-tools/SKILL.md (or your agent's skills folder). This skill also uses 6 other files; get the full folder from GitHub.
name
awf-debug-tools
description
Practical Python scripts for debugging awf - parse logs, diagnose issues, inspect containers, test domains
allowed-tools
Bash(python:*), Bash(docker:*), Bash(sudo:*), Read

AWF Debug Tools

A collection of practical Python scripts that help agents efficiently debug and operate the awf firewall. These scripts reduce verbose Docker/log output by 80%+ and provide actionable insights instead of raw data dumps.

Why These Scripts?

Problem: Docker commands and log files are verbose and hard for agents to parse. Diagnosing issues requires 10+ manual commands and produces noisy output that wastes tokens.

Solution: One script replaces 5-10 manual commands with clean, filtered output optimized for agent consumption. All scripts support JSON format for easy parsing.

Available Scripts

All scripts are located in .claude/skills/awf-debug-tools/scripts/:

  1. parse-squid-logs.py - Parse Squid logs and extract blocked domains with counts
  2. diagnose-awf.py - Run automated diagnostic checks on container health and configuration
  3. inspect-containers.py - Show concise container status without verbose docker output
  4. test-domain.py - Test if specific domain is reachable through the firewall

Quick Start

Parse Logs to Find Blocked Domains
bash
# Auto-discover logs and show all domains
python .claude/skills/awf-debug-tools/scripts/parse-squid-logs.py

# Show only blocked domains
python .claude/skills/awf-debug-tools/scripts/parse-squid-logs.py --blocked-only

# Filter by domain
python .claude/skills/awf-debug-tools/scripts/parse-squid-logs.py --domain github.com

# Show top 10, JSON output
python .claude/skills/awf-debug-tools/scripts/parse-squid-logs.py --top 10 --format json
Run Automated Diagnostics
bash
# Quick health check
python .claude/skills/awf-debug-tools/scripts/diagnose-awf.py

# Detailed output
python .claude/skills/awf-debug-tools/scripts/diagnose-awf.py --verbose

# JSON output for agent parsing
python .claude/skills/awf-debug-tools/scripts/diagnose-awf.py --format json
Inspect Container Status
bash
# Inspect all containers
python .claude/skills/awf-debug-tools/scripts/inspect-containers.py

# Specific container only
python .claude/skills/awf-debug-tools/scripts/inspect-containers.py --container awf-squid

# Show only logs
python .claude/skills/awf-debug-tools/scripts/inspect-containers.py --logs-only

# JSON output
python .claude/skills/awf-debug-tools/scripts/inspect-containers.py --format json
Test Domain Reachability
bash
# Test if domain is allowed
python .claude/skills/awf-debug-tools/scripts/test-domain.py github.com

# Test blocked domain with fix suggestion
python .claude/skills/awf-debug-tools/scripts/test-domain.py npmjs.org --suggest-fix

# Check allowlist only (no log lookup)
python .claude/skills/awf-debug-tools/scripts/test-domain.py api.github.com --check-allowlist

# JSON output
python .claude/skills/awf-debug-tools/scripts/test-domain.py github.com --format json

Common Workflows

Workflow 1: Debugging Blocked Requests

When a command fails due to blocked domain:

bash
# 1. Run diagnostics to check overall health
python .claude/skills/awf-debug-tools/scripts/diagnose-awf.py

# 2. Parse logs to find which domains were blocked
python .claude/skills/awf-debug-tools/scripts/parse-squid-logs.py --blocked-only

# 3. Test specific domain and get fix suggestion
python .claude/skills/awf-debug-tools/scripts/test-domain.py npmjs.org --suggest-fix

# 4. Apply the suggested fix
sudo awf --allow-domains github.com,npmjs.org 'your-command'
Workflow 2: Container Health Check

When containers aren't starting or behaving unexpectedly:

bash
# 1. Check container status and recent logs
python .claude/skills/awf-debug-tools/scripts/inspect-containers.py

# 2. Run full diagnostics
python .claude/skills/awf-debug-tools/scripts/diagnose-awf.py --verbose

# 3. If issues found, check Squid logs for errors
python .claude/skills/awf-debug-tools/scripts/parse-squid-logs.py
Workflow 3: Agent Automated Debugging

For agents to diagnose issues without human intervention:

bash
# Run all checks with JSON output
python .claude/skills/awf-debug-tools/scripts/diagnose-awf.py --format json | jq .

# Parse blocked domains
python .claude/skills/awf-debug-tools/scripts/parse-squid-logs.py --blocked-only --format json | jq .

# Test each blocked domain
python .claude/skills/awf-debug-tools/scripts/test-domain.py npmjs.org --format json | jq .

Output Formats

All scripts support two output formats:

  • table/text (default): Human-readable format with clear sections and alignment
  • json: Machine-readable format optimized for agent parsing

Use --format json to get structured output that's easy to parse programmatically.

Exit Codes

All scripts use consistent exit codes:

  • 0: Success (no issues found, domain allowed, etc.)
  • 1: Issues found (blocked domains, failed checks, domain blocked)
  • 2: Error (missing logs, invalid arguments, etc.)

No Dependencies

All scripts use Python 3.8+ stdlib only. No pip install required. They work out of the box on any system with Python 3.8+.

Script Reference

parse-squid-logs.py

Purpose: Extract blocked domains from Squid logs with counts and statistics.

Key Options:

  • --blocked-only - Show only blocked domains
  • --domain DOMAIN - Filter by specific domain
  • --top N - Show top N domains by request count
  • --format {table,json} - Output format

Auto-discovers logs from running containers, preserved logs, or work directories.

diagnose-awf.py

Purpose: Run automated diagnostic checks and report issues with fixes.

Checks:

  • Container status (running/stopped/missing)
  • Container health (Squid healthcheck)
  • Network connectivity (Squid reachable from agent)
  • DNS configuration
  • Squid config validation
  • Common issues (port conflicts, orphaned containers)

Key Options:

  • --verbose - Show detailed check output
  • --format {text,json} - Output format
inspect-containers.py

Purpose: Show concise container status without verbose docker output.

Shows:

  • Container status and exit codes
  • IP addresses and network info
  • Health check status
  • Top 5 processes
  • Recent logs (last 5 lines)

Key Options:

  • --container NAME - Inspect specific container only
  • --logs-only - Show only recent logs
  • --tail N - Number of log lines (default: 5)
  • --format {text,json} - Output format
Show full SKILL.md (252 more words)Show less
test-domain.py

Purpose: Test if domain is reachable through the firewall.

Checks:

  • If domain is in Squid allowlist
  • If domain appears in recent Squid logs
  • Whether requests were allowed or blocked

Key Options:

  • --check-allowlist - Only check allowlist, don't check logs
  • --suggest-fix - Show suggested --allow-domains flag
  • --format {text,json} - Output format

Integration with Existing Skills

  • For manual debugging commands, see the debug-firewall skill
  • For MCP Gateway integration, see the awf-mcp-gateway skill
  • For general troubleshooting, see docs/troubleshooting.md

Performance

All scripts are designed for fast execution:

  • parse-squid-logs.py: <2 seconds for typical log files
  • diagnose-awf.py: <3 seconds for all checks
  • inspect-containers.py: <2 seconds for both containers
  • test-domain.py: <1 second for domain check

Examples

Example 1: Find Blocked Domains
bash
$ python .claude/skills/awf-debug-tools/scripts/parse-squid-logs.py --blocked-only

Blocked Domains (sorted by count):

  Domain                  Blocked  Allowed  Total
  =================================================
  registry.npmjs.org      45       0        45
  example.com             12       0        12

Total requests: 1234
Blocked: 57 (4.6%)
Allowed: 1177 (95.4%)
Example 2: Diagnose Issues
bash
$ python .claude/skills/awf-debug-tools/scripts/diagnose-awf.py

AWF Diagnostic Report
========================================
[✓] Containers: awf-squid (running), awf-agent (exited:0)
[✓] Health: Squid healthy
[✓] Network: awf-net exists ([{Subnet:172.30.0.0/24 Gateway:172.30.0.1}])
[✓] Connectivity: Squid reachable on 172.30.0.10:3128
[✓] DNS: DNS servers: 127.0.0.11, 8.8.8.8, 8.8.4.4
[✓] Config: 3 domains in allowlist (github.com, .github.com, api.github.com)

Summary: All checks passed ✓
Example 3: Test Domain
bash
$ python .claude/skills/awf-debug-tools/scripts/test-domain.py npmjs.org --suggest-fix

Testing: npmjs.org

[✗] Allowlist check: Not in allowlist
[✗] Reachability: Blocked (403 TCP_DENIED:HIER_NONE)
[✗] Status: BLOCKED

Suggested fix:
  awf --allow-domains github.com,npmjs.org 'your-command'

Tips for Agents

  1. Use JSON output for easy parsing: --format json | jq .
  2. Chain commands to get complete picture: diagnose → parse logs → test domain
  3. Check exit codes to determine if action needed (0 = ok, 1 = issues)
  4. Use --suggest-fix to get ready-to-use awf commands
  5. Scripts auto-discover logs - no need to specify paths in most cases

Troubleshooting

Script not found:

bash
# Use absolute path
python /home/mossaka/developer/gh-aw-repos/gh-aw-firewall/.claude/skills/awf-debug-tools/scripts/parse-squid-logs.py

Permission denied on logs:

bash
# Squid logs require sudo to read
sudo python .claude/skills/awf-debug-tools/scripts/parse-squid-logs.py --log-file /tmp/squid-logs-*/access.log

No logs found:

bash
# Run awf first to generate logs
sudo awf --allow-domains github.com 'curl https://api.github.com'

# Then parse
python .claude/skills/awf-debug-tools/scripts/parse-squid-logs.py

Future Enhancements

Planned scripts for future versions:

  • analyze-traffic.py - Analyze traffic patterns over time
  • generate-allowlist.py - Auto-generate allowlist from logs
  • cleanup-awf.py - Clean up orphaned resources
  • benchmark-awf.py - Performance testing utilities

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 6 other files (scripts) in .claude/skills/awf-debug-tools of github/gh-aw-firewall.

  • SKILL.md
  • scripts/.gitignore
  • scripts/common.py
  • scripts/diagnose-awf.py
  • scripts/inspect-containers.py
  • scripts/parse-squid-logs.py
  • scripts/test-domain.py

Open the folder on GitHubat commit 681e932

Compare with similar skills

Awf Debug Tools 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.

Awf Debug Tools compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Awf Debug Tools this skillgithub/gh-aw-firewall148—~2.6kAutomated safety check: NotesMIT
OpenROAD Issue TriageThe-OpenROAD-Project/OpenROAD3.2k—~842Automated safety check: PassBSD-3-Clause
Burla Parallel Dev ClustersBurla-Cloud/burla263—~1.6kAutomated safety check: PassCustom licence
Zizkadb Dev SetupZIZKA-AI-SL/ZizkaDB124—~535Automated safety check: NotesCustom licence
Debug Sessionai-dynamo/dynamo8.2k—~1.2kAutomated safety check: PassApache-2.0
Burla Internals Deep DiveBurla-Cloud/burla263—~2.4kAutomated safety check: PassCustom licence

Similar skills

  • OpenROAD Issue Triage

    The-OpenROAD-Project/OpenROAD

    Reproduces an OpenROAD GitHub bug from an attached tarball and shrinks the failing design with whittle.py so maintainers get a minimal test case.

    3.2k GitHub stars~842 tokensUpdated today
    DevelopmentAuto-check passed

  • Burla Parallel Dev Clusters

    Burla-Cloud/burla

    Sets up an isolated Burla dev cluster per git worktree so several agents can work in parallel, and explains when to use local-dev or remote-dev.

    263 GitHub stars~1.6k tokensUpdated 15 days ago
    DevelopmentAuto-check passed

  • Zizkadb Dev Setup

    ZIZKA-AI-SL/ZizkaDB

    Set up and start the local ZizkaDB development stack. An agent skill from ZIZKA-AI-SL/ZizkaDB.

    124 GitHub stars~535 tokensUpdated yesterday
    DevelopmentAuto-check: notes

  • Debug Session

    ai-dynamo/dynamo

    Sets up a structured debugging session for a Dynamo bug — pull the report from a Linear ticket, GitHub issue, or pasted text, capture the environment, create a persistent worklog markdown file, and…

    8.2k GitHub stars~1.2k tokensUpdated today
    DevelopmentAuto-check passed

  • Burla Internals Deep Dive

    Burla-Cloud/burla

    Reference for Burla internals: how a remote_parallel_map job flows between services, how clusters and nodes are managed, and where the head keeps its state.

    263 GitHub stars~2.4k tokensUpdated 15 days ago
    DevelopmentAuto-check passed

  • Flowfile Config and Flags Catalog

    Edwardvaneechoud/Flowfile

    Catalog of Flowfile's environment variables and runtime flags: what each does, where the code reads it, its default, and where the docs disagree with the code.

    370 GitHub stars~12k tokensUpdated yesterday
    DevelopmentAuto-check: notes

More from github/gh-aw-firewall

  • 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

  • Debugging Workflows

    github/gh-aw-firewall

    Official

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

    148 GitHub stars~2.7k 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 Awf Debug Tools

What does Awf Debug Tools do?

Practical Python scripts for debugging awf - parse logs, diagnose issues, inspect containers, test domains. Awf Debug Tools is an agent skill from github/gh-aw-firewall, published by the product's own GitHub organization.

When should I use Awf Debug Tools?

Awf Debug Tools fits situations like: tasks that involve Debugging.

How do I install Awf Debug Tools in Claude Code?

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

How do I install Awf Debug Tools in Codex?

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

Can I use Awf Debug Tools 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 awf-debug-tools -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/awf-debug-tools, .gemini/skills/awf-debug-tools, .github/skills/awf-debug-tools and .opencode/skills/awf-debug-tools in your project.

What does Awf Debug Tools need to run?

Going by SKILL.md and its folder, Awf Debug Tools needs Python for the scripts in its folder and the command-line tools its instructions call (python, jq and pip). Our summary lists: Python 3; Docker. Its frontmatter pre-approves these tools: Bash(python:*), Bash(docker:*), Bash(sudo:*), Read.

Does Awf Debug Tools 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 Awf Debug Tools 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. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Awf Debug Tools use?

Awf Debug Tools 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 Awf Debug Tools use?

About 2.6k tokens (SKILL.md is roughly 10k 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 Awf Debug Tools?

Skills that share tags, products or a category with Awf Debug Tools: OpenROAD Issue Triage (The-OpenROAD-Project/OpenROAD, 3.2k stars), Burla Parallel Dev Clusters (Burla-Cloud/burla, 263 stars), Zizkadb Dev Setup (ZIZKA-AI-SL/ZizkaDB, 124 stars) and Debug Session (ai-dynamo/dynamo, 8.2k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Awf Debug Tools?

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.