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

Agent skill

Debug Mode

by MadAppGang in MadAppGang/claude-code

Enable, disable, and manage debug mode for agentdev sessions.

MITAuto-check passedDevelopment

Install Debug Mode

skills CLI
$ npx skills add MadAppGang/claude-code --skill debug-mode -a claude-code

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

GitHub CLI
$ gh skill install MadAppGang/claude-code debug-mode --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/MadAppGang/claude-code.git skills-src && mkdir -p .claude/skills && cp -r skills-src/plugins/agentdev/skills/debug-mode .claude/skills/debug-mode && 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
debug-mode
GitHub stars
283
Token cost
~2.6k tokens
SKILL.md length
611 words
Files
1
Skills in repo
69
Repo updated
First seen
Licence
MIT

At a glance

Enable, disable, and manage debug mode for agentdev sessions.

  • Works in 3 steps: Check if debug mode is enabled → Verify config file → Verify the directory is writable
  • Debugging agent behavior
  • SKILL.md covers Configuration, Enabling Debug Mode, Debug Levels and Output Location, plus 6 more sections
  • Calls jq, brew and apt-get

What it does

Debug Mode is an agent skill from MadAppGang/claude-code. Enable, disable, and manage debug mode for agentdev sessions. Records all tool invocations, skill activations, hook triggers, and agent delegations to JSONL. Use when debugging agent behavior, optimizing workflows, or analyzing session performance.

Its SKILL.md is about 2.6k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Development, covering Debugging. The repository describes itself as: claude code plugins marketplace. The licence is MIT.

When your agent uses it

  • Debugging agent behavior
  • Optimizing workflows
  • Analyzing session performance

Example prompts

  • “/debug-mode”

Workflow steps

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

  1. Check if debug mode is enabled
  2. Verify config file
  3. Verify the directory is writable

What it can do on your machine

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

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • jq
    • brew
    • apt-get
    • curl

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

  • Network

    No URLs in SKILL.md. Its commands use curl, which can reach the network depending on how they are called.

    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

Debug Mode loads about 2.6k tokens when it runs. Until then it costs about 65 tokens; SKILL.md has 611 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~65
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 passed

The automated check found no risky patterns in SKILL.md.

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 MadAppGang/claude-code at commit 6097ad4, republished under its MIT licence (© MadAppGang). 611 words, ~2,639 tokens.

Download SKILL.mdSave it as .claude/skills/debug-mode/SKILL.md (or your agent's skills folder).
name
debug-mode
description
Enable, disable, and manage debug mode for agentdev sessions. Records all tool invocations, skill activations, hook triggers, and agent delegations to JSONL. Use when debugging agent behavior, optimizing workflows, or analyzing session performance.

plugin: agentdev updated: 2026-01-20

AgentDev Debug Mode

Debug mode captures detailed session information for analysis, debugging, and optimization. All events are recorded to a JSONL file in claude-code-session-debug/.

Configuration

Debug mode uses per-project configuration stored in .claude/agentdev-debug.json.

Config File Format

Location: .claude/agentdev-debug.json (in project root)

json
{
  "enabled": true,
  "level": "standard",
  "created_at": "2026-01-09T07:00:00Z"
}

Fields:

  • enabled: boolean - Whether debug mode is active
  • level: string - Debug level (minimal, standard, verbose)
  • created_at: string - ISO timestamp when config was created

Enabling Debug Mode

Use the command to create the config file:

/agentdev:debug-enable

This creates .claude/agentdev-debug.json with enabled: true.

Or manually create the file:

bash
mkdir -p .claude
cat > .claude/agentdev-debug.json << 'EOF'
{
  "enabled": true,
  "level": "standard",
  "created_at": "2026-01-09T07:00:00Z"
}
EOF

Debug Levels

LevelCaptured Events
minimalPhase transitions, errors, session start/end
standardAll of minimal + tool invocations, agent delegations
verboseAll of standard + skill activations, hook triggers, full parameters

Default level is standard.

Changing Debug Level

Using jq:

bash
jq '.level = "verbose"' .claude/agentdev-debug.json > tmp.json && mv tmp.json .claude/agentdev-debug.json

Output Location

Debug sessions are saved to:

claude-code-session-debug/agentdev-{slug}-{timestamp}-{id}.jsonl

Example:

claude-code-session-debug/agentdev-graphql-reviewer-20260109-063623-ba71.jsonl

JSONL Format

Each line in the JSONL file is a complete JSON event object. This append-only format is:

  • Crash-resilient (no data loss on unexpected termination)
  • Easy to process with jq
  • Streamable during the session
Event Schema (v1.0.0)
json
{
  "event_id": "550e8400-e29b-41d4-a716-446655440001",
  "correlation_id": null,
  "timestamp": "2026-01-09T06:40:00Z",
  "type": "tool_invocation",
  "data": { ... }
}

Fields:

  • event_id: Unique UUID for this event
  • correlation_id: Links related events (e.g., tool_invocation -> tool_result)
  • timestamp: ISO 8601 timestamp
  • type: Event type (see below)
  • data: Type-specific payload
Event Types
TypeDescription
session_startSession initialization with metadata
session_endSession completion
tool_invocationTool called with parameters
tool_resultTool execution result
skill_activationSkill loaded by agent
hook_triggerPreToolUse/PostToolUse hook fired
agent_delegationTask delegated to sub-agent
agent_responseSub-agent returned result
phase_transitionWorkflow phase changed
user_interactionUser approval/input requested
proxy_mode_requestExternal model request via Claudish
proxy_mode_responseExternal model response
errorError occurred

What Gets Captured

Session Metadata
  • Session ID and path
  • User request
  • Environment (Claudish availability, plugin version)
  • Start/end timestamps
Tool Invocations
  • Tool name
  • Parameters (sanitized - credentials redacted)
  • Execution context (phase, agent)
  • Duration and result size
Agent Delegations
  • Target agent name
  • Prompt preview (first 200 chars)
  • Proxy mode model if used
  • Session path
Proxy Mode
  • Model ID
  • Request/response duration
  • Success/failure status
Phase Transitions
  • From/to phase numbers and names
  • Transition reason (completed, skipped, failed)
  • Quality gate results
Errors
  • Error type (tool_error, hook_error, agent_error, etc.)
  • Message and stack trace
  • Context (phase, agent, tool)
  • Recoverability

Sensitive Data Protection

Debug mode automatically sanitizes sensitive data:

Redacted Patterns:

  • API keys (sk-*, ghp_*, AKIA*, etc.)
  • Tokens (bearer, access, auth)
  • Passwords and secrets
  • AWS credentials
  • Slack tokens (xox*)
  • Google API keys (AIza*)
Show full SKILL.md (243 more words)Show less

Analyzing Debug Output

Prerequisites

Install jq for JSON processing:

bash
# macOS
brew install jq

# Linux
apt-get install jq
Quick Statistics
bash
# Count events by type
cat session.jsonl | jq -s 'group_by(.type) | map({type: .[0].type, count: length})'
Tool Usage Analysis
bash
# Tool invocation counts
cat session.jsonl | jq -s '
  [.[] | select(.type == "tool_invocation") | .data.tool_name]
  | group_by(.)
  | map({tool: .[0], count: length})
  | sort_by(-.count)'
Failed Operations
bash
# Find all errors and failed tool results
cat session.jsonl | jq 'select(.type == "error" or (.type == "tool_result" and .data.success == false))'
Timeline View
bash
# Chronological event summary
cat session.jsonl | jq '"\(.timestamp) [\(.type)] \(.data | keys | join(", "))"'
Event Correlation
bash
# Find tool invocation and its result
INVOCATION_ID="550e8400-e29b-41d4-a716-446655440001"
cat session.jsonl | jq "select(.event_id == \"$INVOCATION_ID\" or .correlation_id == \"$INVOCATION_ID\")"
Phase Duration Analysis
bash
# Calculate time between phase transitions
cat session.jsonl | jq -s '
  [.[] | select(.type == "phase_transition")]
  | sort_by(.timestamp)
  | .[]
  | {phase: .data.to_name, timestamp: .timestamp}'
Agent Delegation Timing
bash
# Find slowest agent delegations
cat session.jsonl | jq -s '
  [.[] | select(.type == "agent_response")]
  | sort_by(-.data.duration_ms)
  | .[:5]
  | .[]
  | {agent: .data.agent, duration_sec: (.data.duration_ms / 1000)}'
Proxy Mode Performance
bash
# External model response times
cat session.jsonl | jq -s '
  [.[] | select(.type == "proxy_mode_response")]
  | .[]
  | {model: .data.model_id, success: .data.success, duration_sec: (.data.duration_ms / 1000)}'

Disabling Debug Mode

Use the command:

/agentdev:debug-disable

Or manually update:

bash
jq '.enabled = false' .claude/agentdev-debug.json > tmp.json && mv tmp.json .claude/agentdev-debug.json

Or delete the config file:

bash
rm -f .claude/agentdev-debug.json

Cleaning Up Debug Files

Remove All Debug Files
bash
rm -rf claude-code-session-debug/
Remove Files Older Than 7 Days
bash
find claude-code-session-debug/ -name "*.jsonl" -mtime +7 -delete
Remove Files Larger Than 10MB
bash
find claude-code-session-debug/ -name "*.jsonl" -size +10M -delete

File Permissions

Debug files are created with restrictive permissions:

  • Directory: 0o700 (owner only)
  • Files: 0o600 (owner read/write only)

This prevents other users from reading potentially sensitive session data.

Example Session Output

jsonl
{"event_id":"init-1736408183","timestamp":"2026-01-09T06:36:23Z","type":"session_start","data":{"schema_version":"1.0.0","session_id":"agentdev-graphql-reviewer-20260109-063623-ba71","user_request":"Create an agent that reviews GraphQL schemas","session_path":"ai-docs/sessions/agentdev-graphql-reviewer-20260109-063623-ba71","environment":{"claudish_available":true,"plugin_version":"1.4.0","jq_available":true}}}
{"event_id":"550e8400-e29b-41d4-a716-446655440001","timestamp":"2026-01-09T06:36:25Z","type":"tool_invocation","data":{"tool_name":"TodoWrite","parameters":{"todos":"[REDACTED]"},"context":{"phase":0,"agent":null}}}
{"event_id":"550e8400-e29b-41d4-a716-446655440002","correlation_id":"550e8400-e29b-41d4-a716-446655440001","timestamp":"2026-01-09T06:36:25Z","type":"tool_result","data":{"tool_name":"TodoWrite","success":true,"result_size_bytes":156,"duration_ms":12}}
{"event_id":"550e8400-e29b-41d4-a716-446655440003","timestamp":"2026-01-09T06:36:26Z","type":"phase_transition","data":{"from_phase":null,"to_phase":0,"from_name":null,"to_name":"Init","transition_reason":"completed","quality_gate_result":true}}
{"event_id":"550e8400-e29b-41d4-a716-446655440004","timestamp":"2026-01-09T06:36:30Z","type":"agent_delegation","data":{"target_agent":"agentdev:architect","prompt_preview":"SESSION_PATH: ai-docs/sessions/agentdev-graphql-reviewer...","prompt_length":1456,"proxy_mode":null,"session_path":"ai-docs/sessions/agentdev-graphql-reviewer-20260109-063623-ba71"}}
{"event_id":"end-1736408565","timestamp":"2026-01-09T06:42:45Z","type":"session_end","data":{"success":true}}

Troubleshooting

Debug File Not Created

  1. Check if debug mode is enabled:

    bash
    /agentdev:debug-status

  2. Verify config file:

    bash
    cat .claude/agentdev-debug.json

  3. Verify the directory is writable:

    bash
    ls -la claude-code-session-debug/
jq Commands Not Working
  1. Install jq: brew install jq or apt-get install jq
  2. Verify JSONL format (each line should be valid JSON):
    bash
    head -1 session.jsonl | jq .
Large Debug Files

Debug files can grow large in verbose mode. Use minimal level for lighter capture:

Update config:

bash
jq '.level = "minimal"' .claude/agentdev-debug.json > tmp.json && mv tmp.json .claude/agentdev-debug.json

Or clean up old files regularly:

bash
find claude-code-session-debug/ -name "*.jsonl" -mtime +3 -delete

Integration with Other Tools

Viewing in VS Code

The JSONL format works with JSON syntax highlighting. For better viewing:

  1. Install "JSON Lines" VS Code extension
  2. Use "Format Document" on each line individually
Importing to Analytics
bash
# Convert to CSV for spreadsheet import
cat session.jsonl | jq -rs '
  (.[0] | keys_unsorted) as $keys
  | ($keys | @csv),
  (.[] | [.[$keys[]]] | @csv)' > session.csv
Streaming to External Service
bash
# Tail and send to logging service
tail -f session.jsonl | while read line; do
  curl -X POST -d "$line" https://logging.example.com/ingest
done

Commands Reference

CommandDescription
/agentdev:debug-enableEnable debug mode (creates config file)
/agentdev:debug-disableDisable debug mode (updates config file)
/agentdev:debug-statusCheck current debug mode status

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

Files

Just SKILL.md in plugins/agentdev/skills/debug-mode of MadAppGang/claude-code.

Open the folder on GitHubat commit 6097ad4

Compare with similar skills

Debug Mode 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.

Debug Mode compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Debug Mode this skillMadAppGang/claude-code283—~2.6kAutomated safety check: PassMIT
Trellis Session Insightmindfold-ai/Trellis15k4 repos~1.7kAutomated safety check: PassAGPL-3.0
Native Data FetchingCherryHQ/cherry-studio-app4k6 repos~2.9kAutomated safety check: NotesMIT
Aoti Debugpytorch/pytorch104k1 repos~1.7kAutomated safety check: PassCustom licence
Herdr Throwaway Reproductionherdrdev/herdr43k—~2.4kAutomated safety check: PassApache-2.0
Systematic Debuggingultralisp/ultralisp25851 repos~2.4kAutomated safety check: PassNone

Similar skills

  • Trellis Session Insight

    mindfold-ai/Trellis

    Reach into past AI conversation history through the trellis mem CLI.

    15k GitHub starsUsed in 4 repos~1.7k tokens
    DevelopmentAuto-check passed

  • Native Data Fetching

    CherryHQ/cherry-studio-app

    A skill your agent uses when implementing or debugging ANY network request, API call, or data fetching.

    4k GitHub starsUsed in 6 repos~2.9k tokens
    DevelopmentAuto-check: notes

  • Aoti Debug

    pytorch/pytorch

    Debug AOTInductor (AOTI) errors and crashes. An agent skill from pytorch/pytorch.

    104k GitHub starsUsed in 1 repo~1.7k tokens
    DevelopmentAuto-check passed

  • Herdr Throwaway Reproduction

    herdrdev/herdr

    Runs a disposable, uniquely named Herdr session inside an existing one so runtime, pane, terminal or API bugs can be reproduced without touching the main session.

    43k GitHub stars~2.4k tokensUpdated yesterday
    DevelopmentAuto-check passed

  • Systematic Debugging

    ultralisp/ultralisp

    A skill your agent uses when encountering any bug, test failure, or unexpected behavior, before proposing fixes

    258 GitHub starsUsed in 51 repos~2.4k tokens
    DevelopmentAuto-check passed

  • OpenLogi macOS Permissions Triage

    AprilNEA/OpenLogi

    Decides whether an OpenLogi device problem on macOS is a privacy-permission (TCC) problem, using agent log lines, and says which identity needs which grant.

    23k GitHub stars~2.5k tokensUpdated 4 days ago
    DevelopmentAuto-check: notes

More from MadAppGang/claude-code

All 69 skills in this repo

  • API Spec Analyzer

    MadAppGang/claude-code

    Analyzes API documentation from OpenAPI specs to provide TypeScript interfaces, request/response formats, and implementation guidance.

    283 GitHub starsUsed in 1 repo~2.7k tokens
    Auto-check passed

  • Content Brief

    MadAppGang/claude-code

    Content brief template and creation methodology for SEO-optimized content.

    283 GitHub starsUsed in 1 repo~959 tokens
    Auto-check passed

  • Context Detection

    MadAppGang/claude-code

    A skill your agent uses when detecting project technology stack from files/configs/directory structure, auto-loading framework-specific skills, or analyzing multi-stack fullstack projects (e.g…

    283 GitHub stars~5.4k tokensUpdated 6 mo ago
    Auto-check passed

  • Content Optimizer

    MadAppGang/claude-code

    On-page SEO optimization techniques including keyword density, meta tags, heading structure, and readability.

    283 GitHub starsUsed in 1 repo~694 tokens
    Auto-check passed

  • Keyword Cluster Builder

    MadAppGang/claude-code

    Techniques for expanding seed keywords and clustering by topic and intent.

    283 GitHub starsUsed in 1 repo~674 tokens
    Auto-check passed

  • Serp Analysis

    MadAppGang/claude-code

    SERP analysis techniques for intent classification, feature identification, and competitive intelligence.

    283 GitHub starsUsed in 1 repo~1k tokens
    Auto-check passed

Categories

Questions about Debug Mode

What does Debug Mode do?

Enable, disable, and manage debug mode for agentdev sessions. Debug Mode is an agent skill from MadAppGang/claude-code. Enable, disable, and manage debug mode for agentdev sessions.

When should I use Debug Mode?

Debug Mode fits situations like: debugging agent behavior; optimizing workflows; analyzing session performance.

How do I install Debug Mode in Claude Code?

Run `npx skills add MadAppGang/claude-code --skill debug-mode -a claude-code`. Or copy the skill folder (plugins/agentdev/skills/debug-mode in MadAppGang/claude-code) into .claude/skills/debug-mode in your project. Claude Code loads it when a task matches its description.

How do I install Debug Mode in Codex?

Run `npx skills add MadAppGang/claude-code --skill debug-mode -a codex`. Or copy the skill folder (plugins/agentdev/skills/debug-mode in MadAppGang/claude-code) into .agents/skills/debug-mode in your project. Codex loads it when a task matches its description.

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

What does Debug Mode need to run?

Going by SKILL.md and its folder, Debug Mode needs the command-line tools its instructions call (jq, brew, apt-get and curl).

Does Debug Mode access the network?

SKILL.md contains no URLs. Its commands use curl, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Debug Mode safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Debug Mode use?

Debug Mode 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 Debug Mode use?

About 2.6k 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 Debug Mode?

Skills that share tags, products or a category with Debug Mode: Trellis Session Insight (mindfold-ai/Trellis, 15k stars), Native Data Fetching (CherryHQ/cherry-studio-app, 4k stars), Aoti Debug (pytorch/pytorch, 104k stars) and Herdr Throwaway Reproduction (herdrdev/herdr, 43k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Debug Mode?

MadAppGang (a GitHub organization) maintains it in MadAppGang/claude-code, which has 283 GitHub stars. The repository holds 69 skills in this directory. The repository was last updated on March 15, 2026.

Source: MadAppGang/claude-code on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.