Debug Mode skill
A debugging skill built on hypotheses: the agent adds logs, reproduces the bug itself, tests its guesses and cleans up
- 119 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The agent edits project code and temporarily adds logging to it.
- Logs may capture request data, so keep `.agents/debug.log` out of the repository.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/debug-modeDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The agent edits project code and temporarily adds logging to it.
- Logs may capture request data, so keep `.agents/debug.log` out of the repository.
This is third-party code. Review the repository files before installing.
What it does
The `debug-mode` skill brings the idea of Cursor's debug mode to Claude Code, Codex and Gemini CLI. The agent gathers the bug report, forms 3 to 5 testable hypotheses, adds logs inside `#region DEBUG` blocks and reproduces the bug itself with a test, a command or an HTTP request. If that fails, it asks you to repeat the scenario. Logs go to `.agents/debug.log` by absolute path rather than to the terminal and carry `[DEBUG H1]`, `[DEBUG H2]` tags tied to hypotheses. The fix stays minimal, the agent repeats the reproduction and removes all debug markup only after confirmation.
Who it is for. Developers fighting a bug with no obvious cause: intermittent, environment-dependent or invisible in the console.
Good fit when
- A page stays blank after a form submit while the console is clean.
- An API returns 200 with no data and the cause is unknown.
- A bug appears rarely, so logs are placed in advance and you wait for a repeat.
- The code runs on a device that cannot write to the project folder: logs are collected there and copied to the agent.
Not a fit when
- The cause is visible from a stack trace or a compiler message.
- You need a style change or refactoring with no bug.
- The repository must not hold temporary logs even during debugging.
Example request
/debug-mode The login page is blank after clicking submit and the console shows no errors.Limitations
The author describes the skill as a tool for hard cases only: it does not activate on its own and waits for an explicit `/debug-mode`. In Claude Code the `SKILL.md` file must sit exactly one level below `~/.claude/skills/`, otherwise the skill silently fails to load, so after cloning the `debug-mode` folder is moved up. The agent needs permission to write the log to `.agents/debug.log`. `#region DEBUG` markers target the languages and comment syntaxes listed in the README.
How to disable. For Claude Code run `rm -rf ~/.claude/skills/debug-mode`, for Codex delete `~/.codex/skills/claude-code-debug-mode`. In Gemini CLI use `gemini skills uninstall debug-mode`.
FAQ
Why does the skill not load in Claude Code after cloning?
Claude Code scans only direct subfolders of `~/.claude/skills/`. Move `debug-mode` up one level so `SKILL.md` sits in `~/.claude/skills/debug-mode/`.
Where do debug logs go?
To `.agents/debug.log` by absolute path. The terminal stays clean and the agent context does not overflow.
What if the bug reproduces rarely?
Ask the agent to add the logs up front and keep working. When the bug happens, hand it the collected log for analysis.
How do I verify the installation?
Run `ls ~/.claude/skills/debug-mode/SKILL.md` for Claude Code or `gemini skills list` for Gemini CLI. If the file exists, the skill is ready.
Which languages does the markup work with?
JavaScript, TypeScript, Java, C#, Go, Rust, C, C++, Python, Ruby, Shell, YAML, HTML, Vue, Svelte and Lua. The marker form depends on comment syntax.
Discussion
No questions or reviews yet.
Related
Skills14 skills that find the gaps in a task before the code: interviews, plans, assumption tests and proof that a bug fix works
Over twenty skills for coding agents: MCP and hooks, plan mode, a bug-fix protocol, prompting and a bash safety hook
A debugging tool for Claude Code that reads the session logs already saved on disk and shows exact file paths, diffs, model thinking and a category-by-category
A 2.4 KB charter for CLAUDE.md and three on-demand skills: the agent stops guessing, verifies results and gates irreversible steps
The dbg debugger CLI for AI agents: breakpoints, steps and variables through short @ref handles instead of print debugging
A Claude Code working configuration: a planner with per-milestone review, sub-agents and skills for analysis, refactoring and docs sync
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Debug Mode (this card) | no | 119 | ||
| debug-that | no | 159 | that one uses a dbg debugger with breakpoints; Debug Mode works with logs and hypotheses, no debugger | |
| Claude Debugs For You | no | not required | 514 | that card attaches the editor debugger over MCP; here a skill runs the hypothesis and log loop |
README in short
Installation is one `npx skills add` command or a clone into the target agent's skills folder. The marker form follows the file's comment syntax.
README badge
Original SKILL.md
---
name: debug-mode
description: Interactive debugging mode that generates hypotheses, instruments code with runtime logs, and iteratively fixes bugs via autonomous reproduce-analyze loops, with human help only as a fallback. Only for hard-to-diagnose bugs; in those cases, remind the user that debug-mode is available, and never proactively activate this skill.
---
# Debug Mode
You are in **Debug Mode** — a hypothesis-driven debugging workflow. Do NOT jump to fixes. Follow each phase in order.
---
## Phase 1: Understand the Bug
Ask the user (if not already provided): expected vs actual behavior, reproduction steps, error messages.
Read the relevant source code. Understand the call chain and data flow.
## Phase 2: Generate Hypotheses
Generate **testable hypotheses** as a numbered list:
```
Based on my analysis, here are my hypotheses:
1. **[Title]** — [What might be wrong and why]
2. **[Title]** — [Explanation]
3. **[Title]** — [Explanation]
```
Include both obvious and non-obvious causes (race conditions, off-by-one, stale closures, type coercion, etc.).
Manual reproduction fatigues users—especially after 3+ rounds without finding the root cause. Include sufficiently detailed and reasonable debug information upfront to minimize reproduction cycles.
## Phase 3: Instrument the Code
### Log file & Evidence Collection
Write to **`{project_root}/.agents/debug.log`** using an absolute path by default.
**`project_root` = hardcoded constant string** inferred from context (file paths in the conversation). PROHIBITED: `import.meta.dir`, `__dirname`, `process.cwd()`, `Deno.cwd()`, `path.resolve()` or any runtime detection. Exception: remote/CI environments or non-writable local filesystem — use `/tmp/.agents/debug.log` instead.
Before each reproduction: create `.agents/` if needed. If `.agents/debug.log` exists and is non-empty, **archive it first** (rename to `debug-1.log`, `debug-2.log`, etc., incrementing sequentially) before resetting `debug.log` to empty, preserving historical logs.
Server-side: file-append API (`fs.appendFileSync`, `open("a")`, etc.). Browser-side: `fetch` POST to a debug API route. **Must work in all environments** (dev/release).
**Adapt for non-standard environments & intermittent bugs (Evidence over Ritual):**
- **Restricted/remote/mobile runtimes:** If the code runs on mobile, embedded, or remote environments that cannot write to the project root, adapt the log destination (e.g. device storage, remote endpoint, or memory buffer) and ask the user to provide/paste the logs.
- **Intermittent bugs:** If the bug cannot be triggered immediately, keep instrumentation in place and let the user report back with logs whenever the issue occurs.