feat: add skill resource management and update skill document rendering

Author: qorzj

src/prompt.ts

@@ -100,6 +100,30 @@ type PromptToolOptions = {
 };
 
 const DEFAULT_SKILL_TEMPLATES = ["karpathy-guidelines.md"];
+const DEFAULT_SKILL_RESOURCE_FILE_LIMIT = 50;
+const SKILL_RESOURCE_EXCLUDED_DIRS = new Set([
+  ".cache",
+  ".git",
+  ".next",
+  ".turbo",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+  "out",
+]);
+
+export type SkillPromptDocument = {
+  name: string;
+  content: string;
+  path?: string;
+  skillFilePath?: string;
+};
+
+type SkillResourceListing = {
+  files: string[];
+  truncated: boolean;
+};
 
 function readToolDocs(extensionRoot: string, options: PromptToolOptions = {}): string {
   const toolsDir = path.join(extensionRoot, "templates", "tools");
@@ -149,14 +173,99 @@ export function getDefaultSkillPrompt(): string {
     return "";
   }
 
-  const blocks = skillDocs.map(
-    (skill) => `<${skill.name}-skill>
-${skill.content}
-</${skill.name}-skill>`
-  );
+  return buildSkillDocumentsPrompt(skillDocs);
+}
+
+export function buildSkillDocumentsPrompt(skills: SkillPromptDocument[]): string {
+  const blocks = skills.map((skill) => renderSkillDocumentBlock(skill));
   return `Use the skill documents below to assist the user:\n${blocks.join("\n\n")}`;
 }
 
+function renderSkillDocumentBlock(skill: SkillPromptDocument): string {
+  const pathAttribute = skill.path ? ` path="${escapeXml(skill.path)}"` : "";
+  const resources = renderSkillResources(skill.skillFilePath);
+  return `<${skill.name}-skill${pathAttribute}>
+${skill.content}${resources}
+</${skill.name}-skill>`;
+}
+
+function renderSkillResources(skillFilePath?: string): string {
+  if (!skillFilePath) {
+    return "";
+  }
+
+  const listing = listSkillResourceFiles(skillFilePath, DEFAULT_SKILL_RESOURCE_FILE_LIMIT);
+  if (listing.files.length === 0 && !listing.truncated) {
+    return "";
+  }
+
+  const fileLines = listing.files.map((file) => `  <file>${escapeXml(file)}</file>`);
+  const noteLine = listing.truncated
+    ? [`  <note>Listing capped at ${DEFAULT_SKILL_RESOURCE_FILE_LIMIT} files and may be incomplete.</note>`]
+    : [];
+  return `\n\n<skill_resources>\n${[...fileLines, ...noteLine].join("\n")}\n</skill_resources>`;
+}
+
+function listSkillResourceFiles(skillFilePath: string, limit: number): SkillResourceListing {
+  const skillDir = path.dirname(skillFilePath);
+  const files: string[] = [];
+  let truncated = false;
+
+  const visit = (dir: string, relativeDir = ""): void => {
+    if (files.length > limit) {
+      truncated = true;
+      return;
+    }
+
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) {
+        continue;
+      }
+
+      const relativePath = relativeDir ? path.join(relativeDir, entry.name) : entry.name;
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (SKILL_RESOURCE_EXCLUDED_DIRS.has(entry.name)) {
+          continue;
+        }
+        visit(fullPath, relativePath);
+        if (truncated) {
+          return;
+        }
+        continue;
+      }
+
+      if (!entry.isFile() || entry.name === "SKILL.md") {
+        continue;
+      }
+
+      files.push(toPosixPath(relativePath));
+      if (files.length > limit) {
+        truncated = true;
+        return;
+      }
+    }
+  };
+
+  visit(skillDir);
+  return { files: files.slice(0, limit), truncated };
+}
+
+function toPosixPath(filePath: string): string {
+  return filePath.split(path.sep).join("/");
+}
+
+function escapeXml(value: string): string {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
 function getCurrentDateAndModelPrompt(model?: string): string {
   const date = new Date();
   let prompt = `今天是${date.getFullYear()}年${date.getMonth() + 1}月${date.getDate()}日。随着对话的进行，时间在流逝。`;

src/session.ts

@@ -10,6 +10,7 @@ import { buildThinkingRequestOptions } from "./common/openai-thinking";
 import { DEEPSEEK_V4_MODELS } from "./common/model-capabilities";
 import { readTextFileWithMetadata } from "./common/file-utils";
 import {
+  buildSkillDocumentsPrompt,
   getCompactPrompt,
   getDefaultSkillPrompt,
   getExtensionRoot,
@@ -878,6 +879,18 @@ ${agentInstructions}
     return path.join(os.homedir(), skillPath);
   }
 
+  private buildSkillPrompt(skill: SkillInfo): string {
+    const skillPath = this.resolveSkillPath(skill.path);
+    return buildSkillDocumentsPrompt([
+      {
+        name: skill.name,
+        content: fs.readFileSync(skillPath, "utf8"),
+        path: skillPath,
+        skillFilePath: skillPath,
+      },
+    ]);
+  }
+
   private readSkillInfo(skillPath: string, displayPath: string, fallbackName: string): SkillInfo {
     const fallbackSkill: SkillInfo = {
       name: fallbackName.replace(/_/g, "-"),
@@ -1101,11 +1114,7 @@ ${agentInstructions}
         if (skill.isLoaded) {
           continue;
         }
-        const skillMd = fs.readFileSync(this.resolveSkillPath(skill.path), "utf8");
-        const skillPrompt = `Use the skill document below to assist the user:\n
-<${skill.name}-skill path="${this.resolveSkillPath(skill.path)}">
-${skillMd}
-</${skill.name}-skill>`;
+        const skillPrompt = this.buildSkillPrompt(skill);
         const skillMessage = this.buildSkillMessage(sessionId, skillPrompt, skill);
         this.appendSessionMessage(sessionId, skillMessage);
         this.onAssistantMessage(skillMessage, true);
@@ -1180,11 +1189,7 @@ ${skillMd}
         if (skill.isLoaded) {
           continue;
         }
-        const skillMd = fs.readFileSync(this.resolveSkillPath(skill.path), "utf8");
-        const skillPrompt = `Use the skill document below to assist the user:\n
-<${skill.name}-skill path="${this.resolveSkillPath(skill.path)}">
-${skillMd}
-</${skill.name}-skill>`;
+        const skillPrompt = this.buildSkillPrompt(skill);
         const skillMessage = this.buildSkillMessage(sessionId, skillPrompt, skill);
         this.appendSessionMessage(sessionId, skillMessage);
         this.onAssistantMessage(skillMessage, true);
@@ -2335,11 +2340,7 @@ ${skillMd}
         if (skill.isLoaded) {
           continue;
         }
-        const skillMd = fs.readFileSync(this.resolveSkillPath(skill.path), "utf8");
-        const skillPrompt = `Use the skill document below to assist the user:\n
-<${skill.name}-skill path="${this.resolveSkillPath(skill.path)}">
-${skillMd}
-</${skill.name}-skill>`;
+        const skillPrompt = this.buildSkillPrompt(skill);
         const skillMessage = this.buildSkillMessage(sessionId, skillPrompt, skill);
         this.appendSessionMessage(sessionId, skillMessage);
         this.onAssistantMessage(skillMessage, true);

src/tests/prompt.test.ts

@@ -1,11 +1,31 @@
-import { test } from "node:test";
+import { afterEach, test } from "node:test";
 import assert from "node:assert/strict";
 import * as fs from "fs";
+import * as os from "os";
 import * as path from "path";
 import { fileURLToPath } from "url";
-import { getDefaultSkillPrompt, getRuntimeContext, getSystemPrompt, getTools } from "../prompt";
+import {
+  buildSkillDocumentsPrompt,
+  getDefaultSkillPrompt,
+  getRuntimeContext,
+  getSystemPrompt,
+  getTools,
+} from "../prompt";
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+const tempDirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+function createTempDir(prefix: string): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  tempDirs.push(dir);
+  return dir;
+}
 
 test("getTools always includes WebSearch", () => {
   const names = getTools().map((tool) => tool.function.name);
@@ -68,6 +88,70 @@ test("getDefaultSkillPrompt loads the default skill template", () => {
   assert.equal(prompt.includes('path="templates/skills/'), false);
 });
 
+test("buildSkillDocumentsPrompt lists skill resources", () => {
+  const skillDir = createTempDir("deepcode-skill-resources-");
+  fs.mkdirSync(path.join(skillDir, "scripts"), { recursive: true });
+  fs.mkdirSync(path.join(skillDir, "references"), { recursive: true });
+  const skillPath = path.join(skillDir, "SKILL.md");
+  fs.writeFileSync(skillPath, "# PDF Skill\n", "utf8");
+  fs.writeFileSync(path.join(skillDir, "scripts", "extract.py"), "print('extract')\n", "utf8");
+  fs.writeFileSync(path.join(skillDir, "scripts", "merge.py"), "print('merge')\n", "utf8");
+  fs.writeFileSync(path.join(skillDir, "references", "pdf-spec-summary.md"), "# PDF Spec\n", "utf8");
+
+  const prompt = buildSkillDocumentsPrompt([
+    { name: "pdf", content: "# PDF Skill", path: skillPath, skillFilePath: skillPath },
+  ]);
+
+  assert.equal(prompt.includes(`<pdf-skill path="${skillPath}">`), true);
+  assert.equal(prompt.includes("<skill_resources>"), true);
+  assert.equal(prompt.includes("<file>scripts/extract.py</file>"), true);
+  assert.equal(prompt.includes("<file>scripts/merge.py</file>"), true);
+  assert.equal(prompt.includes("<file>references/pdf-spec-summary.md</file>"), true);
+  assert.equal(prompt.includes("<file>SKILL.md</file>"), false);
+});
+
+test("buildSkillDocumentsPrompt caps large skill resource listings", () => {
+  const skillDir = createTempDir("deepcode-skill-resource-cap-");
+  const skillPath = path.join(skillDir, "SKILL.md");
+  fs.writeFileSync(skillPath, "# Large Skill\n", "utf8");
+  for (let index = 0; index < 55; index += 1) {
+    fs.writeFileSync(path.join(skillDir, `file-${String(index).padStart(2, "0")}.txt`), "resource\n", "utf8");
+  }
+
+  const prompt = buildSkillDocumentsPrompt([
+    { name: "large", content: "# Large Skill", path: skillPath, skillFilePath: skillPath },
+  ]);
+
+  assert.equal((prompt.match(/<file>/g) ?? []).length, 50);
+  assert.equal(prompt.includes("<file>file-49.txt</file>"), true);
+  assert.equal(prompt.includes("<file>file-50.txt</file>"), false);
+  assert.equal(prompt.includes("Listing capped at 50 files and may be incomplete."), true);
+});
+
+test("buildSkillDocumentsPrompt excludes hidden and generated skill resources", () => {
+  const skillDir = createTempDir("deepcode-skill-resource-exclusions-");
+  fs.mkdirSync(path.join(skillDir, ".hidden"), { recursive: true });
+  fs.mkdirSync(path.join(skillDir, "node_modules", "pkg"), { recursive: true });
+  fs.mkdirSync(path.join(skillDir, "dist"), { recursive: true });
+  const skillPath = path.join(skillDir, "SKILL.md");
+  fs.writeFileSync(skillPath, "# Clean Skill\n", "utf8");
+  fs.writeFileSync(path.join(skillDir, ".secret.txt"), "hidden\n", "utf8");
+  fs.writeFileSync(path.join(skillDir, ".hidden", "file.txt"), "hidden\n", "utf8");
+  fs.writeFileSync(path.join(skillDir, "node_modules", "pkg", "index.js"), "module.exports = {}\n", "utf8");
+  fs.writeFileSync(path.join(skillDir, "dist", "bundle.js"), "bundle\n", "utf8");
+  fs.writeFileSync(path.join(skillDir, "README.md"), "# Resource\n", "utf8");
+
+  const prompt = buildSkillDocumentsPrompt([
+    { name: "clean", content: "# Clean Skill", path: skillPath, skillFilePath: skillPath },
+  ]);
+
+  assert.equal(prompt.includes("<file>README.md</file>"), true);
+  assert.equal(prompt.includes(".secret.txt"), false);
+  assert.equal(prompt.includes(".hidden/file.txt"), false);
+  assert.equal(prompt.includes("node_modules/pkg/index.js"), false);
+  assert.equal(prompt.includes("dist/bundle.js"), false);
+});
+
 test("getSystemPrompt does not include current date guidance", () => {
   const now = new Date();
   const expected = `今天是${now.getFullYear()}年${now.getMonth() + 1}月${now.getDate()}日。随着对话的进行，时间在流逝。`;