debugging

A project-specific guide for investigating failed tests, runtime errors, and unexpected command-line behavior. It lists pytest debugging options, logging approaches, and common ways to inspect provider and CLI failures.

In plain words
What is it for?
Use it to debug pytest failures, inspect provider responses, trace command-line workflows, run dry runs, or view the prompt sent to a language model.
Why use it?
It provides repeatable ways to expose more failure details, stop at the first problem, enter the debugger, or inspect the prompt and local values. This shortens the path from an error message to its cause.

Skill for Claude CodeCodex

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add skills/thomwebb/gac/debugging
Any agent
npx skills add thomwebb/gac --skill debugging
Clone the repo
git clone --depth 1 https://github.com/thomwebb/gac

Made for: Claude Code, Codex.

Per session 31 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 846 The whole file, excluding the scripts and references it only reads on demand.
Security scan C 1 finding. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.00031 $0.00846
Opus 5 $0.00015 $0.00423
Sonnet 5 $0.00006 $0.00169
Haiku 4.5 $0.00003 $0.00085

Measured yesterday against content hash a3553dbb07e8, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade C, and why

debugging scanned grade C with 1 finding against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured yesterday.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Harvests environment variableshighData exfiltration

Enumerating or grepping the environment for keys collects credentials unrelated to what the mod says it does.

uv run python -c "import os; print({k:v for k,v in os.environ.items() if k.startswith('GAC_')})"
.skills/debugging/SKILL.md · 129 lines

How it starts

The opening of the file, as written. The whole thing — 129 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Debugging Workflows

When to Use

  • Tests are failing and you need to understand why
  • Runtime errors occur in CLI operation
  • Provider responses are unexpected
  • Need to trace code execution flow

Test Debugging

uv run -- pytest tests/test_cli.py -v       # Verbose
uv run -- pytest tests/test_cli.py -vv      # Extra verbose
uv run -- pytest tests/test_cli.py -s       # Show print statements
uv run -- pytest tests/test_cli.py -x       # Stop on first failure
uv run -- pytest tests/test_cli.py --pdb    # Debugger on failure
uv run -- pytest tests/test_cli.py --tb=long    # Full traceback
uv run -- pytest tests/test_cli.py --showlocals  # Local variables

Provider Test Debugging

# Run specific mocked test
uv run -- pytest tests/providers/test_openai.py::TestOpenAIProviderMocked::test_successful_api_call -vvv

# API key validation tests
uv run -- pytest tests/providers/test_openai.py -k "APIKey" -v

Note: The standard mocked test is test_successful_api_call (NOT test_successful_call).

CLI Debugging

# Dry run with verbose
gac --dry-run -v

# Message only (no commit)
gac --dry-run --message-only

# Show the prompt sent to LLM
gac --show-prompt --dry-run

# Enable debug logging
GAC_LOG_LEVEL=DEBUG uv run python -m gac.cli --dry-run -v

# Or via CLI flag
uv run python -m gac.cli --log-level DEBUG --dry-run

Note: There is NO GAC_DEBUG env var. Use GAC_LOG_LEVEL=DEBUG or --log-level DEBUG.

Checking Configuration

# Check which model/provider is configured
uv run python -c "import os; print({k:v for k,v in os.environ.items() if k.startswith('GAC_')})"

# Check stats file location
uv run python -c "from gac.stats.store import STATS_FILE; print(STATS_FILE)"

# Check OAuth token storage
uv run python -c "from gac.oauth.token_store import TOKEN_DIR; print(TOKEN_DIR)"

Stats Debugging (safe)

Always mock stats paths when debugging outside pytest:

from unittest.mock import patch
import tempfile
from pathlib import Path

with tempfile.TemporaryDirectory() as tmpdir:
    with patch("gac.stats.store.STATS_FILE", Path(tmpdir) / "debug.json"):
        from gac.stats import save_stats
        save_stats({"model": "test"})  # safe — writes to temp

Read the full file on GitHub · 129 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. yesterday First seen · 129 lines · 31 tokens per session scan C a3553dbb07e8

Subscribe to this mod's changes

debugging is a skill published in the GitHub repository thomwebb/gac (318 stars, last pushed 4d ago), licensed MIT. It adds 31 tokens to every session and 846 once invoked, about $0.0002 per session on Opus 5. A static security scan graded it C with 1 finding (harvests environment variables). No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.

Related

Other skills, from other repositories

debugging

Systematically diagnose and fix bugs using structured debugging techniques. Use when investigating errors, unexpected behavior, failing tests, or production issues.

asgarovf/locusai · 29 tokens

log-triage

CI/build/runtime error log analysis with root-cause detection, prioritized fix plans, and verification checklists.

XSpoonAi/spoon-awesome-skill · 25 tokens

greptimedb-development-docker-image

Builds a development-only GreptimeDB Docker image from a local debug binary for local-cluster testing, and optionally pushes it to a development registry. Use when the user asks to package, build, tag, publish, or cross-build a non-release GreptimeDB or GreptimeDB Enterprise image for debugging.

GreptimeTeam/greptimedb · 71 tokens

greptimedb-fuzz-ci-failure-investigation

Investigate a failed GreptimeDB fuzz CI target link by downloading GitHub Actions job logs plus fuzz artifacts such as kind logs, monitor dumps, and CSV dumps, then correlate the failure with local GreptimeDB source code. Use when the user provides a failed fuzz CI target/job URL or asks to diagnose GreptimeDB fuzz CI…

GreptimeTeam/greptimedb · 80 tokens

greptimedb-release-note

Generate a GreptimeDB release changelog with git cliff (correct range, subtract already-released patch PRs, rebuild contributors, add human-curated highlights), output to a file, and prepare the docs-repo blog PR. Use when asked to write/generate a GreptimeDB release note or changelog.

GreptimeTeam/greptimedb · 70 tokens

greptimedb-release

Runbook for publishing a new GreptimeDB version (tag + GitHub release + docs release-note PR) on the upstream GreptimeTeam/greptimedb repo. Use when asked to "release" / "publish" a GreptimeDB version (e.g. v1.1.0, v1.0.3).

GreptimeTeam/greptimedb · 75 tokens