Universal Debug Mode Skill — AI skill for Claude Code

Debug Mode — an agent skill for evidence-driven debugging

An [Agent Skill](https://code.claude.com/docs/en/skills) that stops your AI agent from guessing at bugs.

Instead of reading source code and proposing a plausible-looking fix, the agent forms competing hypotheses, instruments your code with probes that stream to an isolated local log sink, asks you to reproduce the bug, and then **confirms or rejects each hypothesis against real runtime data** before changing a line. When the bug is gone, it removes every probe it added.

Inspired by Cursor's Debug Mode, rebuilt as a portable skill that runs anywhere — Claude Code, Cursor, or any agent that reads `SKILL.md`.

hypothesize → instrument → reproduce → read evidence → fix → verify → clean up

Why

The default failure mode of AI debugging is confident nonsense: the agent reads the code, pattern-matches to a familiar bug, and edits something. If the symptom disappears, everyone assumes it was the cause.

This skill makes that impossible by construction. **No fix may be proposed until a probe has produced runtime evidence confirming a specific hypothesis.** A rejected hypothesis is recorded as a result. A probe that never fires is treated as evidence that the code path did not execute — which is frequently the bug.

Install

Requires Python 3.8+ (standard library only — no pip, no dependencies).

**Claude Code** (personal skill, available in every project):

git clone https://github.com/heiets/universal-debug-mode-skill.git ~/.claude/skills/debug-mode

**One project only:**

git clone https://github.com/heiets/universal-debug-mode-skill.git .claude/skills/debug-mode

**Cursor / other agents:** clone anywhere and point the agent at `SKILL.md`, or copy the folder into whatever skills directory your tool uses. The skill is plain Markdown plus one Python CLI; nothing is Claude-specific.

Verify:

python3 ~/.claude/skills/debug-mode/scripts/debugctl.py --help

Use

D