feat(copilot): add chat skills, instructions and when-gates for language model tools (#1643)

- Gate all 10 language model tools with `when` clauses so they only register
  when the Java Language Server is ready, and (for active-debug-session-only
  tools) when an active `java` debug session is in progress. This avoids
  loading failures and reduces the noise Copilot sees from this extension's
  tool catalog when the tools cannot actually run.

- Contribute a `chatInstructions` file (`javaDebugContext.instructions.md`)
  with a keyword-rich, on-demand description (no `applyTo`, to avoid burning
  context on every Java edit) that tells Copilot to activate the deferred
  Java debug tools via `tool_search_tool_regex` and routes the user request
  to one of the two skills below.

- Contribute two `chatSkills`, split by user-habit telemetry (launch/stop is
  ~52% of tool usage; inspection/step is ~28%):
  - `java-launch-troubleshooting` — start/stop a Java program and diagnose
    launch failures (mainClass missing, classpath, build errors, project
    not detected). Gated by `javaLSReady` so it is discoverable any time
    in a Java workspace.
  - `java-debug-inspection` — inspect variables, walk the stack, list
    threads, evaluate expressions, step in/over/out, continue, and manage
    breakpoints in an active Java debug session. Gated by
    `javaLSReady && inDebugMode && debugType == 'java'` so it only appears
    once a Java debug session is alive — keeping it reactive, not proactive.

Author: wenytang-ms

package.json

@@ -1011,6 +1011,7 @@
         ],
         "icon": "$(debug-alt)",
         "canBeReferencedInPrompt": true,
+        "when": "javaLSReady",
         "inputSchema": {
           "type": "object",
           "properties": {
@@ -1062,6 +1063,7 @@
         ],
         "icon": "$(debug-breakpoint)",
         "canBeReferencedInPrompt": true,
+        "when": "javaLSReady",
         "inputSchema": {
           "type": "object",
           "properties": {
@@ -1105,6 +1107,7 @@
         ],
         "icon": "$(debug-step-over)",
         "canBeReferencedInPrompt": true,
+        "when": "javaLSReady && inDebugMode && debugType == 'java'",
         "inputSchema": {
           "type": "object",
           "properties": {
@@ -1142,6 +1145,7 @@
         ],
         "icon": "$(symbol-variable)",
         "canBeReferencedInPrompt": true,
+        "when": "javaLSReady && inDebugMode && debugType == 'java'",
         "inputSchema": {
           "type": "object",
           "properties": {
@@ -1183,6 +1187,7 @@
         ],
         "icon": "$(call-hierarchy)",
         "canBeReferencedInPrompt": true,
+        "when": "javaLSReady && inDebugMode && debugType == 'java'",
         "inputSchema": {
           "type": "object",
           "properties": {
@@ -1212,6 +1217,7 @@
         ],
         "icon": "$(symbol-method)",
         "canBeReferencedInPrompt": true,
+        "when": "javaLSReady && inDebugMode && debugType == 'java'",
         "inputSchema": {
           "type": "object",
           "properties": {
@@ -1257,6 +1263,7 @@
         ],
         "icon": "$(list-tree)",
         "canBeReferencedInPrompt": true,
+        "when": "javaLSReady && inDebugMode && debugType == 'java'",
         "inputSchema": {
           "type": "object",
           "properties": {},
@@ -1275,6 +1282,7 @@
         ],
         "icon": "$(debug-breakpoint-unverified)",
         "canBeReferencedInPrompt": true,
+        "when": "javaLSReady",
         "inputSchema": {
           "type": "object",
           "properties": {
@@ -1303,6 +1311,7 @@
         ],
         "icon": "$(debug-stop)",
         "canBeReferencedInPrompt": true,
+        "when": "javaLSReady && inDebugMode && debugType == 'java'",
         "inputSchema": {
           "type": "object",
           "properties": {
@@ -1330,12 +1339,29 @@
         ],
         "icon": "$(info)",
         "canBeReferencedInPrompt": true,
+        "when": "javaLSReady",
         "inputSchema": {
           "type": "object",
           "properties": {},
           "required": []
         }
       }
+    ],
+    "chatSkills": [
+      {
+        "path": "./resources/skills/java-launch-troubleshooting/SKILL.md",
+        "when": "javaLSReady"
+      },
+      {
+        "path": "./resources/skills/java-debug-inspection/SKILL.md",
+        "when": "javaLSReady && inDebugMode && debugType == 'java'"
+      }
+    ],
+    "chatInstructions": [
+      {
+        "path": "./resources/instruments/javaDebugContext.instructions.md",
+        "when": "javaLSReady"
+      }
     ]
   },
   "scripts": {

resources/instruments/javaDebugContext.instructions.md

@@ -0,0 +1,16 @@
+---
+description: Use when the user wants to run, launch, start, debug, verify, or step through a Java program (main class, Spring Boot, JAR, Maven, Gradle); or when inspecting variables, stack frames, threads, evaluating expressions, or managing breakpoints in a Java debug session.
+---
+
+For Java run/launch/debug/inspection requests, prefer the Java debug language model tools over generic shell commands (`mvn exec:java`, `gradle run`, raw `java -cp …`). These tools are contributed by the `Debugger for Java` extension and are deferred — activate them with `tool_search_tool_regex` using pattern `java_breakpoint|debug` before first use, then call them by name.
+
+## Pick the right skill
+
+| User intent | Load skill | Typical tools |
+|---|---|---|
+| Run / launch / start / stop a Java program, diagnose launch failures (build error, classpath, mainClass missing) | `java-launch-troubleshooting` | `debug_java_application`, `get_debug_session_info`, `stop_debug_session` |
+| Inspect a Java program that is already being debugged: read variables, evaluate expressions, walk the stack, step in/over/out, continue, set or remove breakpoints | `java-debug-inspection` | `get_debug_variables`, `get_debug_stack_trace`, `evaluate_debug_expression`, `get_debug_threads`, `debug_step_operation`, `set_java_breakpoint`, `remove_java_breakpoints` |
+
+If both apply (e.g. "launch and break on entry of `Main.foo`"), load `java-launch-troubleshooting` first, then `java-debug-inspection` after the session is active.
+
+Fall back to `run_in_terminal` only when `debug_java_application` returns "Java Language Server not ready" or "project not detected".

resources/skills/java-debug-inspection/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: java-debug-inspection
+description: Use when inspecting a Java program that is already being debugged — read local variables, walk the call stack, list threads, evaluate expressions, step in/over/out, continue execution, or set / remove breakpoints in an active Java debug session. NOT for starting, launching, or stopping a debug session — use `java-launch-troubleshooting` for that.
+---
+
+# Java Debug Inspection
+
+Use this skill when a Java debug session is already active (the user has launched the program with `debug_java_application` or via the VS Code Run/Debug UI) and they want to **observe or steer the running program**. Typical user phrases:
+
+- "what's the value of `user.id` right now?", "show me the local variables"
+- "evaluate `list.size()`", "what does `service.findById(42)` return at this frame?"
+- "show the stack trace", "what threads are running?", "go up one frame"
+- "step in", "step over", "step out", "continue", "resume"
+- "set a breakpoint at `OrderService.placeOrder`", "remove the breakpoint on line 42"
+
+If no debug session is active, this skill should not be used — load `java-launch-troubleshooting` first to start one.
+
+## Tools
+
+These language model tools are contributed by the `Debugger for Java` extension and are deferred. Activate them with `tool_search_tool_regex` using pattern `java_breakpoint|debug` before first use.
+
+| Tool | Purpose |
+|---|---|
+| `get_debug_variables` | Read local variables, fields, and watched expressions in the current frame. |
+| `get_debug_stack_trace` | List call-stack frames for the focused (or specified) thread. |
+| `get_debug_threads` | List all threads in the session with state (running, stopped, terminated). |
+| `evaluate_debug_expression` | Evaluate an arbitrary Java expression in the context of the focused frame. |
+| `debug_step_operation` | Step in, step over, step out, or continue. Requires the program to be paused. |
+| `set_java_breakpoint` | Set a line / method / exception breakpoint. Works at any time during the session. |
+| `remove_java_breakpoints` | Remove one or more breakpoints by ID or location. |
+
+## Preferred Workflow
+
+1. **Confirm session state.** If the user asks to step or evaluate an expression, the program must be paused (typically at a breakpoint). If unsure, call `get_debug_session_info` from `java-launch-troubleshooting` to check, or list threads with `get_debug_threads`.
+2. **Inspect first, then act.** For "what's the value of X" — call `get_debug_variables` or `evaluate_debug_expression`. Do not guess from source code.
+3. **Step / continue.** For "step over" / "step in" / "step out" / "continue", call `debug_step_operation` with the matching action. After each step, re-read variables or stack as needed.
+4. **Breakpoints.** For "set a breakpoint at …", call `set_java_breakpoint` with the file URI + line, or fully qualified method signature, or exception class. For "remove the breakpoint at …", call `remove_java_breakpoints`.
+5. **Report precisely.** Quote the exact value or stack frame returned by the tool — do not paraphrase.
+
+## Common Pitfalls
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `debug_step_operation` returns "thread is not paused" | The program is running, not stopped at a breakpoint | Ask the user to add a breakpoint first, or wait for the next stop event |
+| `evaluate_debug_expression` returns `<no active frame>` | No focused stack frame, often because the session just resumed | Re-call `get_debug_stack_trace` to refocus a frame |
+| `get_debug_variables` returns empty for a parameter | Compilation without `-g` (no local variable table) | Inform user; offer to inspect via `evaluate_debug_expression` instead |
+| Step in jumps into JDK internals | Default step filters disabled | Suggest enabling `java.debug.settings.stepping.skipClasses` |
+
+## When NOT to Use This Skill
+
+- The user wants to *start* a Java program (no session yet) → use `java-launch-troubleshooting`
+- The user wants to *stop* the session → use `stop_debug_session` from `java-launch-troubleshooting`
+- The program is a non-Java language → do not load this skill
+- The user is editing source code without an active debug session → do nothing
+
+## Fallback
+
+If a tool returns "Java Language Server not ready" or repeats the same error twice, report the raw error to the user and stop calling debug tools for the current turn. Do not retry more than twice.

resources/skills/java-launch-troubleshooting/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: java-launch-troubleshooting
+description: Use when the user wants to run, launch, start, restart, or stop a Java program (main class, Spring Boot, JAR, Maven, Gradle), or diagnose launch failures (mainClass missing, classpath unresolved, compile failure, "project not detected", `ClassNotFoundException` at startup). NOT for inspecting variables, stepping, or setting breakpoints in an already-running debug session — use `java-debug-inspection` for that.
+---
+
+# Java Launch Troubleshooting
+
+Use this skill when the user wants to **start or stop** a Java program, or when an attempted launch fails. Typical user phrases:
+
+- "run this main class", "start the app", "launch the Spring Boot project", "run the jar"
+- "stop the debug session", "kill the running app"
+- prior `run_in_terminal` failed with `ClassNotFoundException`, `mainClass is not set`, `Could not find or load main class`, `Could not resolve classpath`
+- the user changed `pom.xml` / `build.gradle` and the app no longer starts
+
+## Tools
+
+These language model tools are contributed by the `Debugger for Java` extension and are deferred. Activate them with `tool_search_tool_regex` using pattern `java_breakpoint|debug` before first use.
+
+| Tool | Purpose |
+|---|---|
+| `debug_java_application` | Build + resolve classpath + start JVM. Returns precise compile and classpath errors. |
+| `get_debug_session_info` | Check whether a debug session is already running and its status. |
+| `stop_debug_session` | Stop a running Java debug session cleanly. |
+
+## Preferred Workflow
+
+1. **Confirm intent.** Is the user trying to *run / start / launch / stop* a Java program (use this skill) or just edit code (do not load this skill)?
+2. **Check existing session.** Call `get_debug_session_info` first. If a session is already running for the target, do not launch a second one.
+3. **Launch.** Call `debug_java_application` with `target` = the fully qualified main class or JAR, and `workspacePath` = the project root containing `pom.xml`, `build.gradle`, or `.classpath`. Let `skipBuild` default to `false` so the tool handles compilation.
+4. **Read the error.** If `debug_java_application` fails, the error message is structured (mainClass missing, classpath unresolved, build failure with line number). Use it to suggest a fix — do not retry with `run_in_terminal`.
+5. **Stop when done.** When the user says "stop", "kill it", or has the answer they need, call `stop_debug_session`.
+
+## Common Failure Modes
+
+| Symptom from `debug_java_application` | Likely cause | Suggested fix |
+|---|---|---|
+| `mainClass is not configured` / `mainClass missing` | Project has no `launch.json`, and the file has no `public static void main` | Ask user which class to launch, or generate `launch.json` |
+| `Could not resolve classpath` | Maven/Gradle import has not completed, or `pom.xml` has unresolved dependencies | Wait for Java Language Server import, then ask user to run `Java: Clean Java Language Server Workspace` |
+| `Compilation failed` with file:line | Source code has a compile error | Fix the reported error in the source file, do not retry the launch |
+| `Project not detected` | `workspacePath` does not contain a build file | Re-check `workspacePath`; for multi-module projects, use the module root, not the repo root |
+
+## When NOT to Use This Skill
+
+- The user is editing or refactoring Java code without running it → do nothing
+- The user is already inside a live debug session and wants to inspect variables, evaluate expressions, walk the stack, step, or set / remove breakpoints → use `java-debug-inspection` instead, do not re-launch
+- The program is a non-Java language → do not load this skill
+
+## Fallback
+
+If `debug_java_application` returns `Java Language Server not ready` or repeats the same error twice, fall back to `run_in_terminal` with the appropriate `mvn` or `gradle` command and report the raw output to the user. Do not retry the debug tool more than twice.