Diffs: Migrate tool usage guidance from before_prompt_build to a plugin skill (#32630)

Merged via squash.

Prepared head SHA: 585697a4e1
Co-authored-by: sircrumpet <4436535+sircrumpet@users.noreply.github.com>
Co-authored-by: gumadeiras <5599352+gumadeiras@users.noreply.github.com>
Reviewed-by: @gumadeiras

extensions/diffs/README.md

@@ -16,6 +16,8 @@ The tool can return:
 - `details.filePath`: a local rendered artifact path when file rendering is requested
 - `details.fileFormat`: the rendered file format (`png` or `pdf`)
 
+When the plugin is enabled, it also ships a companion skill from `skills/` that guides when to use `diffs`. This guidance is delivered through normal skill loading, not unconditional prompt-hook injection on every turn.
+
 This means an agent can:
 
 - call `diffs` with `mode=view`, then pass `details.viewerUrl` to `canvas present`

extensions/diffs/index.test.ts

@@ -4,7 +4,7 @@ import { createMockServerResponse } from "../../src/test-utils/mock-http-respons
 import plugin from "./index.js";
 
 describe("diffs plugin registration", () => {
-  it("registers the tool, http route, and prompt guidance hook", () => {
+  it("registers the tool and http route", () => {
     const registerTool = vi.fn();
     const registerHttpRoute = vi.fn();
     const on = vi.fn();
@@ -43,8 +43,7 @@ describe("diffs plugin registration", () => {
       auth: "plugin",
       match: "prefix",
     });
-    expect(on).toHaveBeenCalledTimes(1);
-    expect(on.mock.calls[0]?.[0]).toBe("before_prompt_build");
+    expect(on).not.toHaveBeenCalled();
   });
 
   it("applies plugin-config defaults through registered tool and viewer handler", async () => {

extensions/diffs/index.ts

@@ -7,7 +7,6 @@ import {
   resolveDiffsPluginSecurity,
 } from "./src/config.js";
 import { createDiffsHttpHandler } from "./src/http.js";
-import { DIFFS_AGENT_GUIDANCE } from "./src/prompt-guidance.js";
 import { DiffArtifactStore } from "./src/store.js";
 import { createDiffsTool } from "./src/tool.js";
 
@@ -35,9 +34,6 @@ const plugin = {
         allowRemoteViewer: security.allowRemoteViewer,
       }),
     });
-    api.on("before_prompt_build", async () => ({
-      prependContext: DIFFS_AGENT_GUIDANCE,
-    }));
   },
 };
 

extensions/diffs/openclaw.plugin.json

@@ -2,6 +2,7 @@
   "id": "diffs",
   "name": "Diffs",
   "description": "Read-only diff viewer and file renderer for agents.",
+  "skills": ["./skills"],
   "uiHints": {
     "defaults.fontFamily": {
       "label": "Default Font",

extensions/diffs/skills/diffs/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: diffs
+description: Use the diffs tool to produce real, shareable diffs (viewer URL, file artifact, or both) instead of manual edit summaries.
+---
+
+When you need to show edits as a real diff, prefer the `diffs` tool instead of writing a manual summary.
+
+The `diffs` tool accepts either `before` + `after` text, or a unified `patch` string.
+
+Use `mode=view` when you want an interactive gateway-hosted viewer. After the tool returns, use `details.viewerUrl` with the canvas tool via `canvas present` or `canvas navigate`.
+
+Use `mode=file` when you need a rendered file artifact. Set `fileFormat=png` (default) or `fileFormat=pdf`. The tool result includes `details.filePath`.
+
+For large or high-fidelity files, use `fileQuality` (`standard`|`hq`|`print`) and optionally override `fileScale`/`fileMaxWidth`.
+
+When you need to deliver the rendered file to a user or channel, do not rely on the raw tool-result renderer. Instead, call the `message` tool and pass `details.filePath` through `path` or `filePath`.
+
+Use `mode=both` when you want both the gateway viewer URL and the rendered artifact.
+
+If the user has configured diffs plugin defaults, prefer omitting `mode`, `theme`, `layout`, and related presentation options unless you need to override them for this specific diff.
+
+Include `path` for before/after text when you know the file name.

extensions/diffs/src/prompt-guidance.ts

@@ -1,11 +0,0 @@
-export const DIFFS_AGENT_GUIDANCE = [
-  "When you need to show edits as a real diff, prefer the `diffs` tool instead of writing a manual summary.",
-  "The `diffs` tool accepts either `before` + `after` text, or a unified `patch` string.",
-  "Use `mode=view` when you want an interactive gateway-hosted viewer. After the tool returns, use `details.viewerUrl` with the canvas tool via `canvas present` or `canvas navigate`.",
-  "Use `mode=file` when you need a rendered file artifact. Set `fileFormat=png` (default) or `fileFormat=pdf`. The tool result includes `details.filePath`.",
-  "For large or high-fidelity files, use `fileQuality` (`standard`|`hq`|`print`) and optionally override `fileScale`/`fileMaxWidth`.",
-  "When you need to deliver the rendered file to a user or channel, do not rely on the raw tool-result renderer. Instead, call the `message` tool and pass `details.filePath` through `path` or `filePath`.",
-  "Use `mode=both` when you want both the gateway viewer URL and the rendered artifact.",
-  "If the user has configured diffs plugin defaults, prefer omitting `mode`, `theme`, `layout`, and related presentation options unless you need to override them for this specific diff.",
-  "Include `path` for before/after text when you know the file name.",
-].join("\n");