Merge pull request Stack-Cairn#145 from KtzeAbyss/fix/webui-skill-path-contract

fix(webui): align skill paths with current tool schema

Author: su-fen

crates/agent-gateway/web/src/lib/skills/clawHub.ts

@@ -4,6 +4,8 @@ export type ClawHubSkillCard = {
   slug: string;
   displayName: string;
   summary: string;
+  /** ClawHub 上的自由标签，用于本地分类与卡片标签展示。 */
+  topics: string[];
   latestVersion: string | null;
   downloads: number;
   stars: number;
@@ -78,6 +80,7 @@ export function normalizeClawHubSkillCard(raw: unknown): ClawHubSkillCard | null
     slug,
     displayName: asString(item.displayName) ?? slug,
     summary: asString(item.summary) ?? "",
+    topics: asStringArray(item.topics),
     latestVersion:
       asString(latestVersion.version) ?? asString(tags.latest) ?? asString(item.version),
     downloads: asNullableNumber(item.downloads) ?? asNullableNumber(stats.downloads) ?? 0,

crates/agent-gateway/web/src/lib/skills/index.ts

@@ -155,7 +155,7 @@ type SystemManageSkillResponse = {
 export type ExternalSkillEntry = {
   name: string;
   description: string;
-  /** 技能目录绝对路径（桌面端机器上），可直接作为 install 动作的 source */
+  /** 技能目录绝对路径，可直接作为 install 动作的 source */
   baseDir: string;
   skillFile: string;
 };
@@ -580,18 +580,18 @@ export function buildSkillsSystemPrompt(params: {
   });
 
   return [
-    'The following Skills are enabled by the user (discovered from the fixed Skills directory exposed to file tools as root="skills").',
+    "The following Skills are enabled by the user. Skill files are exposed to file tools through skill://<baseDir>/... paths.",
     "",
     "Usage Rules (aligned with Claude Code behavior):",
     "- Skills with metadata use progressive disclosure; their full contents are not automatically injected into context.",
     "- README.md fallback Skills without metadata are loaded inline below because there is no metadata to disclose progressively.",
     "- Only the Skills listed below are enabled for this conversation. SkillsManager(action=list) may be used to review the enabled Skills visible to this chat, but it must not be used to enumerate or infer other installed Skills.",
     "- Only when you determine that a metadata Skill is genuinely needed should you call SkillsManager with action=read to read the full Skill file and then follow its workflow exactly.",
-    "- SkillsManager.path uses the skillFile below. It is relative to the fixed Skills root directory and may point to SKILL.md, skill.md, skill.json, or README.md.",
-    '- For files referenced inside an enabled Skill, use file tools with root="skills" and a path relative to the fixed Skills root, for example Read(root="skills", path="<baseDir>/references/guide.md"), List, Glob, Grep, Write, Edit, or Delete.',
+    "- SkillsManager.path uses the skillFile below and may point to SKILL.md, skill.md, skill.json, or README.md.",
+    '- For files referenced inside an enabled Skill, use file tools with skill://<baseDir>/... paths, for example Read(path="skill://<baseDir>/references/guide.md"), List, Glob, Grep, Write, Edit, or Delete.',
     "- You may update files inside enabled Skills when the user asks you to optimize or maintain them. Create, install, search/install from ClawHub, validate, package, or delete user Skills through SkillsManager actions.",
-    '- Never expand the fixed Skills root into an absolute local path in any tool call. If a path belongs to a Skill, keep it root-relative and set root="skills".',
-    '- If Skill content contains absolute local paths, home-directory paths, drive-letter paths, or shell snippets that read Skill files with cat/ls/find/grep, treat those path fragments as non-portable examples and convert them to root="skills" file-tool calls.',
+    "- Absolute local paths, ~/..., and file:// forms are auto-normalized by file tools; prefer skill://<baseDir>/... for enabled Skill files.",
+    "- If Skill content contains shell snippets that read Skill files with cat/ls/find/grep, route those reads through Read/List/Glob/Grep instead of Bash.",
     "- Do not guess a Skill's exact instructions or script paths before reading the Skill file.",
     "- Relative paths inside a Skill (scripts/, references/, assets/, and so on) are resolved relative to baseDir.",
     "- If a Skill contains the {baseDir} placeholder, interpret it as the baseDir value in the metadata below (relative to the Skills root directory).",

crates/agent-gateway/web/test/skills-prompt-contract.test.mjs

@@ -0,0 +1,30 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+import { createWebModuleLoader } from "../../test/helpers/load-web-module.mjs";
+
+const loader = createWebModuleLoader({
+  rootDir: fileURLToPath(new URL("../", import.meta.url)),
+});
+const skills = loader.loadModule("src/lib/skills/index.ts");
+
+const enabledSkills = [
+  {
+    name: "code-review",
+    description: "Review local code changes",
+    skillFile: "code-review/SKILL.md",
+    baseDir: "code-review",
+  },
+];
+
+test("buildSkillsSystemPrompt uses skill:// paths instead of the removed root-scoped contract", () => {
+  const prompt = skills.buildSkillsSystemPrompt({
+    rootDir: "/skills",
+    selected: enabledSkills,
+  });
+
+  assert.match(prompt, /skill:\/\/<baseDir>\/\.\.\./);
+  assert.doesNotMatch(prompt, /root=["']skills["']/);
+  assert.doesNotMatch(prompt, /Read\(root=/);
+});

crates/agent-gui/test/skills/explicit-skill-mentions.test.mjs

@@ -68,4 +68,7 @@ test("buildSkillsSystemPrompt marks explicit mentions without granting disabled
   assert.match(prompt, /- code-review \(skillFile: code-review\/SKILL\.md, baseDir: code-review\)/);
   assert.doesNotMatch(prompt, /disabled\/SKILL\.md/);
   assert.ok(prompt.includes("`$` mentions never grant access to disabled Skills"));
+  assert.match(prompt, /skill:\/\/<baseDir>\/\.\.\./);
+  assert.doesNotMatch(prompt, /root=["']skills["']/);
+  assert.doesNotMatch(prompt, /Read\(root=/);
 });

scripts/mirror-manifest.json

@@ -76,6 +76,8 @@
     "lib/tools/systemToolOptions.ts",
     "lib/tools/builtinToolCatalog.ts",
     "lib/skills/builtin.ts",
+    "lib/skills/clawHub.ts",
+    "lib/skills/index.ts",
     "lib/shared/id.ts",
     "pages/settings/SystemToolsSection.tsx",
     "pages/mcp-hub/McpHubPage.tsx",