From fd7a8bbc660b3a875b55dd41b2d6883e7651a39b Mon Sep 17 00:00:00 2001
From: ozzafar <48795672+ozzafar@users.noreply.github.com>
Date: Fri, 5 Jun 2026 00:59:05 +0300
Subject: [PATCH 1/2] Rename `/debug` Agent Skill to `/really-debug` and update
 related documentation; increment version to 2.0.1

---
 CHANGELOG.md                                  |   2 +-
 README.md                                     |   4 +-
 docs/architecture/debugMCPServer.md           |   4 +-
 package-lock.json                             |   4 +-
 package.json                                  |   2 +-
 skills/really-debug/README.md                 |  63 +++++
 skills/really-debug/SKILL.md                  | 239 ++++++++++++++++++
 .../references/troubleshooting/cpp.md         |  78 ++++++
 .../references/troubleshooting/csharp.md      | 108 ++++++++
 .../references/troubleshooting/go.md          |  52 ++++
 .../references/troubleshooting/java.md        |  52 ++++
 .../references/troubleshooting/javascript.md  |  46 ++++
 .../references/troubleshooting/python.md      |  57 +++++
 src/debugMCPServer.ts                         |   4 +-
 src/utils/agentConfigurationManager.ts        |  18 +-
 15 files changed, 721 insertions(+), 12 deletions(-)
 create mode 100644 skills/really-debug/README.md
 create mode 100644 skills/really-debug/SKILL.md
 create mode 100644 skills/really-debug/references/troubleshooting/cpp.md
 create mode 100644 skills/really-debug/references/troubleshooting/csharp.md
 create mode 100644 skills/really-debug/references/troubleshooting/go.md
 create mode 100644 skills/really-debug/references/troubleshooting/java.md
 create mode 100644 skills/really-debug/references/troubleshooting/javascript.md
 create mode 100644 skills/really-debug/references/troubleshooting/python.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 10f4bc3..8afb0f6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,7 +7,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 ## [1.2.0] - 2026-06-04
 
 ### Added
-- **`/debug` Agent Skill** — bundled companion skill at `skills/debug/` that encodes the systematic debugging workflow for AI agents. The skill is automatically copied into each configured harness's personal skills directory (e.g. `~/.copilot/skills/debug/`) when DebugMCP is registered, and can be invoked with `/debug` in supporting agents.
+- **`/really-debug` Agent Skill** — bundled companion skill at `skills/really-debug/` that encodes the systematic debugging workflow for AI agents. The skill is automatically copied into each configured harness's personal skills directory (e.g. `~/.copilot/skills/really-debug/`) when DebugMCP is registered, and can be invoked with `/really-debug` in supporting agents. (Named `really-debug` rather than `debug` to avoid shadowing built-in `/debug` commands in some harnesses such as GitHub Copilot Chat.)
 - **Robust test debugging via the VS Code Testing API** — `start_debugging` with a `testName` now discovers and launches the target test through the VS Code Testing API, producing reliable breakpoint hits across pytest, Jest/Vitest, Java, .NET, Go, and other Testing-API-integrated runners.
 
 ## [1.0.8] - 2025-03-14
diff --git a/README.md b/README.md
index 0145f8c..d8d6198 100644
--- a/README.md
+++ b/README.md
@@ -19,7 +19,7 @@ Let AI agents debug your code inside VS Code - set breakpoints, step through exe
 
 ## ✨ What's New in 2.0.0
 
-- **`/debug` Agent Skill** — DebugMCP now ships a companion [Agent Skill](./skills/debug/SKILL.md) that is auto-installed into each configured harness's personal skills directory (e.g. `~/.copilot/skills/debug/`). Invoke it with `/debug` in supporting agents to load the systematic debugging workflow and trigger DebugMCP tools with the right context.
+- **`/really-debug` Agent Skill** — DebugMCP now ships a companion [Agent Skill](./skills/really-debug/SKILL.md) that is auto-installed into each configured harness's personal skills directory (e.g. `~/.copilot/skills/really-debug/`). Invoke it with `/really-debug` in supporting agents to load the systematic debugging workflow and trigger DebugMCP tools with the right context.
 - **Robust debugging via the VS Code Testing API** — `start_debugging` with a `testName` now uses the VS Code Testing API to discover and launch the test, replacing the previous best-effort path. This works reliably across language test runners that integrate with the Testing API (pytest, Jest/Vitest, Java, .NET, Go, etc.) and produces consistent breakpoint hits inside individual test cases.
 
 ## 🚀 Quick Install
@@ -67,7 +67,7 @@ DebugMCP is an MCP server that gives AI coding agents full control over the VS C
 > **Note:** The MCP server intentionally exposes **tools only** — no procedural
 > instructions, no documentation resources. Workflow guidance (when to debug, how to
 > structure a root-cause investigation, language-specific quirks) lives in the companion
-> [DebugMCP Agent Skill](./skills/debug/SKILL.md) so it can be loaded into an
+> [DebugMCP Agent Skill](./skills/really-debug/SKILL.md) so it can be loaded into an
 > agent's prompt context independently of the MCP capability surface.
 
 ### 🎯 Debugging Best Practices
diff --git a/docs/architecture/debugMCPServer.md b/docs/architecture/debugMCPServer.md
index fcf3718..4c47c0e 100644
--- a/docs/architecture/debugMCPServer.md
+++ b/docs/architecture/debugMCPServer.md
@@ -39,7 +39,7 @@ AI Agent (MCP Client)
 
 `DebugMCPServer` exposes **tools only**. Procedural workflow guidance (when to debug,
 how to structure a root-cause investigation, language-specific quirks) lives in the
-companion Agent Skill at `skills/debug/SKILL.md`, not in tool descriptions or MCP
+companion Agent Skill at `skills/really-debug/SKILL.md`, not in tool descriptions or MCP
 resources. This separation matches modern agent ecosystems where MCP servers provide
 *capabilities* and skills provide *procedural knowledge* an agent loads as context.
 
@@ -58,7 +58,7 @@ Each request creates a new stateless `StreamableHTTPServerTransport` instance th
 - Class definition: `src/debugMCPServer.ts`
 - Tool registration: `setupTools()` method (uses `McpServer.registerTool()`)
 - Server startup: `start()` method (creates express app with `/mcp` route)
-- Agent Skill (companion, not part of the MCP surface): `skills/debug/SKILL.md`
+- Agent Skill (companion, not part of the MCP surface): `skills/really-debug/SKILL.md`
 
 ## Exposed Tools
 
diff --git a/package-lock.json b/package-lock.json
index 02761f5..c11ae28 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "debugmcpextension",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "debugmcpextension",
-      "version": "2.0.0",
+      "version": "2.0.1",
       "license": "MIT",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.26.0",
diff --git a/package.json b/package.json
index aed658f..6d4675e 100644
--- a/package.json
+++ b/package.json
@@ -2,7 +2,7 @@
   "name": "debugmcpextension",
   "displayName": "DebugMCP",
   "description": "Let AI agents debug your code inside VS Code — breakpoints, step-through execution, variable inspection, and expression evaluation. Automatically exposes itself as an MCP (Model Context Protocol) server for seamless integration with AI assistants.",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "publisher": "ozzafar",
   "author": {
     "name": "Oz Zafar",
diff --git a/skills/really-debug/README.md b/skills/really-debug/README.md
new file mode 100644
index 0000000..fb2e917
--- /dev/null
+++ b/skills/really-debug/README.md
@@ -0,0 +1,63 @@
+# DebugMCP Skill
+
+This folder is a self-contained **Agent Skill** that teaches an AI agent how to use the
+DebugMCP MCP server effectively. It follows the Anthropic-style Skills convention: a
+`SKILL.md` entry point with YAML frontmatter, plus bundled reference docs.
+
+## Why this is separate from the MCP server
+
+The DebugMCP MCP server exposes only **tools** (with brief, behavioral descriptions).
+All workflow guidance — when to debug, how to structure a root-cause investigation,
+which breakpoints to set, language-specific quirks — lives in this skill, not in tool
+descriptions.
+
+This separation matches modern agent ecosystems where:
+- **MCP servers** = capabilities (tools, resources, prompts)
+- **Skills** = procedural knowledge an agent loads as context
+
+## Contents
+
+```
+skills/debugmcp/
+├── SKILL.md                           # Entry point + workflow + root cause framework
+├── README.md                          # This file
+└── references/
+    └── troubleshooting/
+        ├── python.md
+        ├── javascript.md
+        ├── java.md
+        ├── csharp.md
+        ├── cpp.md
+        └── go.md
+```
+
+## Installation
+
+How you install a skill depends on your agent runtime. Common patterns:
+
+- **Anthropic / Claude API with the Skills feature** — point the runtime at this folder
+  (or vendor the folder into your project) and the agent will read `SKILL.md` and load
+  references on demand.
+- **Claude Code** — drop this folder under your project's configured skills directory.
+- **Cursor / Cline / other clients without native skills support** — copy the contents
+  of `SKILL.md` into a project rule / system prompt, and keep the `references/` files
+  available for the agent to read on request.
+
+Refer to your client's documentation for the exact path / mechanism.
+
+## Tool naming
+
+The `allowed-tools` list in `SKILL.md` uses the raw tool names registered by the
+DebugMCP MCP server (`start_debugging`, `add_breakpoint`, etc.). Some runtimes namespace
+MCP tools (e.g. `mcp__debugmcp__start_debugging`). Adapt the list to whatever convention
+your runtime uses, or omit `allowed-tools` if the runtime doesn't honor it.
+
+## Prerequisites
+
+You also need:
+
+1. The DebugMCP VS Code extension installed and running (it starts an MCP server on
+   `http://127.0.0.1:3001/mcp` by default).
+2. The language extension for whatever you're debugging (Python, C# Dev Kit, Java
+   Extension Pack, etc. — see the per-language reference for specifics).
+3. Your AI agent runtime configured to connect to that MCP endpoint.
diff --git a/skills/really-debug/SKILL.md b/skills/really-debug/SKILL.md
new file mode 100644
index 0000000..1ea9e5e
--- /dev/null
+++ b/skills/really-debug/SKILL.md
@@ -0,0 +1,239 @@
+---
+name: really-debug
+description: Drive an interactive VS Code debugger to investigate bugs, failing tests, wrong/null variable values, unexpected runtime behavior, and other "it doesn't work" reports. Use this skill whenever speculation about runtime behavior would be cheaper to *verify* by stepping through the code than to reason about. Pairs with the DebugMCP MCP server, which exposes the underlying breakpoint / step / inspect tools.
+license: MIT
+allowed-tools:
+  - add_breakpoint
+  - remove_breakpoint
+  - clear_all_breakpoints
+  - list_breakpoints
+  - start_debugging
+  - stop_debugging
+  - restart_debugging
+  - step_over
+  - step_into
+  - step_out
+  - continue_execution
+  - get_variables_values
+  - evaluate_expression
+---
+
+# 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
+
+Reach for this skill 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."
+
+If you can step through the code in a few tool calls, do that instead of speculating.
+
+---
+
+## Core workflow
+
+1. **Set a starting breakpoint.** Use `add_breakpoint` with the file path and the exact
+   line content you want to pause on (line content matching is more robust than line
+   numbers — it survives small edits). 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 `get_variables_values` to see local/global state and
+   `evaluate_expression` to test hypotheses live (call methods, read properties, run
+   list comprehensions, etc.).
+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.
+- **Match line content, not numbers.** `add_breakpoint` takes the exact line text so
+  breakpoints survive small edits and refactors.
+- **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`
+```text
+add_breakpoint  fileFullPath=/repo/src/calculate.py  lineContent="result = parse(raw)"
+start_debugging fileFullPath=/repo/src/calculate.py  workingDirectory=/repo
+# session pauses on the breakpoint
+get_variables_values 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#
+```text
+add_breakpoint  fileFullPath=C:\Repo\Calculator.Tests\CalculatorTests.cs  lineContent="Assert.Equal(5, _calc.Add(2, 3));"
+start_debugging fileFullPath=C:\Repo\Calculator.Tests\CalculatorTests.cs  workingDirectory=C:\Repo  testName=Add_ReturnsSum
+# pauses inside the test
+step_into
+get_variables_values
+```
+
+### Verifying a fix without re-launching VS Code
+```text
+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`
+
+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.
+
+---
+
+## Things to avoid
+
+- ❌ **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.
diff --git a/skills/really-debug/references/troubleshooting/cpp.md b/skills/really-debug/references/troubleshooting/cpp.md
new file mode 100644
index 0000000..268f591
--- /dev/null
+++ b/skills/really-debug/references/troubleshooting/cpp.md
@@ -0,0 +1,78 @@
+# C/C++ Debugging Tips
+
+**C/C++-SPECIFIC GUIDANCE:**
+
+## Prerequisites:
+- Use C/C++ extension for VS Code (by Microsoft)
+- Ensure GDB or LLDB debugger is installed
+- Compile with debug symbols (`-g` flag)
+- Set breakpoints in `.c`, `.cpp`, `.cc`, `.h`, `.hpp` files
+- Use 'cppdbg' debug configuration type
+
+## C/C++-Specific Best Practices:
+- **Compilation:** Always compile with `-g` flag and disable optimizations (`-O0`) for debugging
+- **Memory Issues:** Watch for buffer overflows, memory leaks, and dangling pointers
+- **Pointers:** Carefully inspect pointer values and dereferenced contents
+- **Stack Frames:** Use call stack to trace function calls and local variables
+- **Core Dumps:** Enable core dumps for post-mortem debugging of crashes
+
+## Common C++ Debug Configurations:
+
+### GDB (Linux/Windows with MinGW):
+```json
+{
+    "type": "cppdbg",
+    "request": "launch",
+    "name": "Debug with GDB",
+    "program": "${fileDirname}/${fileBasenameNoExtension}",
+    "args": [],
+    "stopAtEntry": false,
+    "cwd": "${fileDirname}",
+    "environment": [],
+    "externalConsole": false,
+    "MIMode": "gdb",
+    "setupCommands": [
+        {
+            "description": "Enable pretty-printing for gdb",
+            "text": "-enable-pretty-printing",
+            "ignoreFailures": true
+        }
+    ]
+}
+```
+
+### LLDB (macOS):
+```json
+{
+    "type": "cppdbg",
+    "request": "launch",
+    "name": "Debug with LLDB",
+    "program": "${fileDirname}/${fileBasenameNoExtension}",
+    "args": [],
+    "stopAtEntry": false,
+    "cwd": "${fileDirname}",
+    "environment": [],
+    "externalConsole": false,
+    "MIMode": "lldb"
+}
+```
+
+## Debugging Tips:
+- Use `printf()` or `std::cout` for quick debugging
+- Watch for uninitialized variables
+- Check array bounds carefully
+- Be aware of undefined behavior from pointer arithmetic
+- Use address sanitizer (`-fsanitize=address`) to detect memory errors
+- Use valgrind for memory leak detection (Linux)
+
+## Common Issues:
+- **"Unable to start debugging":** Ensure executable is compiled with debug symbols
+- **"No symbol table":** Recompile with `-g` flag
+- **Breakpoints grayed out:** Source file doesn't match compiled binary - rebuild
+- **Segmentation fault:** Use backtrace to find the crashing line, check pointer operations
+- **Optimized away variables:** Compile with `-O0` to disable optimizations
+
+## Memory Debugging:
+- **Valgrind:** `valgrind --leak-check=full ./program`
+- **Address Sanitizer:** Compile with `-fsanitize=address -fno-omit-frame-pointer`
+- **Watch expressions:** Monitor pointer values and array indices during stepping
diff --git a/skills/really-debug/references/troubleshooting/csharp.md b/skills/really-debug/references/troubleshooting/csharp.md
new file mode 100644
index 0000000..86b04b2
--- /dev/null
+++ b/skills/really-debug/references/troubleshooting/csharp.md
@@ -0,0 +1,108 @@
+# C# Debugging Tips
+
+## Overview
+DebugMCP provides enhanced support for debugging C# applications using the C# Dev Kit. This guide covers configuration options and best practices for C# debugging.
+
+## Supported C# Project Types
+
+### Console Applications
+- **File Extension**: `.cs`
+- **Debug Type**: `coreclr`
+- **Requirements**: C# Dev Kit extension installed
+
+### Unit Test Projects
+- **Test Frameworks**: MSTest, NUnit, xUnit
+- **File Patterns**: `*.test.cs`, `*Test.cs`, `*Tests.cs`
+- **Debug Strategy**: Uses `dotnet test` with filtering
+
+### Web Applications
+- **Project Types**: ASP.NET Core, Blazor
+- **Debug Type**: `coreclr`
+- **Additional Configuration**: May require specific launch settings
+
+## Best Practices
+
+### Project Setup
+1. Ensure C# Dev Kit extension is installed
+2. Open projects at the solution or project root level
+3. Use standard .NET project structures
+
+### Debugging Configuration
+1. Place launch.json in `.vscode` directory for custom configurations
+2. Use descriptive configuration names
+3. Set appropriate working directories
+
+### Breakpoint Management
+1. Use line content matching for reliable breakpoint placement
+2. Clear breakpoints when stopping debug sessions
+3. Verify breakpoints are hit in the expected files
+
+## Troubleshooting
+
+### Common Issues
+
+#### Debugger Won't Start
+- **Cause**: Missing C# Dev Kit extension
+- **Solution**: Install the C# Dev Kit extension from VS Code marketplace
+
+#### Breakpoints Not Hit
+- **Cause**: Debug symbols not generated or path mismatch
+- **Solution**: Ensure project builds in Debug mode and paths are correct
+
+#### Test Discovery Issues  
+- **Cause**: Test framework not properly configured
+- **Solution**: Verify test project references and naming conventions
+
+### Performance Optimization
+- Use filtered test execution for large test suites
+- Configure appropriate timeout values
+- Limit scope of variable inspection during debugging
+
+## Advanced Features
+
+### Expression Evaluation
+DebugMCP supports evaluating C# expressions during debugging:
+- Property access: `myObject.Property`
+- Method calls: `myObject.Method()`
+- LINQ expressions: `list.Where(x => x > 5)`
+- Object instantiation: `new List<int>()`
+
+### Variable Scope Management
+- **Local Variables**: Current method scope
+- **Global Variables**: Static members and fields
+- **All Scope**: Complete variable context
+
+### Test Method Filtering
+When running specific test methods:
+- Use exact method names for precision
+- Supports pattern matching with `Name~` filter
+- Works with parameterized tests
+
+## Integration with C# Dev Kit
+
+### Enhanced Features
+- IntelliSense during debugging
+- Advanced breakpoint types
+- Call stack navigation
+- Exception handling configuration
+
+### Project Templates
+DebugMCP works seamlessly with C# Dev Kit project templates:
+- Console applications
+- Class libraries  
+- Test projects
+- Web applications
+
+## External Project Support
+
+### Opening C# Projects Outside Workspace
+DebugMCP can debug C# files that are part of external projects:
+1. Specify the full path to the C# source file
+2. Set appropriate working directory
+3. Use custom launch configurations if needed
+
+### Multi-Project Solutions
+For solutions with multiple projects:
+1. Configure debugging at the solution level
+2. Use project-specific launch configurations
+3. Set breakpoints across multiple projects as needed
diff --git a/skills/really-debug/references/troubleshooting/go.md b/skills/really-debug/references/troubleshooting/go.md
new file mode 100644
index 0000000..af4715c
--- /dev/null
+++ b/skills/really-debug/references/troubleshooting/go.md
@@ -0,0 +1,52 @@
+# Go Debugging Tips
+
+**GO-SPECIFIC GUIDANCE:**
+
+## Prerequisites:
+- Use Go extension for VS Code (by Go Team at Google)
+- Ensure Delve debugger is installed (`go install github.com/go-delve/delve/cmd/dlv@latest`)
+- Set breakpoints in `.go` files
+- Use 'go' debug configuration type
+- Check GOPATH and GOROOT environment variables
+
+## Go-Specific Best Practices:
+- **Build Tags:** Ensure correct build tags are set for debugging
+- **Goroutines:** Be aware that goroutines run concurrently - use breakpoints in each goroutine you want to inspect
+- **Interfaces:** When debugging interface values, check both the type and value
+- **Defer Statements:** Remember deferred functions execute in LIFO order at function return
+- **Channels:** Set breakpoints at channel send/receive operations to debug concurrency
+
+## Common Go Debug Configurations:
+```json
+{
+    "type": "go",
+    "request": "launch",
+    "name": "Launch Package",
+    "mode": "debug",
+    "program": "${fileDirname}"
+}
+```
+
+## Test Debugging:
+```json
+{
+    "type": "go",
+    "request": "launch",
+    "name": "Launch Test",
+    "mode": "test",
+    "program": "${fileDirname}",
+    "args": ["-test.run", "TestFunctionName"]
+}
+```
+
+## Debugging Tips:
+- Use `fmt.Printf()` or `log.Printf()` for quick debugging
+- Watch for `nil` pointer dereferences
+- Be aware of value vs pointer receivers on methods
+- Check error return values - Go's explicit error handling is a common source of bugs
+- Use race detector (`go run -race`) to find data races before debugging
+
+## Common Issues:
+- **"could not launch process":** Ensure Delve is installed and in PATH
+- **Breakpoints not hit:** Check build mode (debug vs release) and ensure optimizations are disabled
+- **Goroutine confusion:** Use the Call Stack panel to switch between goroutines
diff --git a/skills/really-debug/references/troubleshooting/java.md b/skills/really-debug/references/troubleshooting/java.md
new file mode 100644
index 0000000..c03ac57
--- /dev/null
+++ b/skills/really-debug/references/troubleshooting/java.md
@@ -0,0 +1,52 @@
+# Java Debugging Tips
+
+☕ **JAVA-SPECIFIC GUIDANCE:**
+
+## Prerequisites:
+- Use Java Extension Pack (includes debugger)
+- Ensure Java is compiled before debugging
+- Set breakpoints in `.java` files
+- Use 'java' debug configuration type
+- Check JAVA_HOME environment variable
+
+## Java-Specific Best Practices:
+- **Compilation:** Ensure `.class` files are up-to-date with source code
+- **Classpath:** Verify all dependencies are in the classpath
+- **Main Method:** Set breakpoints inside the `main` method for entry point debugging
+- **Exception Handling:** Use breakpoints in `catch` blocks to debug exceptions
+- **Static vs Instance:** Be aware of static context when debugging
+
+## Common Java Debug Configurations:
+```json
+{
+    "type": "java",
+    "request": "launch",
+    "name": "Launch Current File",
+    "mainClass": "${file}",
+    "console": "integratedTerminal"
+}
+```
+
+## Maven/Gradle Projects:
+```json
+{
+    "type": "java",
+    "request": "launch",
+    "name": "Launch Main",
+    "mainClass": "com.example.Main",
+    "classPaths": ["${workspaceFolder}/target/classes"]
+}
+```
+
+## Debugging Tips:
+- Use `System.out.println()` for quick debugging
+- Leverage IDE features like "Evaluate Expression"
+- Watch for `NullPointerException` and array index issues
+- Be aware of object references vs. primitive types
+- Use conditional breakpoints for loops with many iterations
+- Check for proper package declarations and imports
+
+## Common Issues:
+- **ClassNotFoundException:** Check classpath and package structure
+- **NoSuchMethodError:** Ensure method signatures match between source and compiled code
+- **OutOfMemoryError:** Monitor heap usage during debugging
diff --git a/skills/really-debug/references/troubleshooting/javascript.md b/skills/really-debug/references/troubleshooting/javascript.md
new file mode 100644
index 0000000..d1bfe37
--- /dev/null
+++ b/skills/really-debug/references/troubleshooting/javascript.md
@@ -0,0 +1,46 @@
+# JavaScript Debugging Tips
+
+🟨 **JAVASCRIPT-SPECIFIC GUIDANCE:**
+
+## Prerequisites:
+- Use Node.js debugger for server-side JS
+- Use browser debugger for client-side JS
+- Set breakpoints in `.js`, `.ts`, `.jsx`, `.tsx` files
+- Use 'pwa-node' debug configuration type
+- Check that Node.js is installed
+
+## JavaScript-Specific Best Practices:
+- **Async/Await:** Be careful with asynchronous code - breakpoints in async functions
+- **Callbacks:** Set breakpoints inside callback functions to debug async operations
+- **Closures:** Watch for variable scope issues in nested functions
+- **Event Handlers:** Debug event-driven code by setting breakpoints in handlers
+- **Promises:** Use breakpoints in `.then()` and `.catch()` blocks
+
+## Common JavaScript Debug Configurations:
+```json
+{
+    "type": "pwa-node",
+    "request": "launch",
+    "name": "Launch Program",
+    "program": "${file}",
+    "console": "integratedTerminal"
+}
+```
+
+## Browser Debugging:
+```json
+{
+    "type": "pwa-chrome",
+    "request": "launch",
+    "name": "Launch Chrome",
+    "url": "http://localhost:3000",
+    "webRoot": "${workspaceFolder}"
+}
+```
+
+## Debugging Tips:
+- Use `console.log()`, `console.error()`, `console.table()` for quick debugging
+- Leverage browser developer tools for client-side debugging
+- Watch for `undefined` and `null` values
+- Be aware of hoisting and variable scope rules
+- Use source maps for debugging transpiled code (TypeScript, Babel)
diff --git a/skills/really-debug/references/troubleshooting/python.md b/skills/really-debug/references/troubleshooting/python.md
new file mode 100644
index 0000000..07c64cd
--- /dev/null
+++ b/skills/really-debug/references/troubleshooting/python.md
@@ -0,0 +1,57 @@
+# Python Debugging Tips
+
+🐍 **PYTHON-SPECIFIC GUIDANCE:**
+
+## Prerequisites:
+- Use Python debugger extension (Python extension by Microsoft)
+- Set breakpoints inside function bodies
+- Check virtual environment activation
+- Use 'python' debug configuration type
+- Common file extensions: `.py`
+
+## Python-Specific Best Practices:
+- **Virtual Environment:** Ensure the correct Python interpreter is selected
+- **Module Imports:** Set breakpoints after import statements to debug module loading
+- **Exception Handling:** Use breakpoints in `except` blocks to catch errors
+- **List Comprehensions:** Break complex comprehensions into regular loops for easier debugging
+- **Decorators:** Be aware that decorators can affect breakpoint placement
+
+## Common Python Debug Configurations:
+```json
+{
+    "type": "python",
+    "request": "launch",
+    "name": "Python: Current File",
+    "program": "${file}",
+    "console": "integratedTerminal"
+}
+```
+
+## Debugging a Specific Test (pytest / unittest):
+
+DebugMCP dispatches single-test debugging through VS Code's Test Explorer, which requires the Python extension to have **discovered** the test. If discovery hasn't run, `start_debugging` with a `testName` will appear to do nothing (the file opens, the cursor jumps to the test, but no debug session starts).
+
+Discovery requires the test framework to be enabled in workspace settings. Add **one** of the following to `.vscode/settings.json`:
+
+```jsonc
+// For pytest:
+{
+    "python.testing.pytestEnabled": true
+}
+
+// For unittest:
+{
+    "python.testing.unittestEnabled": true,
+    "python.testing.unittestArgs": ["-v", "-s", ".", "-p", "test_*.py"]
+}
+```
+
+Alternatively, run **"Python: Configure Tests"** from the VS Code command palette once — it will write the appropriate settings for you.
+
+Verify discovery worked by opening the Testing view (beaker icon in the sidebar): your tests should appear in the tree. If the tree is empty, the framework isn't configured correctly.
+
+## Debugging Tips:
+- Use `print()` statements for quick debugging
+- Leverage Python's `pdb` module for command-line debugging
+- Watch for `None` values and type mismatches
+- Check indentation issues that might affect code flow
diff --git a/src/debugMCPServer.ts b/src/debugMCPServer.ts
index 7944ac1..9e6264b 100644
--- a/src/debugMCPServer.ts
+++ b/src/debugMCPServer.ts
@@ -18,7 +18,7 @@ import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/
  *
  * Tools only. Procedural workflow guidance (when to debug, how to perform
  * root-cause analysis, language-specific quirks) lives in the companion
- * Agent Skill at `skills/debug/` — the MCP surface itself only describes
+ * Agent Skill at `skills/really-debug/` — the MCP surface itself only describes
  * what each tool does, not how to use them together.
  */
 /**
@@ -148,7 +148,7 @@ export class DebugMCPServer {
      * Tool descriptions are intentionally terse and behavioral. Procedural
      * guidance (when to use which tool, how to perform root-cause analysis,
      * language-specific quirks) lives in the companion Agent Skill at
-     * `skills/debug/SKILL.md`.
+     * `skills/really-debug/SKILL.md`.
      */
     private setupTools(server: McpServer) {
         // Start debugging tool
diff --git a/src/utils/agentConfigurationManager.ts b/src/utils/agentConfigurationManager.ts
index a10c7fc..0dd84e2 100644
--- a/src/utils/agentConfigurationManager.ts
+++ b/src/utils/agentConfigurationManager.ts
@@ -203,7 +203,7 @@ export class AgentConfigurationManager {
      * Path to the debugmcp skill bundled with the extension.
      */
     private getBundledSkillPath(): string {
-        return path.join(this.context.extensionPath, 'skills', 'debug');
+        return path.join(this.context.extensionPath, 'skills', 'really-debug');
     }
 
     /**
@@ -220,12 +220,26 @@ export class AgentConfigurationManager {
         }
 
         const skillsDir = this.getSkillsDirForAgent(agent);
-        const destination = path.join(skillsDir, 'debug');
+        const destination = path.join(skillsDir, 'really-debug');
 
         try {
             await fs.promises.mkdir(skillsDir, { recursive: true });
             await fs.promises.cp(bundledSkillPath, destination, { recursive: true, force: true });
             console.log(`Successfully registered debugmcp skill for ${agent.name} at ${destination}`);
+
+            // Back-compat cleanup: earlier 1.2.0 builds installed the skill at
+            // `<skillsDir>/debug`. Remove the stale copy if it's still around so
+            // users don't end up with two competing entries.
+            const legacyDestination = path.join(skillsDir, 'debug');
+            if (fs.existsSync(legacyDestination)) {
+                try {
+                    await fs.promises.rm(legacyDestination, { recursive: true, force: true });
+                    console.log(`Removed legacy debugmcp skill at ${legacyDestination}`);
+                } catch (cleanupError) {
+                    console.warn(`Failed to remove legacy debugmcp skill at ${legacyDestination}:`, cleanupError);
+                }
+            }
+
             return destination;
         } catch (error) {
             console.warn(`Failed to register debugmcp skill for ${agent.name} at ${destination}:`, error);

From 72bcdc642cfd64fb74fefbcd4520522190904662 Mon Sep 17 00:00:00 2001
From: ozzafar <48795672+ozzafar@users.noreply.github.com>
Date: Fri, 5 Jun 2026 01:01:14 +0300
Subject: [PATCH 2/2] fix version

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index d8d6198..65ebfa2 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@ Let AI agents debug your code inside VS Code - set breakpoints, step through exe
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![VS Code](https://img.shields.io/badge/VS%20Code-1.104.0+-blue.svg)](https://code.visualstudio.com/)
-[![Version](https://img.shields.io/badge/version-2.0.0-green.svg)](https://github.com/microsoft/DebugMCP)
+[![Version](https://img.shields.io/badge/version-2.0.1-green.svg)](https://github.com/microsoft/DebugMCP)
 [![VS Marketplace](https://img.shields.io/badge/VS%20Marketplace-Install-blue.svg)](https://marketplace.visualstudio.com/items?itemName=ozzafar.debugmcpextension)
 
 > ⭐ **If you find DebugMCP useful, please [star the repo on GitHub](https://github.com/microsoft/DebugMCP)!** It helps others discover the project and motivates continued development.