feat: add support for implicit invocation control in skills

Author: qorzj

src/prompt.ts

@@ -3,6 +3,7 @@ import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 import ejs from "ejs";
+import matter from "gray-matter";
 import { fileURLToPath } from "url";
 import type { SessionMessage } from "./session";
 import { findGitBashPath, resolveShellPath } from "./common/shell-utils";
@@ -184,11 +185,27 @@ export function buildSkillDocumentsPrompt(skills: SkillPromptDocument[]): string
 function renderSkillDocumentBlock(skill: SkillPromptDocument): string {
   const pathAttribute = skill.path ? ` path="${escapeXml(skill.path)}"` : "";
   const resources = renderSkillResources(skill.skillFilePath);
+  const content = stripSkillPromptMetadata(skill.content);
   return `<${skill.name}-skill${pathAttribute}>
-${skill.content}${resources}
+${content}${resources}
 </${skill.name}-skill>`;
 }
 
+function stripSkillPromptMetadata(content: string): string {
+  try {
+    const parsed = matter(content);
+    if (!Object.prototype.hasOwnProperty.call(parsed.data, "metadata")) {
+      return content;
+    }
+
+    const frontmatter = { ...parsed.data };
+    delete frontmatter.metadata;
+    return matter.stringify(parsed.content, frontmatter);
+  } catch {
+    return content;
+  }
+}
+
 function renderSkillResources(skillFilePath?: string): string {
   if (!skillFilePath) {
     return "";

src/session.ts

@@ -289,6 +289,7 @@ export type SkillInfo = {
   path: string;
   description: string;
   isLoaded?: boolean;
+  allowImplicitInvocation?: boolean;
 };
 
 type SessionManagerOptions = {
@@ -732,13 +733,14 @@ Response in JSON format:
 If none of the available skills match, respond with an empty array, i.e. \`{"skillNames": []}\`.\n
 `;
     const simpleSkills = skills
-      .filter((x) => !x.isLoaded)
+      .filter((x) => !x.isLoaded && x.allowImplicitInvocation !== false)
       .map((x) => {
         return { name: x.name, description: x.description };
       });
     if (simpleSkills.length === 0) {
       return [];
     }
+    const candidateSkillNames = new Set(simpleSkills.map((skill) => skill.name));
 
     const { client, model, baseURL, debugLogEnabled } = this.createOpenAIClient();
     if (!client) {
@@ -787,7 +789,10 @@ ${agentInstructions}
 
       const parsed = JSON.parse(content);
       if (parsed && Array.isArray(parsed.skillNames)) {
-        return parsed.skillNames;
+        return parsed.skillNames.filter(
+          (skillName: unknown): skillName is string =>
+            typeof skillName === "string" && candidateSkillNames.has(skillName)
+        );
       }
 
       return [];
@@ -938,13 +943,22 @@ ${agentInstructions}
     try {
       const skillMd = fs.readFileSync(skillPath, "utf8");
       const parsed = matter(skillMd);
+      const metadata = parsed.data.metadata;
+      const allowImplicitInvocation =
+        metadata &&
+        typeof metadata === "object" &&
+        !Array.isArray(metadata) &&
+        (metadata as Record<string, unknown>)["allow-implicit-invocation"] === false
+          ? false
+          : undefined;
       return {
         name:
           typeof parsed.data.name === "string" && parsed.data.name.trim()
             ? parsed.data.name.trim()
             : fallbackSkill.name,
         path: displayPath,
         description: typeof parsed.data.description === "string" ? parsed.data.description.trim() : "",
+        allowImplicitInvocation,
       };
     } catch {
       return fallbackSkill;

src/tests/prompt.test.ts

@@ -88,6 +88,27 @@ test("getDefaultSkillPrompt loads the default skill template", () => {
   assert.equal(prompt.includes('path="templates/skills/'), false);
 });
 
+test("buildSkillDocumentsPrompt excludes SKILL.md frontmatter metadata", () => {
+  const prompt = buildSkillDocumentsPrompt([
+    {
+      name: "example",
+      content:
+        "---\nname: example\ndescription: Example skill\nlicense: MIT\ncompatibility: Node.js\nallowed-tools: Read Bash\nmetadata:\n  author: test\n  allow-implicit-invocation: false\n---\n# Example Skill\n\nUse these instructions.\n",
+    },
+  ]);
+
+  assert.equal(prompt.includes("name: example"), true);
+  assert.equal(prompt.includes("description: Example skill"), true);
+  assert.equal(prompt.includes("license: MIT"), true);
+  assert.equal(prompt.includes("compatibility: Node.js"), true);
+  assert.equal(prompt.includes("allowed-tools: Read Bash"), true);
+  assert.equal(prompt.includes("# Example Skill"), true);
+  assert.equal(prompt.includes("Use these instructions."), true);
+  assert.equal(prompt.includes("metadata:"), false);
+  assert.equal(prompt.includes("author: test"), false);
+  assert.equal(prompt.includes("allow-implicit-invocation"), false);
+});
+
 test("buildSkillDocumentsPrompt lists skill resources", () => {
   const skillDir = createTempDir("deepcode-skill-resources-");
   fs.mkdirSync(path.join(skillDir, "scripts"), { recursive: true });

src/tests/session.test.ts

@@ -644,6 +644,78 @@ test("SessionManager excludes disabled skills by resolved skill name", async ()
   assert.equal(skills[0]?.path, "./.deepcode/skills/enabled-skill/SKILL.md");
 });
 
+test("SessionManager keeps implicit opt-out skills available for manual invocation", async () => {
+  const workspace = createTempDir("deepcode-manual-only-skill-workspace-");
+  const home = createTempDir("deepcode-manual-only-skill-home-");
+  setHomeDir(home);
+
+  const skillDir = path.join(workspace, ".agents", "skills", "manual-only");
+  fs.mkdirSync(skillDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(skillDir, "SKILL.md"),
+    "---\nname: manual-only\ndescription: Manual-only skill\nmetadata:\n  allow-implicit-invocation: false\n---\n# Manual Only\n",
+    "utf8"
+  );
+
+  const manager = createSessionManager(workspace, "machine-id-manual-only-skill");
+  const skill = (await manager.listSkills()).find((candidate) => candidate.name === "manual-only");
+  assert.ok(skill);
+  assert.equal(skill.allowImplicitInvocation, false);
+
+  const sessionId = await manager.createSession({ text: "", skills: [skill] });
+  const skillMessages = manager
+    .listSessionMessages(sessionId)
+    .filter((message) => message.role === "system" && message.meta?.skill?.name === "manual-only");
+
+  assert.equal(skillMessages.length, 1);
+  assert.match(skillMessages[0]?.content ?? "", /<manual-only-skill/);
+  assert.doesNotMatch(skillMessages[0]?.content ?? "", /allow-implicit-invocation/);
+});
+
+test("SessionManager excludes implicit opt-out skills from automatic matching candidates", async () => {
+  const workspace = createTempDir("deepcode-implicit-opt-out-workspace-");
+  const home = createTempDir("deepcode-implicit-opt-out-home-");
+  setHomeDir(home);
+  globalThis.fetch = (async () => ({ ok: true, text: async () => "" }) as Response) as typeof fetch;
+
+  const writeSkill = (name: string, metadata = ""): void => {
+    const skillDir = path.join(workspace, ".deepcode", "skills", name);
+    fs.mkdirSync(skillDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(skillDir, "SKILL.md"),
+      `---\nname: ${name}\ndescription: ${name} description${metadata}\n---\n# ${name}\n`,
+      "utf8"
+    );
+  };
+  writeSkill("auto-skill");
+  writeSkill("manual-only", "\nmetadata:\n  allow-implicit-invocation: false");
+
+  const requests: any[] = [];
+  const client = {
+    chat: {
+      completions: {
+        create: async (request: any) => {
+          requests.push(request);
+          if (isSkillMatchingRequest(request)) {
+            return createSkillMatchingResponse(["manual-only", "auto-skill"]);
+          }
+          return createChatResponse("done", { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 });
+        },
+      },
+    },
+  };
+  const manager = createMockedClientSessionManagerWithClient(workspace, client);
+  (manager as any).activateSession = async () => {};
+
+  const sessionId = await manager.createSession({ text: "choose an automatic skill" });
+  const matchingPrompt = String(requests[0]?.messages?.[0]?.content ?? "");
+
+  assert.match(matchingPrompt, /"name": "auto-skill"/);
+  assert.doesNotMatch(matchingPrompt, /"name": "manual-only"/);
+  assert.equal(countLoadedSkillMessages(manager.listSessionMessages(sessionId), "auto-skill"), 1);
+  assert.equal(countLoadedSkillMessages(manager.listSessionMessages(sessionId), "manual-only"), 0);
+});
+
 test("SessionManager dispose disconnects MCP servers", async () => {
   const workspace = createTempDir("deepcode-mcp-dispose-workspace-");
   const serverPath = path.join(workspace, "mcp-server.cjs");