agentleFS
MicrosoftKnown publishermicrosoft/DebugMCP/skills/debug-live/SKILL.md

debug-live

Skill579 starsChanged 9 months agoMITView on GitHub

Guides root-cause investigations with debugging capabilities by setting breakpoints, starting a debug session, stepping through execution, inspecting variables, and tracing symptoms back to their origin. Prefer it for runtime bugs, failing tests, exceptions, crashes, hangs, wrong/null values, and unexpected output when live inspection is practical. Use this skill instead of modifying source code with temporary logs, print statements, or console output.

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    1. jakkarin-promsee/my-harness★ 1same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repositoryOne other file it gives its agents.

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 3 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Set a starting breakpoint: Use add_breakpoint with the file path and the 1-based line number you want to pause on.

    line 51
  2. Very specific:

    Start the session: Call start_debugging with the source file path.

    line 56
  3. Very specific:

    Navigate and inspect: Use step_over, step_into, step_out, continue_execution to move through code.

    line 61
  4. Very specific:

    Use list_variable_names to see what is in scope (names and types only, no values), then get_variables_values with the specific …

    line 64
  5. Very specific:

    Clean up: Call clear_all_breakpoints when you're done so you don't pollute the next session, and stop_debugging if the session is still …

    line 75
  6. Distinctive:

    When you encounter an issue during debugging (null variable, unexpected value, thrown error, wrong branch taken), apply this systematic …

    line 84
  7. Distinctive:

    Repeat until you reach the origin: Keep asking "why" until you hit a fundamental cause — usually where data enters the system, a config is …

    line 102
  8. Distinctive:

    Before ending the debug session, confirm you can answer:

    line 163
  9. Very specific:

    Prefer logpoints for loops/hot paths: When you want to observe how a value evolves across many iterations without stopping, use …

    line 180

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

DebugMCP — Interactive Debugging Skill

This skill teaches an agent how to use the DebugMCP MCP server effectively. The MCP server itself exposes only tools (with brief, behavioral descriptions); the workflow, root cause analysis framework, and language-specific guidance live here.

The allowed-tools list above uses the tool names registered by the DebugMCP MCP server. Some runtimes namespace MCP tools (e.g. mcp__debugmcp__start_debugging); adapt as needed.


When to invoke this skill

Invoke this skill as the first investigation step whenever you would otherwise guess at runtime behavior:

  • Any reported bug, failing test, exception, or unexpected output.
  • A variable holds an unexpected null / undefined / wrong type / wrong value.
  • A function returns something the caller didn't expect.
  • A code path executes (or fails to execute) when you didn't predict it would.
  • You're about to read a large amount of code "trying to figure out what happens at runtime."

Core workflow

  1. Set a starting breakpoint. Use add_breakpoint with the file path and the 1-based line number you want to pause on. Place it at the earliest point that's still relevant to the suspected issue.
  2. Optionally add strategic breakpoints. Decision points, error-handling branches, data boundaries (where input enters, where output is produced).
  3. Start the session. Call start_debugging with the source file path. For a single test, pass testName; the server routes through VS Code's Testing API so test runners like dotnet test / pytest / jest work correctly. The call returns when the program either hits a breakpoint (stopped) or runs to completion without pausing (terminated).
  4. Navigate and inspect. Use step_over, step_into, step_out, continue_execution to move through code. Use pause_execution to interrupt a freely-running program (e.g. a busy loop or embedded target) when there is no breakpoint to stop at. Use list_variable_names to see what is in scope (names and types only, no values), then get_variables_values with the specific variableNames you care about, and evaluate_expression to test hypotheses live (call methods, read properties, run list comprehensions, etc.).

    get_variables_values requires explicit variableNames — it will not dump the whole scope. This is deliberate: a scope dump hands you unrelated process state such as API keys, tokens and environment variables. Values that still look like credentials are replaced with <redacted: possible secret>; don't try to work around it.

  5. Find the root cause (see framework below). Don't stop at the first wrong thing you see — trace it back to why.
  6. Clean up. Call clear_all_breakpoints when you're done so you don't pollute the next session, and stop_debugging if the session is still active.

🚨 Root cause analysis framework

Never stop at symptoms — always find the root cause

When you encounter an issue during debugging (null variable, unexpected value, thrown error, wrong branch taken), apply this systematic approach.

Symptom vs root cause

  • Symptom: what you observed is wrong (e.g. "variable user is null").
  • Root cause: why the symptom occurred (e.g. "user is null because getUserById() returned null because the DB query failed because the connection string in appsettings.json points at the wrong host").

Investigation process

  1. Identify the symptom. What exactly is wrong? Which line, which variable, which thrown exception? Record the current state.
  2. Ask "why?" Why is this value wrong? Why did this function return this? Why did this condition evaluate this way?
  3. Trace backwards. Set a breakpoint before the symptom, restart, and step forward to watch where the wrong state first appears.
  4. Repeat until you reach the origin. Keep asking "why" until you hit a fundamental cause — usually where data enters the system, a config is read, or an assumption is first violated.

⚠️ Warning signs you're stopping too early

  • You found a null / undefined variable but didn't check why it's that way.
  • You see an error but didn't trace where it originates.
  • You identified "bad data" but didn't find why the data is bad.
  • You found a failing condition but didn't check why it fails.

✅ Signs you've found the root cause

  • You can explain the complete chain from root cause → symptom.
  • Fixing this one thing would prevent the symptom from occurring.
  • The issue is at a fundamental level (data input, configuration, logic invariant).
  • You understand not just what is wrong but why it's wrong.

Practical examples

Example 1 — Null variable

❌ Symptom-only: "The user object is null on line 45." ✅ Root cause: "user is null because getUserById() returned null because the DB query failed because the connection string is incorrect in the configuration file."

Investigation:

  1. user is null → set breakpoint in getUserById().
  2. getUserById() returns null → set breakpoint inside the function.
  3. DB query fails → check connection parameters.
  4. Connection string wrong → root cause identified.

Example 2 — Function exits early

❌ Symptom-only: "processOrder() exits early due to invalid payment status." ✅ Root cause: "processOrder() exits early because payment validation fails when the payment service doesn't receive the required currency field, which wasn't included in the request due to a missing form field in the UI."

Investigation:

  1. Function exits early → breakpoint at validation check.
  2. Payment status invalid → debug payment validation logic.
  3. currency missing → trace back to request formation.
  4. UI form missing currency field → root cause identified.

Example 3 — Unexpected value

❌ Symptom-only: "Calculation result is NaN." ✅ Root cause: "The result is NaN because one input is a string instead of a number, because parseFloat() fails when the input contains currency symbols that weren't stripped by the sanitization function."

Investigation:

  1. Result is NaN → check input parameters.
  2. Parameter is a string → find where conversion should happen.
  3. parseFloat() fails → check what's being parsed.
  4. Currency symbols not stripped → root cause identified.

Root cause investigation checklist

Before ending the debug session, confirm you can answer:

  • What is the immediate symptom?
  • What function / code caused this symptom?
  • What input or condition caused that function to behave incorrectly?
  • Where did that input or condition originate?
  • Can I trace this back further to a more fundamental cause?
  • If I fix this root cause, will it prevent the symptom from occurring?

Breakpoint strategy

  • Start broad, then narrow. Begin at the entry point of the suspect function. As you isolate the issue, add tighter breakpoints around the problematic region.
  • Use line numbers. add_breakpoint takes a 1-based line; re-check the line after edits since numbers shift when code changes.
  • Prefer logpoints for loops/hot paths. When you want to observe how a value evolves across many iterations without stopping, use add_logpoint with {expression} interpolation (e.g. iter {i}: total={total}) instead of repeatedly continuing from a breakpoint. Logpoints also avoid distorting timing-sensitive code.
  • Don't overuse breakpoints. A handful of well-placed pauses beats dozens of noisy ones. After each session, clear_all_breakpoints to start fresh.
  • For test debugging, pass testName to start_debugging. The server routes through VS Code's Testing API so test runners (dotnet test, pytest, jest, etc.) are driven correctly and the debugger attaches to the child test-host process.

Tool-call patterns

Investigating a bug in calculate.py

add_breakpoint  fileFullPath=/repo/src/calculate.py  line=42
start_debugging fileFullPath=/repo/src/calculate.py  workingDirectory=/repo
# session pauses on the breakpoint
list_variable_names  scope=local
get_variables_values variableNames=["raw","total"] scope=local
evaluate_expression  expression="type(raw).__name__"
step_into
# … iterate until root cause found …
clear_all_breakpoints

Debugging a single xUnit test in C#

add_breakpoint  fileFullPath=C:\Repo\Calculator.Tests\CalculatorTests.cs  line=18
start_debugging fileFullPath=C:\Repo\Calculator.Tests\CalculatorTests.cs  workingDirectory=C:\Repo  testName=Add_ReturnsSum
# pauses inside the test
step_into
list_variable_names
get_variables_values variableNames=["result","expected"]

Verifying a fix without re-launching VS Code

restart_debugging
# session restarts with the same configuration; breakpoints persist
continue_execution

Language-specific guidance

Load the relevant reference file for the language you're debugging:

  • Python → references/troubleshooting/python.md
  • JavaScript / TypeScript → references/troubleshooting/javascript.md
  • Java → references/troubleshooting/java.md
  • C# → references/troubleshooting/csharp.md
  • C++ → references/troubleshooting/cpp.md
  • Go → references/troubleshooting/go.md
  • Ruby → references/troubleshooting/ruby.md

Each reference covers prerequisites (which VS Code extension to install), framework-specific configuration (e.g. enabling pytest test discovery, building .NET projects before launch), and common pitfalls.

Multiple VS Code windows

VS Code normally brings a window to the foreground when its debugger stops. If a breakpoint or step in one workspace interrupts work in another VS Code window, recommend these native VS Code settings:

{
  "debug.focusWindowOnBreak": false,
  "debug.focusEditorOnBreak": false
}

debug.focusWindowOnBreak prevents the debugged window from taking operating-system focus. The optional debug.focusEditorOnBreak setting also keeps focus out of the stopped source editor. Do not change either persistent setting without the user's approval.


Things to avoid

  • ❌ Adding temporary logs, print statements, or console output before debugging. Invoke this skill and inspect live state first. Use a debugger logpoint for non-breaking observation.
  • ❌ Speculating about runtime values when you could just inspect them. That's what get_variables_values and evaluate_expression are for.
  • ❌ Calling start_debugging without first setting a breakpoint. The program will run to completion and you'll learn nothing.
  • ❌ Stopping at the first wrong value you find. That's a symptom. Trace it back.
  • ❌ Leaving breakpoints set across sessions. Future runs will pause in unexpected places. Always clear_all_breakpoints when done.
  • ❌ Awaiting interactive input when the program reads stdin. DebugMCP drives the VS Code debugger; if the program blocks on stdin, no tool call can unblock it. Pick a code path that doesn't require interactive input, or pre-supply input via the launch config / fixture.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.