enhance documentation for debug-live skill installation and usage

Author: ozzafar

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.1-green.svg)](https://github.com/microsoft/DebugMCP)
+[![Version](https://img.shields.io/badge/version-2.2.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.
@@ -17,10 +17,12 @@ Let AI agents debug your code inside VS Code - set breakpoints, step through exe
   <img src="assets/DebugMCP.gif" width="800">
 </p>
 
-## ✨ What's New in 2.0.0
+## ✨ What's New
 
-- **`/debug-live` Agent Skill** — DebugMCP now ships a companion [Agent Skill](./skills/debug-live/SKILL.md) that is auto-installed into each configured harness's personal skills directory (e.g. `~/.copilot/skills/debug-live/`). Invoke it with `/debug-live` 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.
+### 2.2
+- **Cross-agent `debug-live` skill install** — the systematic debugging workflow ships as an [Agent Skill](https://agentskills.io) and is now installed into the **standard skills directories** — `~/.agents/skills/` (the cross-agent location honored by skills-compatible harnesses, including VS Code agent mode) and `~/.copilot/skills/` when present — so it's discoverable everywhere instead of being copied next to each agent's config where nothing scans it (fixes [#105](https://github.com/microsoft/DebugMCP/issues/105), where VS Code never loaded the skill). The server also advertises MCP `instructions` and the `start_debugging` tool points at the skill for the full workflow.
+- **Pause running programs** — new `pause_execution` tool interrupts a freely-running program and stops at its current location, even with no breakpoint set (great for busy loops and embedded/bare-metal targets), so you can then inspect state or step from there.
+- **Robust debugging via the VS Code Testing API** — `start_debugging` with a `testName` uses the VS Code Testing API to discover and launch the test, producing consistent breakpoint hits inside individual test cases across language test runners (pytest, Jest/Vitest, Java, .NET, Go, etc.).
 
 ## 🚀 Quick Install
 
@@ -56,6 +58,7 @@ DebugMCP is an MCP server that gives AI coding agents full control over the VS C
 | **step_into** | Step into function calls | None |
 | **step_out** | Step out of the current function | None |
 | **continue_execution** | Continue until next breakpoint | None |
+| **pause_execution** | Interrupt a freely-running program and stop at its current location (no breakpoint needed) | None |
 | **restart_debugging** | Restart the current debug session | None |
 | **add_breakpoint** | Add a breakpoint at a specific line (optionally conditional) | `fileFullPath` (required)<br>`lineContent` (required)<br>`condition` (optional) |
 | **remove_breakpoint** | Remove a breakpoint from a specific line | `fileFullPath` (required)<br>`line` (required) |
@@ -64,11 +67,13 @@ DebugMCP is an MCP server that gives AI coding agents full control over the VS C
 | **get_variables_values** | Get variables and their values at current execution point | `scope` (optional: 'local', 'global', 'all') |
 | **evaluate_expression** | Evaluate an expression in debug context | `expression` (required) |
 
-> **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-live/SKILL.md) so it can be loaded into an
-> agent's prompt context independently of the MCP capability surface.
+> **Note:** The MCP server exposes **tools** for debugger actions, while the procedural
+> workflow guidance (when to debug, how to structure a root-cause investigation,
+> language-specific quirks) lives in the companion [Agent Skill](./skills/debug-live/SKILL.md).
+> Tool descriptions stay terse and behavioral; the extension installs the `debug-live` skill
+> into the standard skills directories (`~/.agents/skills/`, plus `~/.copilot/skills/` when
+> present) so skills-compatible harnesses load the full workflow on demand. The server also
+> advertises MCP `instructions` pointing agents at it before debugging.
 
 ### 🎯 Debugging Best Practices
 

docs/architecture/agentConfigurationManager.md

@@ -73,11 +73,22 @@ url = "http://localhost:3001/mcp"
 
 Uses VS Code's `globalState` to track whether the onboarding popup has been shown, preventing repeated prompts on every activation.
 
+### Skill delivery — standard skills directories
+
+The `debug-live` Agent Skill is installed into the **standard personal skills directories** defined by the Agent Skills open standard (agentskills.io), rather than being copied next to each agent's config file:
+- **`~/.agents/skills/debug-live/`** — the cross-agent location honored by skills-compatible harnesses, including VS Code agent mode and Copilot CLI. Always installed.
+- **`~/.copilot/skills/debug-live/`** — Copilot's own skills path; also installed when a Copilot home directory (`~/.copilot`, or `$COPILOT_HOME`) exists.
+
+`installDebugMCPSkill()` copies the one bundled source (`skills/debug-live/SKILL.md`) into each target with `force: true` (idempotent refresh) and removes stale legacy copies (`debug`, `really-debug`). It is agent-independent — a single shared install covers every skills-compatible harness.
+
+This fixes issue #105: earlier builds copied the skill next to each agent's config (e.g. `Code/User/skills/` for VS Code Copilot), a directory no harness scans, so the skill never loaded. Installing to `~/.agents/skills/` — which VS Code agent mode does scan — makes it discoverable.
+
 ## Key Code Locations
 
 - Class definition: `src/utils/agentConfigurationManager.ts`
 - Agent definitions: `getSupportedAgents()`
 - Config writing: `addDebugMCPToAgent()`
+- Skill install: `installDebugMCPSkill()` / `getSkillInstallTargets()` / `ensureSkillRegistered()`
 - Codex TOML upsert: `upsertCodexDebugMCPConfig()`
 - Path detection: `getConfigBasePath()`
 - Popup logic: `shouldShowPopup()`, `showAgentSelectionPopup()`
@@ -91,6 +102,8 @@ Uses VS Code's `globalState` to track whether the onboarding popup has been show
 5. Show success message with option to open config file
 6. Mark popup as shown
 
+The bundled `debug-live` skill is installed into the standard skills directories (`~/.agents/skills/`, plus `~/.copilot/skills/` when present) during step 4, so every skills-compatible harness discovers it from one shared location.
+
 ## Commands
 
 - `debugmcp.showAgentSelectionPopup`: Manually trigger agent setup

docs/architecture/debugMCPServer.md

@@ -35,17 +35,26 @@ AI Agent (MCP Client)
 
 ## Key Concepts
 
-### Tools only — no resources, no instructions
+### Tools plus the debug-live skill
 
-`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-live/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.
+`DebugMCPServer` exposes **tools** for debugger capabilities. Detailed procedural guidance
+(when to debug, how to structure a root-cause investigation, language-specific quirks) lives
+in the companion Agent Skill at `skills/debug-live/SKILL.md`, which `AgentConfigurationManager`
+installs into the standard personal skills directories (`~/.agents/skills/`, and
+`~/.copilot/skills/` when present) so skills-compatible harnesses load it on demand. This
+separation matches modern agent ecosystems where MCP servers provide *capabilities* and
+skills provide *procedural knowledge* an agent loads as context.
 
 Tool descriptions are intentionally terse and behavioral — they describe *what* the
 tool does, not *when* or *how* to use it in a multi-step workflow.
 
+### Ensuring the workflow is loaded
+
+The server `instructions` (passed to the `McpServer` constructor and returned to the client
+at `initialize`) and the `start_debugging` tool description both point agents at the
+`debug-live` skill for the full step-through workflow, so the pointer is visible even before
+the skill activates.
+
 ### Streamable HTTP Transport
 
 Uses stateless HTTP POST requests for MCP communication. The express server exposes:
@@ -58,7 +67,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-live/SKILL.md`
+- Agent Skill (procedural workflow): `skills/debug-live/SKILL.md`
 
 ## Exposed Tools
 

package-lock.json

@@ -1,8 +1,8 @@
 {
   "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.1.0",
+  "displayName": "DebugMCP — AI Agent Debugging for VS Code",
+  "description": "Your AI agent debugs for you — right inside VS Code. Let Copilot, Cline, Cursor, Codex & any MCP agent set breakpoints, step through code, and inspect variables live instead of guessing from logs.",
+  "version": "2.2.1",
   "publisher": "ozzafar",
   "author": {
     "name": "Oz Zafar",
@@ -28,15 +28,34 @@
     "breakpoints",
     "debugger",
     "ai agent",
-    "copilot"
+    "copilot",
+    "cline",
+    "cursor",
+    "windsurf",
+    "roo code",
+    "codex",
+    "claude",
+    "autonomous debugging",
+    "agent debugging",
+    "test debugging",
+    "pytest",
+    "jest",
+    "debug adapter protocol",
+    "dap"
   ],
   "engines": {
     "vscode": "^1.104.0"
   },
   "icon": "assets/debug_mcp_icon.png",
+  "galleryBanner": {
+    "color": "#1e1e1e",
+    "theme": "dark"
+  },
   "categories": [
     "Debuggers",
     "AI",
+    "Chat",
+    "Machine Learning",
     "Programming Languages"
   ],
   "extensionDependencies": [],

package.json

@@ -144,6 +144,14 @@ export class DebugMCPServer {
         const server = new McpServer({
             name: 'debugmcp',
             version: '1.0.0',
+        }, {
+            // Surfaced to clients at `initialize`. Points agents at the
+            // `debug-live` Agent Skill, which the extension installs into the
+            // standard skills directories for harnesses that load skills.
+            instructions: 'These tools drive the VS Code debugger to investigate bugs, failing tests, ' +
+                'wrong/null values and other "it doesn\'t work" reports by stepping through code. ' +
+                'The companion "debug-live" Agent Skill describes the full interactive workflow: ' +
+                'when to set breakpoints, how to step and inspect state, and how to do root-cause analysis.',
         });
         this.setupTools(server);
         return server;
@@ -162,7 +170,7 @@ export class DebugMCPServer {
         server.registerTool('start_debugging', {
             description: 'Start a VS Code debug session for a source file, optionally for a single test method. ' +
                 'Use when investigating bugs, failing tests, wrong/null variable values, unexpected runtime behavior, ' +
-                'or any "it doesn\'t work" report.',
+                'or any "it doesn\'t work" report. See the "debug-live" skill for the full investigation workflow.',
             inputSchema: {
                 fileFullPath: z.string().describe('Full path to the source code file to debug'),
                 workingDirectory: z.string().describe('Working directory for the debug session'),