Agent skill

Debug Mode

by doraemonkeys in doraemonkeys/claude-code-debug-mode

Interactive debugging mode that generates hypotheses, instruments code with runtime logs, and iteratively fixes bugs with human-in-the-loop verification.

MITAuto-check passedDevelopment

Install Debug Mode

skills CLI

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

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

GitHub CLI

$ gh skill install doraemonkeys/claude-code-debug-mode 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/doraemonkeys/claude-code-debug-mode.git skills-src && mkdir -p .claude/skills && cp -r skills-src/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/

Paste into Claude Code

Install the "debug-mode" agent skill from https://github.com/doraemonkeys/claude-code-debug-mode/tree/master/debug-mode into .claude/skills/debug-mode/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "debug-mode", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/doraemonkeys/claude-code-debug-mode/tree/master/debug-mode

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add doraemonkeys/claude-code-debug-mode --skill debug-mode -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install doraemonkeys/claude-code-debug-mode debug-mode --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/doraemonkeys/claude-code-debug-mode.git skills-src && mkdir -p .agents/skills && cp -r skills-src/debug-mode .agents/skills/debug-mode && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "debug-mode" agent skill from https://github.com/doraemonkeys/claude-code-debug-mode/tree/master/debug-mode into .agents/skills/debug-mode/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "debug-mode", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add doraemonkeys/claude-code-debug-mode --skill debug-mode -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install doraemonkeys/claude-code-debug-mode debug-mode --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/doraemonkeys/claude-code-debug-mode.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/debug-mode .cursor/skills/debug-mode && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "debug-mode" agent skill from https://github.com/doraemonkeys/claude-code-debug-mode/tree/master/debug-mode into .cursor/skills/debug-mode/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "debug-mode", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/doraemonkeys/claude-code-debug-mode.git --path debug-mode

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add doraemonkeys/claude-code-debug-mode --skill debug-mode -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install doraemonkeys/claude-code-debug-mode debug-mode --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/doraemonkeys/claude-code-debug-mode.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/debug-mode .gemini/skills/debug-mode && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "debug-mode" agent skill from https://github.com/doraemonkeys/claude-code-debug-mode/tree/master/debug-mode into .gemini/skills/debug-mode/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "debug-mode", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install doraemonkeys/claude-code-debug-mode debug-mode

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add doraemonkeys/claude-code-debug-mode --skill debug-mode -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/doraemonkeys/claude-code-debug-mode.git skills-src && mkdir -p .github/skills && cp -r skills-src/debug-mode .github/skills/debug-mode && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "debug-mode" agent skill from https://github.com/doraemonkeys/claude-code-debug-mode/tree/master/debug-mode into .github/skills/debug-mode/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "debug-mode", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add doraemonkeys/claude-code-debug-mode --skill debug-mode -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install doraemonkeys/claude-code-debug-mode debug-mode --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/doraemonkeys/claude-code-debug-mode.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/debug-mode .opencode/skills/debug-mode && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "debug-mode" agent skill from https://github.com/doraemonkeys/claude-code-debug-mode/tree/master/debug-mode into .opencode/skills/debug-mode/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "debug-mode", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: debug-mode
GitHub stars: 117
Token cost: ~1.3k tokens
SKILL.md length: 559 words
Files: 1
Skills in repo: 1
Repo updated: Sep 2, 2026
First seen: Oct 7, 2026
Licence: MIT

At a glance

Interactive debugging mode that generates hypotheses, instruments code with runtime logs, and iteratively fixes bugs with human-in-the-loop verification.

Works in 6 steps: Understand the Bug → Generate Hypotheses → Instrument the Code → …
Tasks that involve Debugging
SKILL.md covers Phase 1: Understand the Bug, Phase 2: Generate Hypotheses, Phase 3: Instrument the Code and Phase 4: Analyze Logs & Diagnose, plus 3 more sections
Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Debug Mode is an agent skill from doraemonkeys/claude-code-debug-mode. Interactive debugging mode that generates hypotheses, instruments code with runtime logs, and iteratively fixes bugs with human-in-the-loop verification. Only for hard-to-diagnose bugs; in those cases, remind the user that debug-mode is available, and never proactively activate this skill.

Its SKILL.md is about 1.3k 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 and Human-in-the-loop approvals. The repository describes itself as: Cursor-style Debug Mode skill for coding agents. Hypothesis-driven debugging with runtime log instrumentation and human-in-the-loop verification. The licence is MIT.

When your agent uses it

Tasks that involve Debugging
Tasks that involve Human-in-the-loop approvals

Example prompts

“/debug-mode”

Workflow steps

6 steps, taken from the step headings in SKILL.md.

Understand the Bug
Generate Hypotheses
Instrument the Code
Analyze Logs & Diagnose
Generate a Fix
Verify & Clean Up

What it can do on your machine

Read from SKILL.md and the folder at commit c34f9e3. 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
No scripts in the folder and no shell commands in SKILL.md.
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md.
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 1.3k tokens when it runs. Until then it costs about 75 tokens; SKILL.md has 559 words of instructions outside code blocks.

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

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 doraemonkeys/claude-code-debug-mode at commit c34f9e3, republished under its MIT licence (© doraemonkeys). 559 words, ~1,256 tokens.

Download SKILL.mdSave it as .claude/skills/debug-mode/SKILL.md (or your agent's skills folder).

name: debug-mode
description: Interactive debugging mode that generates hypotheses, instruments code with runtime logs, and iteratively fixes bugs with human-in-the-loop verification. 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.).

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.

Region markers

ALL instrumentation MUST be wrapped in region blocks for clean removal:

// #region DEBUG       (JS/TS/Java/C#/Go/Rust/C/C++)
# #region DEBUG        (Python/Ruby/Shell/YAML)
<!-- #region DEBUG --> (HTML/Vue/Svelte)
-- #region DEBUG       (Lua)

...instrumentation...

// #endregion DEBUG    (matching closer)

Logging rules

NEVER use console.log、print or any stdout/stderr output. All debug output MUST go to debug.log — server-side via file-append, browser-side via fetch to a debug API endpoint.
Log messages include hypothesis number: [DEBUG H1], [DEBUG H2], etc.
Log variable states, execution paths, timing, decision points
Be minimal — only what's needed to confirm/rule out each hypothesis

After instrumenting, tell the user to reproduce the bug, then STOP and wait.

Show full SKILL.md (226 more words)Show less

Phase 4: Analyze Logs & Diagnose

When the user has reproduced:

Check log file size first (e.g. wc -l or ls -lh). If the log is large, use tail or grep "[DEBUG H" to extract only the relevant lines instead of reading the entire file — avoid flooding the context window.
Map logs to hypotheses — determine which are confirmed vs ruled out
Present diagnosis with evidence:

## Diagnosis

**Root cause**: [Explanation backed by log evidence]

Evidence:
- [H1] Ruled out — [why]
- [H2] Confirmed — [log evidence]

If inconclusive: new hypotheses → more instrumentation → archive & reset log → ask user to reproduce again.

Phase 5: Generate a Fix

Write a fix. Keep debug instrumentation in place.

Archive and reset .agents/debug.log, ask user to verify the fix works, then STOP and wait.

Phase 6: Verify & Clean Up

If fixed: Remove all #region DEBUG blocks and contents (use Grep to find them), delete all .agents/debug*.log files (including archived logs), summarize.

If NOT fixed: Read new logs, ask what they observed, return to Phase 2, iterate.

Rules

Never skip phases. Instrument and verify even if you think you know the answer.
Never remove instrumentation before user confirms the fix.
Never use console.log、print etc. Route all debug output to {project_root}/.agents/debug.log (or adapt the transport if runtime constraints require it).
Always archive existing logs and reset debug.log before each reproduction.
Always wrap instrumentation in #region DEBUG blocks.
Always wait for the user after asking them to reproduce (or when waiting for intermittent occurrences).

Files

Just SKILL.md in debug-mode of doraemonkeys/claude-code-debug-mode.

Open the folder on GitHubat commit c34f9e3

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
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Debug Mode this skilldoraemonkeys/claude-code-debug-mode	117	—	~1.3k	Automated safety check: Pass	MIT	1 mo ago
Debugging Devtools Extensionsflutter/devtools	1.7k	—	~839	Automated safety check: Pass	BSD-3-Clause	today
iOS ImplementMacMagazine/app-iOS	171	—	~741	Automated safety check: Pass	None	today
Refactorsd0xdev/sd0x-harness	192	—	~3k	Automated safety check: Notes	MIT	today
Bug Fixsd0xdev/sd0x-harness	192	—	~1.4k	Automated safety check: Notes	MIT	today
PUA High-Agency Governance for Traetanweai/pua	20k	—	~878	Automated safety check: Pass	MIT	29 days ago

Similar skills

Debugging Devtools Extensions
flutter/devtools
Guidelines and step-by-step workflow for debugging DevTools extensions locally, including stub mode, fixed-port launching, browser auto-opening, URL query parameters, target app connection, and…
1.7k GitHub stars~839 tokensUpdated today
DevelopmentAuto-check passed
iOS Implement
MacMagazine/app-iOS
Complete feature-implementation workflow for MacMagazine with pattern matching, review gates, and quality verification.
171 GitHub stars~741 tokensUpdated today
DevelopmentAuto-check passed
Refactor
sd0xdev/sd0x-harness
Multi-target refactoring orchestrator. An agent skill from sd0xdev/sd0x-harness.
192 GitHub stars~3k tokensUpdated today
DevelopmentAuto-check: notes
Bug Fix
sd0xdev/sd0x-harness
Bug fix workflow. An agent skill from sd0xdev/sd0x-harness.
192 GitHub stars~1.4k tokensUpdated today
DevelopmentAuto-check: notes
PUA High-Agency Governance for Trae
tanweai/pua
An instruction-only discipline for Trae that forces evidence-based work when an agent keeps failing, gives up or declares a task finished without proof.
20k GitHub stars~878 tokensUpdated 29 days ago
Agent WorkflowsAuto-check passed
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

Questions about Debug Mode

What does Debug Mode do?

Interactive debugging mode that generates hypotheses, instruments code with runtime logs, and iteratively fixes bugs with human-in-the-loop verification. Debug Mode is an agent skill from doraemonkeys/claude-code-debug-mode. Interactive debugging mode that generates hypotheses, instruments code with runtime logs, and iteratively fixes bugs with human-in-the-loop verification.

When should I use Debug Mode?

Debug Mode fits situations like: tasks that involve Debugging; tasks that involve Human-in-the-loop approvals.

How do I install Debug Mode in Claude Code?

Run `npx skills add doraemonkeys/claude-code-debug-mode --skill debug-mode -a claude-code`. Or copy the skill folder (debug-mode in doraemonkeys/claude-code-debug-mode) 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 doraemonkeys/claude-code-debug-mode --skill debug-mode -a codex`. Or copy the skill folder (debug-mode in doraemonkeys/claude-code-debug-mode) 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 doraemonkeys/claude-code-debug-mode --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?

SKILL.md names no scripts, command-line tools or credentials: Debug Mode is instructions for the agent only.

Does Debug Mode access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. 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 1.3k tokens (SKILL.md is roughly 5k 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: Debugging Devtools Extensions (flutter/devtools, 1.7k stars), iOS Implement (MacMagazine/app-iOS, 171 stars), Refactor (sd0xdev/sd0x-harness, 192 stars) and Bug Fix (sd0xdev/sd0x-harness, 192 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Debug Mode?

doraemonkeys (a GitHub user) maintains it in doraemonkeys/claude-code-debug-mode, which has 117 GitHub stars. The repository was last updated on September 2, 2026.

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

Install Debug Mode

Facts

At a glance

What it does

When your agent uses it

Example prompts

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

Debug Mode

Phase 1: Understand the Bug

Phase 2: Generate Hypotheses

Phase 3: Instrument the Code

Log file & Evidence Collection

Region markers

Logging rules

Phase 4: Analyze Logs & Diagnose

Phase 5: Generate a Fix

Phase 6: Verify & Clean Up

Rules

Files

Compare with similar skills

Similar skills

Debugging Devtools Extensions

iOS Implement

Refactor

Bug Fix

PUA High-Agency Governance for Trae

Trellis Session Insight

Related

Questions about Debug Mode