fix(skills): cap slash-picker line and drop dangling worker pointers

Author: TheGreatAxios

src/agent/skill-search.ts

@@ -39,7 +39,7 @@ export const skillSearchDefinition: ToolDefinition = {
 export const workerSkillSearchDefinition: ToolDefinition = {
   name: "skill_search",
   description:
-    "Prep lookup for a skill when attached skills are not enough; skip tiny one-file fixes. Directly callable; load via use_skill. See Guidelines: Tool choice.",
+    "Prep lookup for a skill when attached skills are not enough; skip tiny one-file fixes. Directly callable; load via use_skill.",
   inputSchema: SKILL_SEARCH_INPUT_SCHEMA,
 };
 

src/agent/use-skill.ts

@@ -36,7 +36,7 @@ export const useSkillDefinition: ToolDefinition = {
 export const workerUseSkillDefinition: ToolDefinition = {
   name: "use_skill",
   description:
-    "Load a skill by name; do not reload attached skills or bodies already in context. See Guidelines: Tool choice.",
+    "Load a skill by name; do not reload attached skills or bodies already in context.",
   inputSchema: USE_SKILL_INPUT_SCHEMA,
 };
 

src/plugins/skill-commands.ts

@@ -5,6 +5,7 @@ import {
   type CommandDefinition,
   type CommandResult,
 } from "../tui/commands/registry.js";
+import { firstLine } from "../extensions/skills.js";
 import { COMMAND_NAME_PATTERN, splitFrontmatter } from "./frontmatter.js";
 
 // Slash is the operator action surface: `/<skill-name> [args]` sends the skill
@@ -72,8 +73,8 @@ export async function loadSkillCommands(
     }
     const description =
       typeof frontmatter.description === "string" &&
-      frontmatter.description.trim().length > 0
-        ? frontmatter.description.trim()
+      firstLine(frontmatter.description).length > 0
+        ? firstLine(frontmatter.description)
         : name;
 
     const argumentHint = argumentHintFromFrontmatter(frontmatter);

tests/unit/skills.test.ts

@@ -13,6 +13,7 @@ import {
   skillSearchDefinition,
   workerSkillSearchDefinition,
 } from "../../src/agent/skill-search.js";
+import { loadSkillCommands } from "../../src/plugins/skill-commands.js";
 import {
   useSkillDefinition,
   workerUseSkillDefinition,
@@ -276,18 +277,27 @@ describe("path-like skill refs", () => {
 describe("description caps (CL-8854)", () => {
   const MAX_DESCRIPTION_CHARS = 160;
 
-  test("all five registration descriptions are one line within the cap", () => {
-    const skillDescriptions = [
+  test("primary descriptions keep the pointer; worker copies are pointer-free, all one line within the cap", () => {
+    const primaryDescriptions = [
       skillSearchDefinition.description,
-      workerSkillSearchDefinition.description,
       useSkillDefinition.description,
-      workerUseSkillDefinition.description,
     ];
-    for (const description of skillDescriptions) {
+    for (const description of primaryDescriptions) {
       expect(description).not.toContain("\n");
       expect(description.length).toBeLessThanOrEqual(MAX_DESCRIPTION_CHARS);
       expect(description.endsWith("See Guidelines: Tool choice.")).toBe(true);
     }
+    // The lean worker contract ships no guidelines, so the worker copies must
+    // not point at them.
+    const workerDescriptions = [
+      workerSkillSearchDefinition.description,
+      workerUseSkillDefinition.description,
+    ];
+    for (const description of workerDescriptions) {
+      expect(description).not.toContain("\n");
+      expect(description.length).toBeLessThanOrEqual(MAX_DESCRIPTION_CHARS);
+      expect(description).not.toContain("See Guidelines:");
+    }
     expect(spawnAgentToolDefinition.description).not.toContain("\n");
     expect(spawnAgentToolDefinition.description.length).toBeLessThanOrEqual(
       MAX_DESCRIPTION_CHARS,
@@ -316,4 +326,25 @@ describe("description caps (CL-8854)", () => {
     );
     expect(out).toBe("- scribe: write docs");
   });
+
+  test("a multi-line SKILL.md frontmatter description renders as a single slash-picker line", async () => {
+    const plugin = await mkdtemp(join(tmpdir(), "skill-slash-multiline-"));
+    try {
+      await mkdir(join(plugin, "skills", "scribe"), { recursive: true });
+      await writeFile(
+        join(plugin, "skills", "scribe", "SKILL.md"),
+        "---\nname: scribe\ndescription: |\n  write docs\n  second line\n---\nScribe body.\n",
+        "utf8",
+      );
+      const cmds = defined(await loadSkillCommands(plugin), "skill commands");
+      const scribe = defined(
+        cmds.find((c) => c.name === "scribe"),
+        "scribe command",
+      );
+      expect(scribe.description).toBe("write docs");
+      expect(scribe.description).not.toContain("\n");
+    } finally {
+      await rm(plugin, { recursive: true, force: true });
+    }
+  });
 });