From 5f93106ed2f364747acf1c0441565ee7c8e9ff95 Mon Sep 17 00:00:00 2001
From: Mariano Belinky <mbelinky@gmail.com>
Date: Sat, 2 May 2026 09:53:13 +0200
Subject: [PATCH] Improve skills check visibility wording

---
 docs/tools/skills.md         |  4 +++-
 src/cli/skills-cli.format.ts | 20 ++++++++++++++++++++
 src/cli/skills-cli.test.ts   |  3 +++
 3 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/docs/tools/skills.md b/docs/tools/skills.md
index 37f1e0dc540..b9320c6b029 100644
--- a/docs/tools/skills.md
+++ b/docs/tools/skills.md
@@ -188,7 +188,9 @@ instructions to reference the skill folder path.
   When `true`, the skill is exposed as a user slash command.
 </ParamField>
 <ParamField path="disable-model-invocation" type="boolean" default="false">
-  When `true`, the skill is excluded from the model prompt (still available via user invocation).
+  When `true`, OpenClaw keeps the skill's instructions out of the agent's normal
+  prompt. The skill is still installed and can still be run explicitly as a
+  slash command when `user-invocable` is also `true`.
 </ParamField>
 <ParamField path="command-dispatch" type='"tool"'>
   When set to `tool`, the slash command bypasses the model and dispatches directly to a tool.
diff --git a/src/cli/skills-cli.format.ts b/src/cli/skills-cli.format.ts
index 107620efe3e..acbeb8d6b13 100644
--- a/src/cli/skills-cli.format.ts
+++ b/src/cli/skills-cli.format.ts
@@ -374,6 +374,26 @@ export function formatSkillsCheck(report: SkillStatusReport, opts: SkillsCheckOp
   }
   lines.push(`${theme.error("✗")} ${theme.muted("Missing requirements:")} ${missingReqs.length}`);
 
+  if (modelVisible.length > 0 || commandVisible.length > 0 || promptHidden.length > 0) {
+    lines.push("");
+    lines.push(theme.heading("What this means:"));
+    if (modelVisible.length > 0) {
+      lines.push(
+        `  ${theme.muted("Visible to model:")} the agent can see the skill instructions during normal chat.`,
+      );
+    }
+    if (commandVisible.length > 0) {
+      lines.push(
+        `  ${theme.muted("Available as command:")} people, scripts, or cron jobs can call the skill explicitly.`,
+      );
+    }
+    if (promptHidden.length > 0) {
+      lines.push(
+        `  ${theme.muted("Hidden from model prompt:")} installed and ready, but kept out of normal chat unless called explicitly.`,
+      );
+    }
+  }
+
   if (modelVisible.length > 0) {
     lines.push("");
     lines.push(theme.heading("Ready and visible to model:"));
diff --git a/src/cli/skills-cli.test.ts b/src/cli/skills-cli.test.ts
index becc702b874..9c445b5185e 100644
--- a/src/cli/skills-cli.test.ts
+++ b/src/cli/skills-cli.test.ts
@@ -269,6 +269,9 @@ describe("skills-cli", () => {
       expect(output).toContain("prompt-hidden");
       expect(output).toContain("Excluded by agent allowlist");
       expect(output).toContain("not-assigned");
+      expect(output).toContain("What this means");
+      expect(output).toContain("people, scripts, or cron jobs can call the skill explicitly");
+      expect(output).toContain("kept out of normal chat unless called explicitly");
     });
 
     it("summarizes a mixed bad skill pack in JSON", () => {