@dudamel/mcp-agents 2026.918.1 → 2026.923.1

package/dist/index.js

@@ -462,33 +462,239 @@ function registerAgentTools(server, client, ctx) {
 
 // src/tools/skills.ts
 import { z as z2 } from "zod";
+
+// src/skill-bundle.ts
+import { createHash } from "node:crypto";
+import { mkdir, readdir, readFile, realpath, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+var EXCLUDED = /* @__PURE__ */ new Set([".git", "node_modules", "__pycache__", ".venv", ".DS_Store"]);
+var MAX_PATH_LENGTH = 512;
+var MAX_FILES = 200;
+var MAX_BUNDLE_BYTES = 2 * 1024 * 1024;
+var SKILL_MD = "SKILL.md";
+function digest(content) {
+  return {
+    bytes: Buffer.byteLength(content, "utf8"),
+    sha256: createHash("sha256").update(content, "utf8").digest("hex")
+  };
+}
+function digestFiles(files) {
+  return files.map((f) => ({ path: f.path, ...digest(f.content) }));
+}
+function decodeUtf8(raw, relPath, notText) {
+  if (raw.includes(0)) {
+    notText.push(relPath);
+    return void 0;
+  }
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(raw);
+  } catch {
+    notText.push(relPath);
+    return void 0;
+  }
+}
+async function readSkillDir(skillDir) {
+  const root = resolve(skillDir);
+  let realRoot;
+  try {
+    realRoot = await realpath(root);
+  } catch {
+    throw new Error(`skillDir not found or not readable: ${root}`);
+  }
+  let content;
+  try {
+    content = await readFile(join(realRoot, SKILL_MD), "utf8");
+  } catch {
+    throw new Error(
+      `${SKILL_MD} not found at the root of ${root}. A skill directory must contain ${SKILL_MD}; use download-skill with outDir to get the expected layout.`
+    );
+  }
+  const files = [];
+  const notText = [];
+  const escaping = [];
+  const tooLongPath = [];
+  async function walk(dir) {
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+      if (EXCLUDED.has(entry.name)) continue;
+      const full = join(dir, entry.name);
+      const relPath = relative(realRoot, full).split(sep).join("/");
+      if (relPath === SKILL_MD) continue;
+      let resolved = full;
+      if (entry.isSymbolicLink()) {
+        try {
+          resolved = await realpath(full);
+        } catch {
+          escaping.push(relPath);
+          continue;
+        }
+        if (resolved !== realRoot && !resolved.startsWith(realRoot + sep)) {
+          escaping.push(relPath);
+          continue;
+        }
+      }
+      const isDir = entry.isDirectory() || entry.isSymbolicLink() && await isDirectory(resolved);
+      if (isDir) {
+        await walk(resolved);
+        continue;
+      }
+      if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+      if (relPath.length > MAX_PATH_LENGTH) {
+        tooLongPath.push(relPath);
+        continue;
+      }
+      const text = decodeUtf8(await readFile(resolved), relPath, notText);
+      if (text !== void 0) files.push({ path: relPath, content: text });
+    }
+  }
+  await walk(realRoot);
+  if (notText.length > 0) {
+    throw new Error(
+      `A skill can only hold text files (the column that stores them is text, not bytes). Not text: ${notText.sort().join(", ")}. Remove them from the directory, or keep them out of the skill entirely.`
+    );
+  }
+  if (escaping.length > 0) {
+    throw new Error(
+      `These symlinks point outside the skill directory and were refused: ${escaping.sort().join(", ")}. Replace them with real files if they belong to the skill.`
+    );
+  }
+  if (tooLongPath.length > 0) {
+    throw new Error(
+      `These paths exceed the ${MAX_PATH_LENGTH}-character limit: ${tooLongPath.sort().join(", ")}.`
+    );
+  }
+  if (files.length > MAX_FILES) {
+    throw new Error(
+      `A skill bundle is capped at ${MAX_FILES} files; ${skillDir} has ${files.length}.`
+    );
+  }
+  const total = Buffer.byteLength(content, "utf8") + files.reduce((n, f) => n + digest(f.content).bytes, 0);
+  if (total > MAX_BUNDLE_BYTES) {
+    const biggest = digestFiles(files).sort((a, b) => b.bytes - a.bytes).slice(0, 5).map((f) => `${f.path} (${Math.round(f.bytes / 1024)} KB)`);
+    throw new Error(
+      `The bundle is ${Math.round(total / 1024)} KB, over the ${MAX_BUNDLE_BYTES / 1024 / 1024} MB cap. Largest files: ${biggest.join(", ")}.`
+    );
+  }
+  files.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  return { content, files };
+}
+async function isDirectory(path) {
+  try {
+    await readdir(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function writeSkillFiles(outDir, files, opts) {
+  const root = resolve(outDir);
+  await mkdir(root, { recursive: true });
+  const realRoot = await realpath(root);
+  const targets = files.map((file) => {
+    const target = resolve(realRoot, file.path);
+    if (target !== realRoot && !target.startsWith(realRoot + sep)) {
+      throw new Error(`Refusing to write outside outDir: ${file.path}`);
+    }
+    return { file, target };
+  });
+  if (!opts.overwrite) {
+    const conflicts = [];
+    for (const { file, target } of targets) {
+      const existing = await readFile(target, "utf8").catch(() => void 0);
+      if (existing !== void 0 && existing !== file.content) conflicts.push(file.path);
+    }
+    if (conflicts.length > 0) {
+      throw new Error(
+        `These files already exist in ${root} with different content: ${conflicts.sort().join(", ")}. Nothing was written. Pass overwrite: true to replace them.`
+      );
+    }
+  }
+  for (const { file, target } of targets) {
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, file.content, "utf8");
+  }
+  return digestFiles(files);
+}
+
+// src/tools/skills.ts
+function skillMetadata(skill) {
+  return {
+    id: skill.id,
+    name: skill.name,
+    description: skill.description ?? null,
+    status: skill.status,
+    origin: skill.origin,
+    currentVersion: skill.currentVersion ?? null,
+    updatedAt: skill.updatedAt,
+    canEdit: skill.canEdit,
+    fileCount: skill.files?.length ?? 0,
+    usedBy: skill.usedBy ?? []
+  };
+}
+function writeReceipt(skill) {
+  return {
+    id: skill.id,
+    name: skill.name,
+    currentVersion: skill.currentVersion ?? null,
+    updatedAt: skill.updatedAt,
+    content: digest(skill.content ?? ""),
+    files: digestFiles(skill.files ?? [])
+  };
+}
+async function resolveBundle(args) {
+  if (args.skillDir === void 0) return { content: args.content, files: args.files };
+  if (args.content !== void 0 || args.files !== void 0) {
+    throw new Error(
+      "skillDir cannot be combined with content or files: pass the directory alone (its SKILL.md becomes the content and everything else becomes the files), or pass content/files inline."
+    );
+  }
+  return readSkillDir(args.skillDir);
+}
+var FILES_SEMANTICS = "Omitting `files` keeps the existing ones; sending it REPLACES the whole set, so a file missing from the list is deleted (`files: []` deletes all of them). To delete a file, leave it out of the directory (or the array) and upload.";
+var SKILL_DIR_HELP = "Path to a skill directory on disk \u2014 `SKILL.md` at its root becomes the content (frontmatter included) and every other file becomes an embedded file, path relative to the directory. This is the layout download-skill writes with outDir, so the loop is: download to a folder, edit, upload the folder. Prefer this over inline content for anything non-trivial \u2014 it costs the same whether the skill is 1 KB or 1 MB. Text files only; .git/node_modules/__pycache__/.venv are skipped.";
 function registerSkillTools(server, client, ctx) {
   server.registerTool(
     "list-skills",
     {
-      description: "List skill definitions (active by default). Returns id, name, description, status, origin, version, and timestamps.",
+      description: "List skill definitions (active by default). Metadata only \u2014 id, name, description, status, origin, version, file count and timestamps. Use get-skill or download-skill to read a specific skill.",
       inputSchema: {
-        status: z2.enum(["active", "archived"]).optional().describe("Lifecycle filter \u2014 defaults to 'active'; pass 'archived' for archived skills")
+        status: z2.enum(["active", "archived"]).optional().describe("Lifecycle filter \u2014 defaults to 'active'; pass 'archived' for archived skills"),
+        query: z2.string().optional().describe("Case-insensitive substring match against the name and description")
       },
       annotations: { readOnlyHint: true }
     },
-    async ({ status }) => {
-      const query = status ? `?status=${status}` : "";
-      const page = await client.get(`/api/skills${query}`);
-      return jsonResult({ items: page.items, total: page.total });
+    async ({ status, query }) => {
+      const qs = status ? `?status=${status}` : "";
+      const page = await client.get(`/api/skills${qs}`);
+      const needle = query?.trim().toLowerCase();
+      const items = page.items.filter(
+        (s) => !needle || s.name.toLowerCase().includes(needle) || (s.description ?? "").toLowerCase().includes(needle)
+      ).map(skillMetadata);
+      return jsonResult({ items, total: items.length, totalBeforeFilter: page.total });
     }
   );
   server.registerTool(
     "get-skill",
     {
-      description: "Get detailed information about a specific skill, including content, allowed tools, files, and version info.",
+      description: "Get detailed information about a specific skill, including content, allowed tools, files, and version info. For a large skill prefer download-skill with outDir, which puts the files on disk instead of in the conversation.",
       inputSchema: {
-        id: z2.string().describe("Skill ID (UUID)")
+        id: z2.string().describe("Skill ID (UUID)"),
+        includeContent: z2.boolean().optional().describe(
+          "Defaults to true. With false, returns metadata plus a size and sha256 per file \u2014 enough to check what is stored without pulling the content in."
+        )
       },
       annotations: { readOnlyHint: true }
     },
-    async ({ id }) => {
+    async ({ id, includeContent }) => {
       const skill = await client.get(`/api/skills/${id}`);
+      if (includeContent === false) {
+        return jsonResult({
+          ...skillMetadata(skill),
+          model: skill.model ?? null,
+          allowedTools: skill.allowedTools ?? [],
+          content: digest(skill.content ?? ""),
+          files: digestFiles(skill.files ?? [])
+        });
+      }
       return jsonResult(skill);
     }
   );
@@ -509,18 +715,30 @@ function registerSkillTools(server, client, ctx) {
   server.registerTool(
     "download-skill",
     {
-      description: "Download a skill as files in the target tool's on-disk layout (e.g. .claude/skills/<name>/SKILL.md for Claude Code). Returns {files: [{path, content}]} \u2014 write each file at its path relative to the current working directory. Iterate locally, then push changes back with update-skill.",
+      description: "Download a skill as files in the target tool's on-disk layout (e.g. .claude/skills/<name>/SKILL.md for Claude Code). With `outDir` the files are written to disk and only their paths, sizes and hashes come back \u2014 the way to handle a skill of any size. Without it, the content is returned inline. Then edit the folder and push it back with update-skill + skillDir.",
       inputSchema: {
         id: z2.string().describe("Skill ID (UUID)"),
         format: z2.enum(["claude-code", "codex", "kimi-code", "opencode", "raw"]).optional().describe(
           "Target tool layout \u2014 defaults to 'claude-code'; 'raw' is the dudamel-native <name>/SKILL.md layout"
+        ),
+        outDir: z2.string().optional().describe(
+          "Directory to write the files into (created if missing). Paths from the chosen format are kept, so outDir is the root the layout hangs from."
+        ),
+        overwrite: z2.boolean().optional().describe(
+          "Defaults to false: if a file already exists with different content the call is rejected and nothing is written, so a re-download cannot erase edits in flight."
         )
       },
       annotations: { readOnlyHint: true }
     },
-    async ({ id, format }) => {
-      const result = await client.get(`/api/skills/${id}/export?format=${format ?? "claude-code"}`);
-      return jsonResult(result);
+    async ({ id, format, outDir, overwrite }) => {
+      const result = await client.get(
+        `/api/skills/${id}/export?format=${format ?? "claude-code"}`
+      );
+      if (outDir === void 0) return jsonResult(result);
+      const written = await writeSkillFiles(outDir, result.files, {
+        overwrite: overwrite ?? false
+      });
+      return jsonResult({ skillName: result.skillName, outDir, files: written });
     }
   );
   server.registerTool(
@@ -541,10 +759,13 @@ function registerSkillTools(server, client, ctx) {
   server.registerTool(
     "create-skill",
     {
-      description: "Create a new skill definition. The creator becomes the owner and can edit it and share edition with business roles via set-skill-roles.",
+      description: "Create a new skill definition. The creator becomes the owner and can edit it and share edition with business roles via set-skill-roles. Pass `skillDir` to upload a directory from disk instead of inlining every file. Returns the new version plus a size and sha256 per stored file. " + FILES_SEMANTICS,
       inputSchema: {
         name: z2.string().describe("Skill name (unique, kebab-case)"),
-        content: z2.string().describe("Skill content (markdown body)"),
+        content: z2.string().optional().describe(
+          "Skill content \u2014 the full SKILL.md is fine: its frontmatter (description, version, allowed-tools, model) is honored, and an argument passed explicitly here wins over it. Required unless skillDir is given."
+        ),
+        skillDir: z2.string().optional().describe(SKILL_DIR_HELP),
         description: z2.string().optional().describe("Skill description"),
         disableModelInvocation: z2.boolean().optional().describe("Disable model-triggered invocation"),
         userInvocable: z2.boolean().optional().describe("Allow user to invoke via slash command"),
@@ -556,13 +777,14 @@ function registerSkillTools(server, client, ctx) {
             path: z2.string().describe("Relative file path within the skill"),
             content: z2.string().describe("File content")
           })
-        ).optional().describe("Embedded skill files")
+        ).optional().describe(`Embedded skill files. ${FILES_SEMANTICS}`)
       },
       annotations: { readOnlyHint: false, destructiveHint: false }
     },
     async ({
       name,
       content,
+      skillDir,
       description,
       disableModelInvocation,
       userInvocable,
@@ -571,30 +793,37 @@ function registerSkillTools(server, client, ctx) {
       currentVersion,
       files
     }) => {
+      const bundle = await resolveBundle({ content, files, skillDir });
+      if (bundle.content === void 0) {
+        throw new Error("A new skill needs either content or skillDir.");
+      }
       const result = await client.post("/api/skills", {
         name,
-        content,
+        content: bundle.content,
         description,
         disableModelInvocation,
         userInvocable,
         model,
         allowedTools,
         currentVersion,
-        files
+        files: bundle.files
       });
-      return jsonResult(result);
+      return jsonResult(writeReceipt(result));
     }
   );
   server.registerTool(
     "update-skill",
     {
-      description: "Update a skill definition. Creates a new version entry.",
+      description: "Update a skill definition. Creates a new version entry. Pass `skillDir` to upload an edited directory from disk in one call instead of retyping every file. Returns the new version plus a size and sha256 per stored file, so the upload can be verified without downloading it back. " + FILES_SEMANTICS,
       inputSchema: {
         id: z2.string().describe("Skill ID (UUID)"),
         name: z2.string().optional().describe(
           "New skill name (unique, kebab-case) \u2014 rename the skill; agent assignments are by id and survive the rename"
         ),
-        content: z2.string().optional().describe("New skill content"),
+        content: z2.string().optional().describe(
+          "New skill content \u2014 the full SKILL.md is fine: its frontmatter (description, version, allowed-tools, model) is honored, and an argument passed explicitly here wins over it."
+        ),
+        skillDir: z2.string().optional().describe(SKILL_DIR_HELP),
         description: z2.string().optional().describe("New description"),
         disableModelInvocation: z2.boolean().optional().describe("Disable model-triggered invocation"),
         userInvocable: z2.boolean().optional().describe("Allow user to invoke via slash command"),
@@ -607,13 +836,22 @@ function registerSkillTools(server, client, ctx) {
             path: z2.string().describe("Relative file path within the skill"),
             content: z2.string().describe("File content")
           })
-        ).optional().describe("Embedded skill files")
+        ).optional().describe(`Embedded skill files. ${FILES_SEMANTICS}`)
       },
       annotations: { readOnlyHint: false, destructiveHint: false }
     },
-    async ({ id, ...updates }) => {
-      const result = await client.put(`/api/skills/${id}`, updates);
-      return jsonResult(result);
+    async ({ id, skillDir, ...updates }) => {
+      const bundle = await resolveBundle({
+        content: updates.content,
+        files: updates.files,
+        skillDir
+      });
+      const result = await client.put(`/api/skills/${id}`, {
+        ...updates,
+        content: bundle.content,
+        files: bundle.files
+      });
+      return jsonResult(writeReceipt(result));
     }
   );
   server.registerTool(

package/dist/skill-bundle.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Disk I/O for skill bundles (Plan 53).
+ *
+ * This MCP server runs as a stdio child of the agent, on the same filesystem, so it can
+ * read and write the skill directory itself instead of making the model retype every file
+ * inside the tool call. That is the whole point: the cost that hurts is the model's
+ * context, not the HTTP request. A 110 KB skill now uploads for the same price as a 1 KB
+ * one.
+ *
+ * Under the coding-agent sandbox the Landlock ruleset is inherited and cannot be relaxed,
+ * so a directory inside the workspace works and one outside fails closed — which is the
+ * behaviour we want, not a limitation to work around.
+ *
+ * Everything here fails loudly. A silently skipped file would recreate exactly the failure
+ * mode this replaces: believing you uploaded something you did not.
+ */
+export interface SkillFile {
+    path: string;
+    content: string;
+}
+export interface FileDigest {
+    path: string;
+    bytes: number;
+    sha256: string;
+}
+export declare function digest(content: string): {
+    bytes: number;
+    sha256: string;
+};
+export declare function digestFiles(files: SkillFile[]): FileDigest[];
+/**
+ * Read a skill directory into the shape the API expects: `SKILL.md` at the root becomes
+ * `content` (frontmatter included — the API parses and honors it), everything else becomes
+ * `files` with paths relative to the directory.
+ *
+ * This is exactly the layout `download-skill` produces, so the cycle closes:
+ * download to a folder → edit → upload the folder.
+ */
+export declare function readSkillDir(skillDir: string): Promise<{
+    content: string;
+    files: SkillFile[];
+}>;
+/**
+ * Write a downloaded skill to disk and report digests instead of content.
+ *
+ * Refuses by default to clobber a file whose content differs: re-downloading on top of a
+ * folder with edits in flight would erase them with no trace — the same silent loss this
+ * plan removes on the upload side. Conflicts are all collected before anything is written,
+ * so a rejected call leaves the directory untouched.
+ *
+ * Files present in `outDir` but absent from the skill are left alone (same "omitting
+ * conserves" semantics as uploading).
+ */
+export declare function writeSkillFiles(outDir: string, files: SkillFile[], opts: {
+    overwrite: boolean;
+}): Promise<FileDigest[]>;
+//# sourceMappingURL=skill-bundle.d.ts.map

package/dist/skill-bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-bundle.d.ts","sourceRoot":"","sources":["../src/skill-bundle.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAgBD,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAKzE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,UAAU,EAAE,CAE5D;AAgBD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,EAAE,CAAA;CAAE,CAAC,CA4GlD;AAWD;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,SAAS,EAAE,EAClB,IAAI,EAAE;IAAE,SAAS,EAAE,OAAO,CAAA;CAAE,GAC3B,OAAO,CAAC,UAAU,EAAE,CAAC,CAiCvB"}

package/dist/stdio-server.js

@@ -520,33 +520,239 @@ function registerAgentTools(server2, client, ctx2) {
 
 // src/tools/skills.ts
 import { z as z2 } from "zod";
+
+// src/skill-bundle.ts
+import { createHash } from "node:crypto";
+import { mkdir, readdir, readFile, realpath, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+var EXCLUDED = /* @__PURE__ */ new Set([".git", "node_modules", "__pycache__", ".venv", ".DS_Store"]);
+var MAX_PATH_LENGTH = 512;
+var MAX_FILES = 200;
+var MAX_BUNDLE_BYTES = 2 * 1024 * 1024;
+var SKILL_MD = "SKILL.md";
+function digest(content) {
+  return {
+    bytes: Buffer.byteLength(content, "utf8"),
+    sha256: createHash("sha256").update(content, "utf8").digest("hex")
+  };
+}
+function digestFiles(files) {
+  return files.map((f) => ({ path: f.path, ...digest(f.content) }));
+}
+function decodeUtf8(raw, relPath, notText) {
+  if (raw.includes(0)) {
+    notText.push(relPath);
+    return void 0;
+  }
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(raw);
+  } catch {
+    notText.push(relPath);
+    return void 0;
+  }
+}
+async function readSkillDir(skillDir) {
+  const root = resolve(skillDir);
+  let realRoot;
+  try {
+    realRoot = await realpath(root);
+  } catch {
+    throw new Error(`skillDir not found or not readable: ${root}`);
+  }
+  let content;
+  try {
+    content = await readFile(join(realRoot, SKILL_MD), "utf8");
+  } catch {
+    throw new Error(
+      `${SKILL_MD} not found at the root of ${root}. A skill directory must contain ${SKILL_MD}; use download-skill with outDir to get the expected layout.`
+    );
+  }
+  const files = [];
+  const notText = [];
+  const escaping = [];
+  const tooLongPath = [];
+  async function walk(dir) {
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+      if (EXCLUDED.has(entry.name)) continue;
+      const full = join(dir, entry.name);
+      const relPath = relative(realRoot, full).split(sep).join("/");
+      if (relPath === SKILL_MD) continue;
+      let resolved = full;
+      if (entry.isSymbolicLink()) {
+        try {
+          resolved = await realpath(full);
+        } catch {
+          escaping.push(relPath);
+          continue;
+        }
+        if (resolved !== realRoot && !resolved.startsWith(realRoot + sep)) {
+          escaping.push(relPath);
+          continue;
+        }
+      }
+      const isDir = entry.isDirectory() || entry.isSymbolicLink() && await isDirectory(resolved);
+      if (isDir) {
+        await walk(resolved);
+        continue;
+      }
+      if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+      if (relPath.length > MAX_PATH_LENGTH) {
+        tooLongPath.push(relPath);
+        continue;
+      }
+      const text = decodeUtf8(await readFile(resolved), relPath, notText);
+      if (text !== void 0) files.push({ path: relPath, content: text });
+    }
+  }
+  await walk(realRoot);
+  if (notText.length > 0) {
+    throw new Error(
+      `A skill can only hold text files (the column that stores them is text, not bytes). Not text: ${notText.sort().join(", ")}. Remove them from the directory, or keep them out of the skill entirely.`
+    );
+  }
+  if (escaping.length > 0) {
+    throw new Error(
+      `These symlinks point outside the skill directory and were refused: ${escaping.sort().join(", ")}. Replace them with real files if they belong to the skill.`
+    );
+  }
+  if (tooLongPath.length > 0) {
+    throw new Error(
+      `These paths exceed the ${MAX_PATH_LENGTH}-character limit: ${tooLongPath.sort().join(", ")}.`
+    );
+  }
+  if (files.length > MAX_FILES) {
+    throw new Error(
+      `A skill bundle is capped at ${MAX_FILES} files; ${skillDir} has ${files.length}.`
+    );
+  }
+  const total = Buffer.byteLength(content, "utf8") + files.reduce((n, f) => n + digest(f.content).bytes, 0);
+  if (total > MAX_BUNDLE_BYTES) {
+    const biggest = digestFiles(files).sort((a, b) => b.bytes - a.bytes).slice(0, 5).map((f) => `${f.path} (${Math.round(f.bytes / 1024)} KB)`);
+    throw new Error(
+      `The bundle is ${Math.round(total / 1024)} KB, over the ${MAX_BUNDLE_BYTES / 1024 / 1024} MB cap. Largest files: ${biggest.join(", ")}.`
+    );
+  }
+  files.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  return { content, files };
+}
+async function isDirectory(path) {
+  try {
+    await readdir(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function writeSkillFiles(outDir, files, opts) {
+  const root = resolve(outDir);
+  await mkdir(root, { recursive: true });
+  const realRoot = await realpath(root);
+  const targets = files.map((file) => {
+    const target = resolve(realRoot, file.path);
+    if (target !== realRoot && !target.startsWith(realRoot + sep)) {
+      throw new Error(`Refusing to write outside outDir: ${file.path}`);
+    }
+    return { file, target };
+  });
+  if (!opts.overwrite) {
+    const conflicts = [];
+    for (const { file, target } of targets) {
+      const existing = await readFile(target, "utf8").catch(() => void 0);
+      if (existing !== void 0 && existing !== file.content) conflicts.push(file.path);
+    }
+    if (conflicts.length > 0) {
+      throw new Error(
+        `These files already exist in ${root} with different content: ${conflicts.sort().join(", ")}. Nothing was written. Pass overwrite: true to replace them.`
+      );
+    }
+  }
+  for (const { file, target } of targets) {
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, file.content, "utf8");
+  }
+  return digestFiles(files);
+}
+
+// src/tools/skills.ts
+function skillMetadata(skill) {
+  return {
+    id: skill.id,
+    name: skill.name,
+    description: skill.description ?? null,
+    status: skill.status,
+    origin: skill.origin,
+    currentVersion: skill.currentVersion ?? null,
+    updatedAt: skill.updatedAt,
+    canEdit: skill.canEdit,
+    fileCount: skill.files?.length ?? 0,
+    usedBy: skill.usedBy ?? []
+  };
+}
+function writeReceipt(skill) {
+  return {
+    id: skill.id,
+    name: skill.name,
+    currentVersion: skill.currentVersion ?? null,
+    updatedAt: skill.updatedAt,
+    content: digest(skill.content ?? ""),
+    files: digestFiles(skill.files ?? [])
+  };
+}
+async function resolveBundle(args) {
+  if (args.skillDir === void 0) return { content: args.content, files: args.files };
+  if (args.content !== void 0 || args.files !== void 0) {
+    throw new Error(
+      "skillDir cannot be combined with content or files: pass the directory alone (its SKILL.md becomes the content and everything else becomes the files), or pass content/files inline."
+    );
+  }
+  return readSkillDir(args.skillDir);
+}
+var FILES_SEMANTICS = "Omitting `files` keeps the existing ones; sending it REPLACES the whole set, so a file missing from the list is deleted (`files: []` deletes all of them). To delete a file, leave it out of the directory (or the array) and upload.";
+var SKILL_DIR_HELP = "Path to a skill directory on disk \u2014 `SKILL.md` at its root becomes the content (frontmatter included) and every other file becomes an embedded file, path relative to the directory. This is the layout download-skill writes with outDir, so the loop is: download to a folder, edit, upload the folder. Prefer this over inline content for anything non-trivial \u2014 it costs the same whether the skill is 1 KB or 1 MB. Text files only; .git/node_modules/__pycache__/.venv are skipped.";
 function registerSkillTools(server2, client, ctx2) {
   server2.registerTool(
     "list-skills",
     {
-      description: "List skill definitions (active by default). Returns id, name, description, status, origin, version, and timestamps.",
+      description: "List skill definitions (active by default). Metadata only \u2014 id, name, description, status, origin, version, file count and timestamps. Use get-skill or download-skill to read a specific skill.",
       inputSchema: {
-        status: z2.enum(["active", "archived"]).optional().describe("Lifecycle filter \u2014 defaults to 'active'; pass 'archived' for archived skills")
+        status: z2.enum(["active", "archived"]).optional().describe("Lifecycle filter \u2014 defaults to 'active'; pass 'archived' for archived skills"),
+        query: z2.string().optional().describe("Case-insensitive substring match against the name and description")
       },
       annotations: { readOnlyHint: true }
     },
-    async ({ status }) => {
-      const query = status ? `?status=${status}` : "";
-      const page = await client.get(`/api/skills${query}`);
-      return jsonResult({ items: page.items, total: page.total });
+    async ({ status, query }) => {
+      const qs = status ? `?status=${status}` : "";
+      const page = await client.get(`/api/skills${qs}`);
+      const needle = query?.trim().toLowerCase();
+      const items = page.items.filter(
+        (s) => !needle || s.name.toLowerCase().includes(needle) || (s.description ?? "").toLowerCase().includes(needle)
+      ).map(skillMetadata);
+      return jsonResult({ items, total: items.length, totalBeforeFilter: page.total });
     }
   );
   server2.registerTool(
     "get-skill",
     {
-      description: "Get detailed information about a specific skill, including content, allowed tools, files, and version info.",
+      description: "Get detailed information about a specific skill, including content, allowed tools, files, and version info. For a large skill prefer download-skill with outDir, which puts the files on disk instead of in the conversation.",
       inputSchema: {
-        id: z2.string().describe("Skill ID (UUID)")
+        id: z2.string().describe("Skill ID (UUID)"),
+        includeContent: z2.boolean().optional().describe(
+          "Defaults to true. With false, returns metadata plus a size and sha256 per file \u2014 enough to check what is stored without pulling the content in."
+        )
       },
       annotations: { readOnlyHint: true }
     },
-    async ({ id }) => {
+    async ({ id, includeContent }) => {
       const skill = await client.get(`/api/skills/${id}`);
+      if (includeContent === false) {
+        return jsonResult({
+          ...skillMetadata(skill),
+          model: skill.model ?? null,
+          allowedTools: skill.allowedTools ?? [],
+          content: digest(skill.content ?? ""),
+          files: digestFiles(skill.files ?? [])
+        });
+      }
       return jsonResult(skill);
     }
   );
@@ -567,18 +773,30 @@ function registerSkillTools(server2, client, ctx2) {
   server2.registerTool(
     "download-skill",
     {
-      description: "Download a skill as files in the target tool's on-disk layout (e.g. .claude/skills/<name>/SKILL.md for Claude Code). Returns {files: [{path, content}]} \u2014 write each file at its path relative to the current working directory. Iterate locally, then push changes back with update-skill.",
+      description: "Download a skill as files in the target tool's on-disk layout (e.g. .claude/skills/<name>/SKILL.md for Claude Code). With `outDir` the files are written to disk and only their paths, sizes and hashes come back \u2014 the way to handle a skill of any size. Without it, the content is returned inline. Then edit the folder and push it back with update-skill + skillDir.",
       inputSchema: {
         id: z2.string().describe("Skill ID (UUID)"),
         format: z2.enum(["claude-code", "codex", "kimi-code", "opencode", "raw"]).optional().describe(
           "Target tool layout \u2014 defaults to 'claude-code'; 'raw' is the dudamel-native <name>/SKILL.md layout"
+        ),
+        outDir: z2.string().optional().describe(
+          "Directory to write the files into (created if missing). Paths from the chosen format are kept, so outDir is the root the layout hangs from."
+        ),
+        overwrite: z2.boolean().optional().describe(
+          "Defaults to false: if a file already exists with different content the call is rejected and nothing is written, so a re-download cannot erase edits in flight."
         )
       },
       annotations: { readOnlyHint: true }
     },
-    async ({ id, format }) => {
-      const result = await client.get(`/api/skills/${id}/export?format=${format ?? "claude-code"}`);
-      return jsonResult(result);
+    async ({ id, format, outDir, overwrite }) => {
+      const result = await client.get(
+        `/api/skills/${id}/export?format=${format ?? "claude-code"}`
+      );
+      if (outDir === void 0) return jsonResult(result);
+      const written = await writeSkillFiles(outDir, result.files, {
+        overwrite: overwrite ?? false
+      });
+      return jsonResult({ skillName: result.skillName, outDir, files: written });
     }
   );
   server2.registerTool(
@@ -599,10 +817,13 @@ function registerSkillTools(server2, client, ctx2) {
   server2.registerTool(
     "create-skill",
     {
-      description: "Create a new skill definition. The creator becomes the owner and can edit it and share edition with business roles via set-skill-roles.",
+      description: "Create a new skill definition. The creator becomes the owner and can edit it and share edition with business roles via set-skill-roles. Pass `skillDir` to upload a directory from disk instead of inlining every file. Returns the new version plus a size and sha256 per stored file. " + FILES_SEMANTICS,
       inputSchema: {
         name: z2.string().describe("Skill name (unique, kebab-case)"),
-        content: z2.string().describe("Skill content (markdown body)"),
+        content: z2.string().optional().describe(
+          "Skill content \u2014 the full SKILL.md is fine: its frontmatter (description, version, allowed-tools, model) is honored, and an argument passed explicitly here wins over it. Required unless skillDir is given."
+        ),
+        skillDir: z2.string().optional().describe(SKILL_DIR_HELP),
         description: z2.string().optional().describe("Skill description"),
         disableModelInvocation: z2.boolean().optional().describe("Disable model-triggered invocation"),
         userInvocable: z2.boolean().optional().describe("Allow user to invoke via slash command"),
@@ -614,13 +835,14 @@ function registerSkillTools(server2, client, ctx2) {
             path: z2.string().describe("Relative file path within the skill"),
             content: z2.string().describe("File content")
           })
-        ).optional().describe("Embedded skill files")
+        ).optional().describe(`Embedded skill files. ${FILES_SEMANTICS}`)
       },
       annotations: { readOnlyHint: false, destructiveHint: false }
     },
     async ({
       name,
       content,
+      skillDir,
       description,
       disableModelInvocation,
       userInvocable,
@@ -629,30 +851,37 @@ function registerSkillTools(server2, client, ctx2) {
       currentVersion,
       files
     }) => {
+      const bundle = await resolveBundle({ content, files, skillDir });
+      if (bundle.content === void 0) {
+        throw new Error("A new skill needs either content or skillDir.");
+      }
       const result = await client.post("/api/skills", {
         name,
-        content,
+        content: bundle.content,
         description,
         disableModelInvocation,
         userInvocable,
         model,
         allowedTools,
         currentVersion,
-        files
+        files: bundle.files
       });
-      return jsonResult(result);
+      return jsonResult(writeReceipt(result));
     }
   );
   server2.registerTool(
     "update-skill",
     {
-      description: "Update a skill definition. Creates a new version entry.",
+      description: "Update a skill definition. Creates a new version entry. Pass `skillDir` to upload an edited directory from disk in one call instead of retyping every file. Returns the new version plus a size and sha256 per stored file, so the upload can be verified without downloading it back. " + FILES_SEMANTICS,
       inputSchema: {
         id: z2.string().describe("Skill ID (UUID)"),
         name: z2.string().optional().describe(
           "New skill name (unique, kebab-case) \u2014 rename the skill; agent assignments are by id and survive the rename"
         ),
-        content: z2.string().optional().describe("New skill content"),
+        content: z2.string().optional().describe(
+          "New skill content \u2014 the full SKILL.md is fine: its frontmatter (description, version, allowed-tools, model) is honored, and an argument passed explicitly here wins over it."
+        ),
+        skillDir: z2.string().optional().describe(SKILL_DIR_HELP),
         description: z2.string().optional().describe("New description"),
         disableModelInvocation: z2.boolean().optional().describe("Disable model-triggered invocation"),
         userInvocable: z2.boolean().optional().describe("Allow user to invoke via slash command"),
@@ -665,13 +894,22 @@ function registerSkillTools(server2, client, ctx2) {
             path: z2.string().describe("Relative file path within the skill"),
             content: z2.string().describe("File content")
           })
-        ).optional().describe("Embedded skill files")
+        ).optional().describe(`Embedded skill files. ${FILES_SEMANTICS}`)
       },
       annotations: { readOnlyHint: false, destructiveHint: false }
     },
-    async ({ id, ...updates }) => {
-      const result = await client.put(`/api/skills/${id}`, updates);
-      return jsonResult(result);
+    async ({ id, skillDir, ...updates }) => {
+      const bundle = await resolveBundle({
+        content: updates.content,
+        files: updates.files,
+        skillDir
+      });
+      const result = await client.put(`/api/skills/${id}`, {
+        ...updates,
+        content: bundle.content,
+        files: bundle.files
+      });
+      return jsonResult(writeReceipt(result));
     }
   );
   server2.registerTool(

package/dist/tools/skills.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/tools/skills.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGvD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,gBAAgB,EACxB,GAAG,EAAE,WAAW,GACf,IAAI,CA4RN"}
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/tools/skills.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AA6FvD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,gBAAgB,EACxB,GAAG,EAAE,WAAW,GACf,IAAI,CA+XN"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudamel/mcp-agents",
-  "version": "2026.918.1",
+  "version": "2026.923.1",
   "description": "Dudamel agents MCP — stdio client for Dudamel's agents management surface over its REST API.",
   "license": "SEE LICENSE IN LICENSE.md",
   "type": "module",