feat: Add custom skills support

raphaelluethy · raphaelluethy · commit 17fa7e1c4b9a · 2026-02-05T00:53:14.000+01:00
- Load skill.md files from workspace, user, and cursor directories
- Expose skills as /skill:&lt;name&gt; slash commands in sessions
- Resolve skill templates when user invokes skill commands
diff --git a/src/cursor-acp-agent.ts b/src/cursor-acp-agent.ts
@@ -41,7 +41,10 @@ import {
   CustomSlashCommand,
   handleSlashCommand,
   loadCustomSlashCommands,
+  resolveCustomSlashCommandPrompt,
+  resolveSkillSlashCommandPrompt,
 } from "./slash-commands.js";
+import { CustomSkill, loadCustomSkills } from "./skills.js";
 import {
   parseLeadingSlashCommand,
   promptToCursorText,
@@ -63,6 +66,7 @@ interface SessionState {
   modeId: SessionModeId;
   modelId?: string;
   customCommands: CustomSlashCommand[];
+  skills: CustomSkill[];
   cancelled: boolean;
   activeRun?: {
     cancel: () => void;
@@ -192,7 +196,7 @@ export class CursorAcpAgent implements Agent {
     }
 
     session.cancelled = false;
-    const promptText = promptToCursorText(params);
+    let promptText = promptToCursorText(params);
 
     const slash = parseLeadingSlashCommand(promptText);
     if (slash.hasSlash) {
@@ -201,6 +205,7 @@ export class CursorAcpAgent implements Agent {
         auth: this.auth,
         listModels: async () => await this.runner.listModels(),
         customCommands: session.customCommands,
+        skills: session.skills,
         onModeChanged: async (modeId) => {
           await this.client.sessionUpdate({
             sessionId: session.sessionId,
@@ -236,6 +241,24 @@ export class CursorAcpAgent implements Agent {
 
         return { stopReason: "end_turn" };
       }
+
+      const skillPrompt = resolveSkillSlashCommandPrompt(
+        slash.command,
+        session.skills,
+      );
+      if (skillPrompt) {
+        const extra = slash.args.trim();
+        promptText = extra ? `${skillPrompt}\n\n${extra}` : skillPrompt;
+      } else {
+        const customPrompt = resolveCustomSlashCommandPrompt(
+          slash.command,
+          slash.args,
+          session.customCommands,
+        );
+        if (customPrompt) {
+          promptText = customPrompt;
+        }
+      }
     }
 
     const firstAttempt = await this.runPromptAttempt(
@@ -346,6 +369,7 @@ export class CursorAcpAgent implements Agent {
       modeId,
       modelId,
       customCommands: [],
+      skills: [],
       cancelled: false,
     };
 
@@ -362,16 +386,11 @@ export class CursorAcpAgent implements Agent {
 
     const models = await this.getAvailableModels(session);
     session.customCommands = await this.getAvailableSlashCommands(session.cwd);
+    session.skills = await this.getAvailableSkills(session.cwd);
     this.sessions[session.sessionId] = session;
 
     setTimeout(() => {
-      void this.client.sessionUpdate({
-        sessionId: session.sessionId,
-        update: {
-          sessionUpdate: "available_commands_update",
-          availableCommands: availableSlashCommands(session.customCommands),
-        },
-      });
+      void this.emitAvailableCommands(session);
     }, 0);
 
     return {
@@ -422,6 +441,29 @@ export class CursorAcpAgent implements Agent {
     }
   }
 
+  private async getAvailableSkills(workspace: string): Promise<CustomSkill[]> {
+    try {
+      const skills = await loadCustomSkills(workspace);
+      return skills.filter((skill) => skill.origin === "user");
+    } catch (error) {
+      this.logger.error("[cursor-acp] Unable to load skills", error);
+      return [];
+    }
+  }
+
+  private async emitAvailableCommands(session: SessionState): Promise<void> {
+    await this.client.sessionUpdate({
+      sessionId: session.sessionId,
+      update: {
+        sessionUpdate: "available_commands_update",
+        availableCommands: availableSlashCommands(
+          session.customCommands,
+          session.skills,
+        ),
+      },
+    });
+  }
+
   private modeToRunnerOptions(
     session: SessionState,
     forceRetry: boolean,
diff --git a/src/skills.ts b/src/skills.ts
@@ -0,0 +1,175 @@
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export type SkillOrigin = "workspace" | "user" | "cursor";
+
+export interface CustomSkill {
+  name: string;
+  description: string;
+  template: string;
+  sourcePath: string;
+  origin: SkillOrigin;
+}
+
+async function collectSkillFiles(dir: string): Promise<string[]> {
+  let entries: import("node:fs").Dirent[];
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true, encoding: "utf8" });
+  } catch (error: unknown) {
+    if (
+      typeof error === "object" &&
+      error !== null &&
+      "code" in error &&
+      (error as { code?: string }).code === "ENOENT"
+    ) {
+      return [];
+    }
+    throw error;
+  }
+
+  entries.sort((a, b) => a.name.localeCompare(b.name));
+
+  const files: string[] = [];
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await collectSkillFiles(fullPath)));
+      continue;
+    }
+
+    if (entry.isFile() && entry.name.toLowerCase() === "skill.md") {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+function parseFrontmatter(markdown: string): {
+  metadata: Record<string, string>;
+  body: string;
+} {
+  const lines = markdown.split(/\r?\n/);
+  if (lines[0]?.trim() !== "---") {
+    return { metadata: {}, body: markdown };
+  }
+
+  let end = -1;
+  for (let i = 1; i < lines.length; i += 1) {
+    if (lines[i]?.trim() === "---") {
+      end = i;
+      break;
+    }
+  }
+
+  if (end === -1) {
+    return { metadata: {}, body: markdown };
+  }
+
+  const metadata: Record<string, string> = {};
+  for (const line of lines.slice(1, end)) {
+    const delimiter = line.indexOf(":");
+    if (delimiter <= 0) {
+      continue;
+    }
+    const key = line.slice(0, delimiter).trim().toLowerCase();
+    const value = line.slice(delimiter + 1).trim();
+    if (key && value) {
+      metadata[key] = value;
+    }
+  }
+
+  return {
+    metadata,
+    body: lines.slice(end + 1).join("\n"),
+  };
+}
+
+function firstHeading(markdown: string): string | undefined {
+  const match = markdown.match(/^\s*#\s+(.+)$/m);
+  if (!match?.[1]) {
+    return undefined;
+  }
+  const heading = match[1].trim();
+  return heading.length > 0 ? heading : undefined;
+}
+
+async function readSkill(
+  filePath: string,
+  origin: SkillOrigin,
+): Promise<CustomSkill | null> {
+  const raw = await fs.readFile(filePath, "utf8");
+  const { metadata, body } = parseFrontmatter(raw);
+  const template = body.trim();
+  if (!template) {
+    return null;
+  }
+
+  const heading = firstHeading(body);
+  const dirName = path.basename(path.dirname(filePath)).trim();
+  const name = metadata.name?.trim() || heading || dirName;
+  if (!name) {
+    return null;
+  }
+
+  const description =
+    metadata.description?.trim() ||
+    (heading && heading !== name ? heading : undefined) ||
+    `Skill from ${dirName || path.basename(filePath)}`;
+
+  return {
+    name,
+    description,
+    template,
+    sourcePath: filePath,
+    origin,
+  };
+}
+
+export async function loadCustomSkills(
+  workspace: string,
+  homeDirectory: string = os.homedir(),
+): Promise<CustomSkill[]> {
+  const skillRoots: Array<{ root: string; origin: SkillOrigin }> = [
+    { root: path.join(workspace, ".cursor", "skills"), origin: "workspace" },
+    { root: path.join(homeDirectory, ".cursor", "skills"), origin: "user" },
+    {
+      root: path.join(homeDirectory, ".cursor", "skills-cursor"),
+      origin: "cursor",
+    },
+  ];
+
+  const byName = new Map<string, CustomSkill>();
+  for (const { root, origin } of skillRoots) {
+    const files = await collectSkillFiles(root);
+    for (const file of files) {
+      const skill = await readSkill(file, origin);
+      if (!skill) {
+        continue;
+      }
+      const key = skill.name.toLowerCase();
+      if (!byName.has(key)) {
+        byName.set(key, skill);
+      }
+    }
+  }
+
+  return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function resolveSkillPrompt(
+  commandName: string,
+  skills: CustomSkill[],
+): string | null {
+  const normalized = commandName.toLowerCase();
+  const stripped = normalized.startsWith("skill:")
+    ? normalized.slice("skill:".length)
+    : normalized.startsWith("skills:")
+      ? normalized.slice("skills:".length)
+      : normalized.startsWith("skills/")
+        ? normalized.slice("skills/".length)
+        : normalized;
+  const match = skills.find((skill) => skill.name.toLowerCase() === stripped);
+  return match?.template ?? null;
+}
diff --git a/src/slash-commands.ts b/src/slash-commands.ts
@@ -4,6 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { CursorAuthClient } from "./auth.js";
 import { SessionModeId, SUPPORTED_MODE_IDS } from "./settings.js";
+import { CustomSkill, resolveSkillPrompt } from "./skills.js";
 
 export interface CursorModelDescriptor {
   modelId: string;
@@ -29,6 +30,7 @@ export interface SlashCommandContext {
   auth: CursorAuthClient;
   listModels: () => Promise<CursorModelDescriptor[]>;
   customCommands?: CustomSlashCommand[];
+  skills?: CustomSkill[];
   onModeChanged?: (modeId: SessionModeId) => Promise<void>;
 }
 
@@ -56,6 +58,7 @@ const BUILTIN_SLASH_COMMANDS: AvailableCommand[] = [
 
 export function availableSlashCommands(
   customCommands: CustomSlashCommand[] = [],
+  skills: CustomSkill[] = [],
 ): AvailableCommand[] {
   const deduped = new Map<string, AvailableCommand>();
   for (const command of BUILTIN_SLASH_COMMANDS) {
@@ -74,9 +77,26 @@ export function availableSlashCommands(
     });
   }
 
+  for (const skill of skills) {
+    const name = skillCommandName(skill.name);
+    const key = name.toLowerCase();
+    if (deduped.has(key)) {
+      continue;
+    }
+    deduped.set(key, {
+      name,
+      description: skill.description,
+      input: null,
+    });
+  }
+
   return [...deduped.values()];
 }
 
+function skillCommandName(skillName: string): string {
+  return `skill:${skillName}`;
+}
+
 async function collectMarkdownFiles(dir: string): Promise<string[]> {
   let entries: import("node:fs").Dirent[];
   try {
@@ -270,6 +290,13 @@ export function resolveCustomSlashCommandPrompt(
   return applyCustomCommandArgs(command.template, args);
 }
 
+export function resolveSkillSlashCommandPrompt(
+  commandName: string,
+  skills: CustomSkill[],
+): string | null {
+  return resolveSkillPrompt(commandName, skills);
+}
+
 export function builtInSlashCommandNames(): string[] {
   return [
     ...BUILTIN_SLASH_COMMANDS.map((command) =>
@@ -337,6 +364,11 @@ export async function handleSlashCommand(
                 )
                 .join(", ")}`
             : null,
+          context.skills?.length
+            ? `Skills: ${context.skills
+                .map((skill) => `/${skillCommandName(skill.name)}`)
+                .join(", ")}`
+            : null,
         ]
           .filter(Boolean)
           .join("\n"),
diff --git a/src/tests/cursor-acp-agent.test.ts b/src/tests/cursor-acp-agent.test.ts
@@ -411,7 +411,9 @@ describe("CursorAcpAgent", () => {
       } as any);
 
       expect(response.stopReason).toBe("end_turn");
-      expect(promptText).toBe("/commit feat(parser)");
+      expect(promptText).toBe(
+        "Write a concise conventional commit message.\nScope: feat(parser)",
+      );
     } finally {
       await rm(tempRoot, { recursive: true, force: true });
     }
diff --git a/src/tests/skills.test.ts b/src/tests/skills.test.ts
