🤖 feat: add agent skills tools and prompt index

Change-Id: Ic6403e04df7db28a075d2b4084fb9f3f330e9425
Signed-off-by: Thomas Kosiewski <[email protected]>

Author: ThomasK33

bun.lock

@@ -1,6 +1,5 @@
 {
   "lockfileVersion": 1,
-  "configVersion": 0,
   "workspaces": {
     "": {
       "name": "mux",
@@ -75,6 +74,7 @@
         "write-file-atomic": "^6.0.0",
         "ws": "^8.18.3",
         "xxhash-wasm": "^1.1.0",
+        "yaml": "^2.8.2",
         "zod": "^4.1.11",
         "zod-to-json-schema": "^3.24.6",
       },
@@ -3674,6 +3674,8 @@
 
     "yallist": ["[email protected]", "", {}, "sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A=="],
 
+    "yaml": ["[email protected]", "", { "bin": { "yaml": "bin.mjs" } }, "sha512-mplynKqc1C2hTVYxd0PU2xQAc22TI1vShAYGksCCfxbn/dFwnHTNi1bvYsBTkhdUNtGIf5xNOg938rrSSYvS9A=="],
+
     "yargs": ["[email protected]", "", { "dependencies": { "cliui": "^8.0.1", "escalade": "^3.1.1", "get-caller-file": "^2.0.5", "require-directory": "^2.1.1", "string-width": "^4.2.3", "y18n": "^5.0.5", "yargs-parser": "^21.1.1" } }, "sha512-7dSzzRQ++CKnNI/krKnYRV7JKKPUXMEh61soaHKg9mrWEhzFWhFnxPxGl+69cD1Ou63C13NUPCnmIcrvqCuM6w=="],
 
     "yargs-parser": ["[email protected]", "", {}, "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw=="],

docs/system-prompt.mdx

@@ -96,6 +96,41 @@ You are in a git worktree at ${workspacePath}
  * Only included when at least one MCP server is configured.
  * Note: We only expose server names, not commands, to avoid leaking secrets.
  */
+
+async function buildAgentSkillsContext(projectPath: string): Promise<string> {
+  try {
+    const skills = await discoverAgentSkills(projectPath);
+    if (skills.length === 0) return "";
+
+    const MAX_SKILLS = 50;
+    const shown = skills.slice(0, MAX_SKILLS);
+    const omitted = skills.length - shown.length;
+
+    const lines: string[] = [];
+    lines.push("Available agent skills (call tools to load):");
+    for (const skill of shown) {
+      lines.push(`- ${skill.name}: ${skill.description} (scope: ${skill.scope})`);
+    }
+    if (omitted > 0) {
+      lines.push(`(+${omitted} more not shown)`);
+    }
+
+    lines.push("");
+    lines.push("To load a skill:");
+    lines.push('- agent_skill_read({ name: "<skill-name>" })');
+
+    lines.push("");
+    lines.push("To read referenced files inside a skill directory:");
+    lines.push(
+      '- agent_skill_read_file({ name: "<skill-name>", filePath: "references/whatever.txt" })'
+    );
+
+    return `\n\n<agent-skills>\n${lines.join("\n")}\n</agent-skills>`;
+  } catch (error) {
+    log.warn("Failed to build agent skills context", { projectPath, error });
+    return "";
+  }
+}
 function buildMCPContext(mcpServers: MCPServerMap): string {
   const names = Object.keys(mcpServers);
   if (names.length === 0) return "";

package.json

@@ -102,7 +102,6 @@
     "parse-duration": "^2.1.4",
     "posthog-node": "^5.17.0",
     "quickjs-emscripten": "^0.31.0",
-    "typescript": "^5.1.3",
     "quickjs-emscripten-core": "^0.31.0",
     "rehype-harden": "^1.1.5",
     "rehype-sanitize": "^6.0.0",
@@ -111,10 +110,12 @@
     "streamdown": "1.6.10",
     "trpc-cli": "^0.12.1",
     "turndown": "^7.2.2",
+    "typescript": "^5.1.3",
     "undici": "^7.16.0",
     "write-file-atomic": "^6.0.0",
     "ws": "^8.18.3",
     "xxhash-wasm": "^1.1.0",
+    "yaml": "^2.8.2",
     "zod": "^4.1.11",
     "zod-to-json-schema": "^3.24.6"
   },

src/common/orpc/schemas.ts

@@ -39,6 +39,15 @@ export {
   TokenConsumerSchema,
 } from "./schemas/chatStats";
 
+// Agent Skill schemas
+export {
+  AgentSkillDescriptorSchema,
+  AgentSkillFrontmatterSchema,
+  AgentSkillPackageSchema,
+  AgentSkillScopeSchema,
+  SkillNameSchema,
+} from "./schemas/agentSkill";
+
 // Error schemas
 export { SendMessageErrorSchema, StreamErrorTypeSchema } from "./schemas/errors";
 

src/common/orpc/schemas/agentSkill.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+
+export const AgentSkillScopeSchema = z.enum(["project", "global"]);
+
+/**
+ * Skill name per agentskills.io
+ * - 1–64 chars
+ * - lowercase letters/numbers/hyphens
+ * - no leading/trailing hyphen
+ * - no consecutive hyphens
+ */
+export const SkillNameSchema = z
+  .string()
+  .min(1)
+  .max(64)
+  .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/);
+
+export const AgentSkillFrontmatterSchema = z.object({
+  name: SkillNameSchema,
+  description: z.string().min(1).max(1024),
+  license: z.string().optional(),
+  compatibility: z.string().min(1).max(500).optional(),
+  metadata: z.record(z.string(), z.string()).optional(),
+});
+
+export const AgentSkillDescriptorSchema = z.object({
+  name: SkillNameSchema,
+  description: z.string().min(1).max(1024),
+  scope: AgentSkillScopeSchema,
+});
+
+export const AgentSkillPackageSchema = z
+  .object({
+    scope: AgentSkillScopeSchema,
+    directoryName: SkillNameSchema,
+    frontmatter: AgentSkillFrontmatterSchema,
+    body: z.string(),
+  })
+  .refine((value) => value.directoryName === value.frontmatter.name, {
+    message: "SKILL.md frontmatter.name must match the parent directory name",
+    path: ["frontmatter", "name"],
+  });

src/common/types/agentSkill.ts

@@ -0,0 +1,18 @@
+import type { z } from "zod";
+import type {
+  AgentSkillDescriptorSchema,
+  AgentSkillFrontmatterSchema,
+  AgentSkillPackageSchema,
+  AgentSkillScopeSchema,
+  SkillNameSchema,
+} from "@/common/orpc/schemas";
+
+export type SkillName = z.infer<typeof SkillNameSchema>;
+
+export type AgentSkillScope = z.infer<typeof AgentSkillScopeSchema>;
+
+export type AgentSkillFrontmatter = z.infer<typeof AgentSkillFrontmatterSchema>;
+
+export type AgentSkillDescriptor = z.infer<typeof AgentSkillDescriptorSchema>;
+
+export type AgentSkillPackage = z.infer<typeof AgentSkillPackageSchema>;

src/common/types/tools.ts

@@ -6,6 +6,8 @@
 import type { z } from "zod";
 import type {
   AgentReportToolResultSchema,
+  AgentSkillReadFileToolResultSchema,
+  AgentSkillReadToolResultSchema,
   AskUserQuestionOptionSchema,
   AskUserQuestionQuestionSchema,
   AskUserQuestionToolResultSchema,
@@ -42,6 +44,16 @@ export interface FileReadToolArgs {
   limit?: number; // number of lines to return from offset (optional)
 }
 
+// Agent Skill Tool Types
+// Args derived from schema (avoid drift)
+export type AgentSkillReadToolArgs = z.infer<typeof TOOL_DEFINITIONS.agent_skill_read.schema>;
+export type AgentSkillReadToolResult = z.infer<typeof AgentSkillReadToolResultSchema>;
+
+export type AgentSkillReadFileToolArgs = z.infer<
+  typeof TOOL_DEFINITIONS.agent_skill_read_file.schema
+>;
+export type AgentSkillReadFileToolResult = z.infer<typeof AgentSkillReadFileToolResultSchema>;
+
 // FileReadToolResult derived from Zod schema (single source of truth)
 export type FileReadToolResult = z.infer<typeof FileReadToolResultSchema>;
 

src/common/utils/tools/toolDefinitions.ts

@@ -6,6 +6,7 @@
  */
 
 import { z } from "zod";
+import { AgentSkillPackageSchema, SkillNameSchema } from "@/common/orpc/schemas";
 import {
   BASH_HARD_MAX_LINES,
   BASH_MAX_LINE_BYTES,
@@ -388,6 +389,46 @@ export const TOOL_DEFINITIONS = {
         .describe("Number of lines to return from offset (optional, returns all if not specified)"),
     }),
   },
+  agent_skill_read: {
+    description:
+      "Load an Agent Skill's SKILL.md (YAML frontmatter + markdown body) by name. " +
+      "Skills are discovered from <projectRoot>/.mux/skills/<name>/SKILL.md and ~/.mux/skills/<name>/SKILL.md.",
+    schema: z
+      .object({
+        name: SkillNameSchema.describe("Skill name (directory name under the skills root)"),
+      })
+      .strict(),
+  },
+  agent_skill_read_file: {
+    description:
+      "Read a file within an Agent Skill directory. " +
+      "filePath must be relative to the skill directory (no absolute paths, no ~, no .. traversal). " +
+      "Supports offset/limit like file_read.",
+    schema: z
+      .object({
+        name: SkillNameSchema.describe("Skill name (directory name under the skills root)"),
+        filePath: z
+          .string()
+          .min(1)
+          .describe("Path to the file within the skill directory (relative)"),
+        offset: z
+          .number()
+          .int()
+          .positive()
+          .optional()
+          .describe("1-based starting line number (optional, defaults to 1)"),
+        limit: z
+          .number()
+          .int()
+          .positive()
+          .optional()
+          .describe(
+            "Number of lines to return from offset (optional, returns all if not specified)"
+          ),
+      })
+      .strict(),
+  },
+
   file_edit_replace_string: {
     description:
       "⚠️ CRITICAL: Always check tool results - edits WILL fail if old_string is not found or unique. Do not proceed with dependent operations (commits, pushes, builds) until confirming success.\n\n" +
@@ -777,6 +818,26 @@ export const FileReadToolResultSchema = z.union([
   }),
 ]);
 
+/**
+ * Agent Skill read tool result - full SKILL.md package or error.
+ */
+export const AgentSkillReadToolResultSchema = z.union([
+  z.object({
+    success: z.literal(true),
+    skill: AgentSkillPackageSchema,
+  }),
+  z.object({
+    success: z.literal(false),
+    error: z.string(),
+  }),
+]);
+
+/**
+ * Agent Skill read_file tool result.
+ * Uses the same shape/limits as file_read.
+ */
+export const AgentSkillReadFileToolResultSchema = FileReadToolResultSchema;
+
 /**
  * File edit insert tool result - diff or error.
  */
@@ -839,6 +900,8 @@ export type BridgeableToolName =
   | "bash_background_list"
   | "bash_background_terminate"
   | "file_read"
+  | "agent_skill_read"
+  | "agent_skill_read_file"
   | "file_edit_insert"
   | "file_edit_replace_string"
   | "web_fetch";
@@ -855,6 +918,8 @@ export const RESULT_SCHEMAS: Record<BridgeableToolName, z.ZodType> = {
   bash_background_list: BashBackgroundListResultSchema,
   bash_background_terminate: BashBackgroundTerminateResultSchema,
   file_read: FileReadToolResultSchema,
+  agent_skill_read: AgentSkillReadToolResultSchema,
+  agent_skill_read_file: AgentSkillReadFileToolResultSchema,
   file_edit_insert: FileEditInsertToolResultSchema,
   file_edit_replace_string: FileEditReplaceStringToolResultSchema,
   web_fetch: WebFetchToolResultSchema,
@@ -901,6 +966,8 @@ export function getAvailableTools(
     "bash_background_list",
     "bash_background_terminate",
     "file_read",
+    "agent_skill_read",
+    "agent_skill_read_file",
     "file_edit_replace_string",
     // "file_edit_replace_lines", // DISABLED: causes models to break repo state
     "file_edit_insert",

src/common/utils/tools/tools.ts

@@ -15,6 +15,8 @@ import { createTaskTool } from "@/node/services/tools/task";
 import { createTaskAwaitTool } from "@/node/services/tools/task_await";
 import { createTaskTerminateTool } from "@/node/services/tools/task_terminate";
 import { createTaskListTool } from "@/node/services/tools/task_list";
+import { createAgentSkillReadTool } from "@/node/services/tools/agent_skill_read";
+import { createAgentSkillReadFileTool } from "@/node/services/tools/agent_skill_read_file";
 import { createAgentReportTool } from "@/node/services/tools/agent_report";
 import { wrapWithInitWait } from "@/node/services/tools/wrapWithInitWait";
 import { log } from "@/node/services/log";
@@ -145,6 +147,8 @@ export async function getToolsForModel(
   // Non-runtime tools execute immediately (no init wait needed)
   const nonRuntimeTools: Record<string, Tool> = {
     ...(config.mode === "plan" ? { ask_user_question: createAskUserQuestionTool(config) } : {}),
+    agent_skill_read: createAgentSkillReadTool(config),
+    agent_skill_read_file: createAgentSkillReadFileTool(config),
     propose_plan: createProposePlanTool(config),
     task: createTaskTool(config),
     task_await: createTaskAwaitTool(config),

src/node/services/agentSkills/agentSkillsService.test.ts

@@ -0,0 +1,68 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+
+import { describe, expect, test } from "bun:test";
+
+import { SkillNameSchema } from "@/common/orpc/schemas";
+import { DisposableTempDir } from "@/node/services/tempDir";
+import { discoverAgentSkills, readAgentSkill } from "./agentSkillsService";
+
+async function writeSkill(root: string, name: string, description: string): Promise<void> {
+  const skillDir = path.join(root, name);
+  await fs.mkdir(skillDir, { recursive: true });
+  const content = `---
+name: ${name}
+description: ${description}
+---
+Body
+`;
+  await fs.writeFile(path.join(skillDir, "SKILL.md"), content, "utf-8");
+}
+
+describe("agentSkillsService", () => {
+  test("project skills override global skills", async () => {
+    using project = new DisposableTempDir("agent-skills-project");
+    using global = new DisposableTempDir("agent-skills-global");
+
+    const projectSkillsRoot = path.join(project.path, ".mux", "skills");
+    const globalSkillsRoot = global.path;
+
+    await writeSkill(globalSkillsRoot, "foo", "from global");
+    await writeSkill(projectSkillsRoot, "foo", "from project");
+    await writeSkill(globalSkillsRoot, "bar", "global only");
+
+    const roots = { projectRoot: projectSkillsRoot, globalRoot: globalSkillsRoot };
+
+    const skills = await discoverAgentSkills(project.path, { roots });
+
+    expect(skills.map((s) => s.name)).toEqual(["bar", "foo"]);
+
+    const foo = skills.find((s) => s.name === "foo");
+    expect(foo).toBeDefined();
+    expect(foo!.scope).toBe("project");
+    expect(foo!.description).toBe("from project");
+
+    const bar = skills.find((s) => s.name === "bar");
+    expect(bar).toBeDefined();
+    expect(bar!.scope).toBe("global");
+  });
+
+  test("readAgentSkill resolves project before global", async () => {
+    using project = new DisposableTempDir("agent-skills-project");
+    using global = new DisposableTempDir("agent-skills-global");
+
+    const projectSkillsRoot = path.join(project.path, ".mux", "skills");
+    const globalSkillsRoot = global.path;
+
+    await writeSkill(globalSkillsRoot, "foo", "from global");
+    await writeSkill(projectSkillsRoot, "foo", "from project");
+
+    const roots = { projectRoot: projectSkillsRoot, globalRoot: globalSkillsRoot };
+
+    const name = SkillNameSchema.parse("foo");
+    const resolved = await readAgentSkill(project.path, name, { roots });
+
+    expect(resolved.package.scope).toBe("project");
+    expect(resolved.package.frontmatter.description).toBe("from project");
+  });
+});