@vellumai/assistant 0.12.2-staging.5 → 0.12.2-staging.6

package/src/live-voice/session-controls.ts

@@ -8,6 +8,7 @@ import {
   NORMAL_UPDATES_MARKER,
   parseTerminalSessionControl,
   type SessionControlRequest,
+  TASK_STOP_MARKER,
 } from "../calls/voice-control-protocol.js";
 import type { VoiceProgressConfig } from "../config/schemas/voice.js";
 import type { LiveVoiceSessionControl } from "./protocol.js";
@@ -86,6 +87,8 @@ export function lookFollowUpNote(action: LookSessionControl): string {
 // to carry it out.
 const UPDATES_LINE = `- To hear fewer spoken progress updates while you work (for example "don't give me updates so often"), confirm that you will only check in now and then and will tell them when it is done, then end your reply with ${FEWER_UPDATES_MARKER}. If they later want regular updates back, confirm and end with ${NORMAL_UPDATES_MARKER}.`;
 
+const TASK_STOP_LINE = `- To abandon the unfinished task while keeping the call open (for example "stop that" or "never mind about that task"), confirm briefly, then end your reply with ${TASK_STOP_MARKER}. Use this only when they want the task abandoned, not when they interrupt with a question or correction.`;
+
 /**
  * The control-prompt block that teaches the session controls: the ones the
  * client declared plus the progress-update cadence. Every leg gets it,
@@ -98,7 +101,7 @@ const UPDATES_LINE = `- To hear fewer spoken progress updates while you work (fo
 export function sessionControlTeaching(
   controls: readonly LiveVoiceSessionControl[],
   leg: { frontDoor?: boolean },
-  client: { lookFrames?: boolean } = {},
+  client: { lookFrames?: boolean; unfinishedTaskPending?: boolean } = {},
 ): string {
   const lines =
     client.lookFrames === true
@@ -109,6 +112,7 @@ export function sessionControlTeaching(
     ...controls.map((control) => lines[control]),
     ...lookGuidance(controls),
     UPDATES_LINE,
+    ...(client.unfinishedTaskPending === true ? [TASK_STOP_LINE] : []),
     `The marker must be the very last thing in your reply. It is never spoken and does nothing anywhere else.${leg.frontDoor === true ? "" : " Never emit any other bracketed marker."}`,
   ].join("\n");
 }
@@ -137,7 +141,7 @@ function lookGuidance(controls: readonly LiveVoiceSessionControl[]): string[] {
 /** A session control the client carries out, sent as a `session_control` frame. */
 export type ClientSessionControlRequest = Exclude<
   SessionControlRequest,
-  { action: "updates" }
+  { action: "updates" } | { action: "task_stop" }
 >;
 
 /**
@@ -154,7 +158,7 @@ export function requestedSessionControl(
   if (request === null) {
     return null;
   }
-  if (request.action === "updates") {
+  if (request.action === "updates" || request.action === "task_stop") {
     return request;
   }
   return controls.includes(request.action) ? request : null;

package/src/monitoring/plugin-auto-update.ts

@@ -155,6 +155,12 @@ function tracksCuratedSource(inspection: PluginInspection): boolean {
   if (!remote) {
     return false;
   }
+  if (source.kind === "local") {
+    return remote.kind === "local" && source.path === remote.path;
+  }
+  if (remote.kind === "local") {
+    return false;
+  }
   return (
     `${source.owner}/${source.repo}`.toLowerCase() ===
       remote.repo.toLowerCase() && (source.path ?? "") === remote.path

package/src/plugins/defaults/memory/__tests__/memory-retrospective-prompt.test.ts

@@ -125,6 +125,11 @@ For everything else in your review window, use the \`remember\` tool on facts, p
     expect(out).toContain(
       "restate `current.activation_hints` (revised only if the procedure's triggers changed",
     );
+    // The store keeps omitted frontmatter on an overwrite, so the pass is told
+    // to leave unchanged fields out rather than restate them from memory.
+    expect(out).toContain(
+      "an omitted field keeps its current value and an empty one clears it",
+    );
     // An UPDATE is announced by a notice whose only account of the change is
     // what the pass passes here, so the instruction has to ask for it.
     expect(out).toContain(

package/src/plugins/defaults/memory/memory-retrospective-prompt.ts

@@ -223,7 +223,7 @@ If your review window contains a PROCEDURE you actually carried out — a sequen
 
 When you do capture a procedure:
 
-1. Deduplicate against existing skills first. Call \`find_similar_skills\` with the procedure's goal as its \`goal\` argument. Each hit carries a \`source\` (bundled, managed, plugin, workspace, or extra), and a managed hit also carries \`author\` (\`"assistant"\` if you authored it, \`"user"\` if a person did, omitted if untagged). You may only overwrite or refine a skill YOU authored: a hit with \`source: "managed"\` AND \`author: "assistant"\`. ANY other hit means the procedure is ALREADY COVERED: a non-managed source (bundled, plugin, workspace, or extra), OR a managed skill that is NOT \`author: "assistant"\` (a person wrote it, or it is untagged). For an ALREADY COVERED hit do not \`overwrite\` it, do not shadow it by creating a skill with its \`skill_id\`, and do not create a near-duplicate. Skip it. Only when a returned skill is one of your own (\`source: "managed"\`, \`author: "assistant"\`) and is the SAME procedure, UPDATE it. Such a hit carries \`current\`: the skill as it is now, in \`scaffold_managed_skill\`'s own argument names. Call \`scaffold_managed_skill\` with that \`skill_id\` and \`overwrite: true\`, rewriting \`body_markdown\` from \`current.body_markdown\` plus what you actually observed in the trace (keep the steps the trace did not contradict; correct or add the ones it did), restate \`current.activation_hints\` (revised only if the procedure's triggers changed; they are the skill's retrieval signal, not something to regenerate) and every other \`current\` field you are not changing (\`emoji\`, \`category\`, \`includes\`, \`avoid_when\`) since an overwrite replaces the whole file, and pass \`change_summary\` (the update is rejected without it): one or two short sentences (under 200 characters) for the person who reads the "Skill updated" notice, naming what you changed and what in the trace prompted it (for example "Added the retry after an expired session and the export endpoint that held steady."). The notice shows nothing else about the change, so name the concrete step, value, or gotcha rather than saying the skill was refined. Only CREATE a new skill (fresh \`skill_id\`) when no existing skill of any source covers the procedure. Bias strongly toward reusing or refining your own skills over spawning near-duplicates.
+1. Deduplicate against existing skills first. Call \`find_similar_skills\` with the procedure's goal as its \`goal\` argument. Each hit carries a \`source\` (bundled, managed, plugin, workspace, or extra), and a managed hit also carries \`author\` (\`"assistant"\` if you authored it, \`"user"\` if a person did, omitted if untagged). You may only overwrite or refine a skill YOU authored: a hit with \`source: "managed"\` AND \`author: "assistant"\`. ANY other hit means the procedure is ALREADY COVERED: a non-managed source (bundled, plugin, workspace, or extra), OR a managed skill that is NOT \`author: "assistant"\` (a person wrote it, or it is untagged). For an ALREADY COVERED hit do not \`overwrite\` it, do not shadow it by creating a skill with its \`skill_id\`, and do not create a near-duplicate. Skip it. Only when a returned skill is one of your own (\`source: "managed"\`, \`author: "assistant"\`) and is the SAME procedure, UPDATE it. Such a hit carries \`current\`: the skill as it is now, in \`scaffold_managed_skill\`'s own argument names. Call \`scaffold_managed_skill\` with that \`skill_id\` and \`overwrite: true\`, rewriting \`body_markdown\` from \`current.body_markdown\` plus what you actually observed in the trace (keep the steps the trace did not contradict; correct or add the ones it did), restate \`current.activation_hints\` (revised only if the procedure's triggers changed; they are the skill's retrieval signal, not something to regenerate) and leave out any other \`current\` field you are not changing (\`emoji\`, \`category\`, \`includes\`, \`avoid_when\`): an omitted field keeps its current value and an empty one clears it, and pass \`change_summary\` (the update is rejected without it): one or two short sentences (under 200 characters) for the person who reads the "Skill updated" notice, naming what you changed and what in the trace prompted it (for example "Added the retry after an expired session and the export endpoint that held steady."). The notice shows nothing else about the change, so name the concrete step, value, or gotcha rather than saying the skill was refined. Only CREATE a new skill (fresh \`skill_id\`) when no existing skill of any source covers the procedure. Bias strongly toward reusing or refining your own skills over spawning near-duplicates.
 
 2. Capture procedure-scoped knowledge alongside the body. Failure modes, gotchas, and cached values you observed in the trace (error signatures and how you recovered, preconditions, IDs/paths/endpoints that held steady) belong in companion files passed via \`scaffold_managed_skill\`'s \`files\` input (for example \`references/failure-modes.md\`), and the SKILL.md body should reference them so a future load surfaces them.
 

package/src/runtime/routes/__tests__/plugins-routes.test.ts

@@ -1082,6 +1082,64 @@ describe("GET /v1/plugins/search", () => {
     expect("icon" in byName.get("plain-plugin")!).toBe(false);
   });
 
+  test("preserves a bundled MCP package source and integration metadata", async () => {
+    getCatalogSpy.mockImplementation(async (ref) =>
+      catalog(ref, [
+        {
+          name: "fathom",
+          path: "local:plugins/mcp-catalog/fathom@1.0.0",
+          description: "Search meeting transcripts.",
+          category: null,
+          integration: {
+            kind: "mcp",
+            displayName: "Fathom",
+            documentationUrl: "https://example.com/fathom/docs",
+            verifiedAt: "2026-09-15",
+            verification: "documentation-only",
+            setup: {
+              mode: "oauth",
+              instructions: "Connect your Fathom account.",
+            },
+            logo: "fathom.png",
+          },
+          source: {
+            kind: "local",
+            path: "plugins/mcp-catalog/fathom",
+            version: "1.0.0",
+          },
+        },
+      ]),
+    );
+
+    const result = await invokeSearch({ queryParams: { q: "fathom" } });
+
+    expect(result.matches).toEqual([
+      {
+        name: "fathom",
+        path: "local:plugins/mcp-catalog/fathom@1.0.0",
+        description: "Search meeting transcripts.",
+        category: null,
+        integration: {
+          kind: "mcp",
+          displayName: "Fathom",
+          documentationUrl: "https://example.com/fathom/docs",
+          verifiedAt: "2026-09-15",
+          verification: "documentation-only",
+          setup: {
+            mode: "oauth",
+            instructions: "Connect your Fathom account.",
+          },
+          logo: "fathom.png",
+        },
+        source: {
+          kind: "local",
+          path: "plugins/mcp-catalog/fathom",
+          version: "1.0.0",
+        },
+      },
+    ]);
+  });
+
   test("normalizes match categories to the Skills taxonomy (`developer` → `development`, `hobby` → null)", async () => {
     getCatalogSpy.mockImplementation(async (ref) =>
       catalog(ref, [
@@ -1607,6 +1665,50 @@ describe("POST /v1/plugins/install", () => {
     }
   });
 
+  test("installs a bundled package from the exact catalog source", async () => {
+    getCatalogSpy.mockImplementation(async (ref) =>
+      catalog(ref, [
+        {
+          name: "fathom",
+          path: "local:plugins/mcp-catalog/fathom@1.0.0",
+          category: null,
+          source: {
+            kind: "local",
+            path: "plugins/mcp-catalog/fathom",
+            version: "1.0.0",
+          },
+        },
+      ]),
+    );
+    installSpy.mockImplementation(async (opts) => ({
+      name: opts.name,
+      target: `/workspace/.vellum/plugins/${opts.name}`,
+      fileCount: 2,
+      ref: "1.0.0",
+      commit: null,
+      committedAt: null,
+    }));
+
+    const result = await invokeInstall({ body: { name: "fathom" } });
+
+    expect(installSpy.mock.calls[0]?.[0]).toEqual({
+      name: "fathom",
+      force: undefined,
+      trustedSource: {
+        kind: "local",
+        path: "plugins/mcp-catalog/fathom",
+        version: "1.0.0",
+      },
+    });
+    expect(result).toEqual({
+      ok: true,
+      name: "fathom",
+      target: "/workspace/.vellum/plugins/fathom",
+      fileCount: 2,
+      ref: "1.0.0",
+    });
+  });
+
   test("publishes sync_changed(plugins:list) on a successful install", async () => {
     installSpy.mockImplementation(async (opts) => trustedInstallResult(opts));
 

package/src/runtime/routes/plugins-routes.ts

@@ -2,7 +2,7 @@
  * Route handlers for the assistant plugins surface.
  *
  * GET    /v1/plugins          — list installed plugins under `<workspaceDir>/plugins/`.
- * GET    /v1/plugins/search   — search the canonical GitHub catalog of installable plugins.
+ * GET    /v1/plugins/search   - search the reviewed catalog of installable plugins.
  * GET    /v1/plugins/:name    — resolve a single plugin's detail view (metadata + README).
  * POST   /v1/plugins/install  — install a plugin by name from the canonical source.
  * DELETE /v1/plugins/:name    — uninstall a plugin from `<workspaceDir>/plugins/<name>/`.
@@ -192,30 +192,47 @@ const pluginsListResponseSchema = z.object({
 });
 
 const pluginMatchSourceSchema = z
-  .object({
-    kind: z.literal("github"),
-    repo: z
-      .string()
-      .describe("`owner/repo` of the external plugin repository."),
-    path: z
-      .string()
-      .optional()
-      .describe(
-        "Directory within the repo, when the plugin is not at the root.",
-      ),
-    ref: z.string().describe("Pinned git ref the plugin is fetched from."),
-  })
-  .describe("Origin of the match: a whitelisted external plugin repository.");
+  .discriminatedUnion("kind", [
+    z.object({
+      kind: z.literal("github"),
+      repo: z
+        .string()
+        .describe("`owner/repo` of the external plugin repository."),
+      path: z
+        .string()
+        .optional()
+        .describe(
+          "Directory within the repo, when the plugin is not at the root.",
+        ),
+      ref: z.string().describe("Pinned git ref the plugin is fetched from."),
+    }),
+    z.object({
+      kind: z.literal("local"),
+      path: z.string().describe("Package key in the assistant bundle."),
+      version: z.string().describe("Bundled package version."),
+    }),
+  ])
+  .describe("Reviewed source of the marketplace entry.");
+
+const mcpPluginIntegrationSchema = z.object({
+  kind: z.literal("mcp"),
+  displayName: z.string(),
+  documentationUrl: z.string(),
+  verifiedAt: z.string(),
+  verification: z.literal("documentation-only"),
+  setup: z.object({
+    mode: z.enum(["oauth", "manual"]),
+    instructions: z.string(),
+  }),
+  logo: z.string(),
+  oauthProvider: z.string().optional(),
+});
 
 const pluginSearchMatchSchema = z.object({
   name: z
     .string()
     .describe("Install name. Matches `assistant plugins install <name>`."),
-  path: z
-    .string()
-    .describe(
-      "Human-readable origin: a `github:owner/repo@ref` locator for the external plugin.",
-    ),
+  path: z.string().describe("Human-readable catalog origin locator."),
   description: z
     .string()
     .optional()
@@ -232,6 +249,7 @@ const pluginSearchMatchSchema = z.object({
     .describe(
       "Marketplace category slug (Skills taxonomy); null when the entry declares none.",
     ),
+  integration: mcpPluginIntegrationSchema.optional(),
   source: pluginMatchSourceSchema,
 });
 
@@ -418,22 +436,20 @@ const fingerprintComparisonSchema = z
   );
 
 const installMetaSourceSchema = z
-  .object({
-    kind: z.string().describe("Source kind. Only `github` is written today."),
-    owner: z.string(),
-    repo: z.string(),
-    path: z
-      .string()
-      .optional()
-      .describe(
-        "Repo-relative directory holding the plugin root; absent = repo root.",
-      ),
-    ref: z
-      .string()
-      .describe(
-        "Ref the install resolved through (the pinned commit SHA for marketplace installs).",
-      ),
-  })
+  .discriminatedUnion("kind", [
+    z.object({
+      kind: z.literal("github"),
+      owner: z.string(),
+      repo: z.string(),
+      path: z.string().optional(),
+      ref: z.string(),
+    }),
+    z.object({
+      kind: z.literal("local"),
+      path: z.string(),
+      version: z.string(),
+    }),
+  ])
   .describe(
     "Source coordinates recorded in the install-time provenance sidecar.",
   );
@@ -489,6 +505,7 @@ const pluginLocalInfoSchema = z
 
 const pluginRemoteInfoSchema = z
   .object({
+    kind: z.literal("local").optional(),
     repo: z
       .string()
       .describe("`owner/repo` of the external plugin repository."),
@@ -517,6 +534,7 @@ const pluginRemoteInfoSchema = z
       .describe(
         "Ref of the canonical repo the marketplace manifest was read from.",
       ),
+    version: z.string().optional().describe("Bundled package version."),
   })
   .describe("The marketplace's current pin and advertised metadata.");
 
@@ -870,7 +888,8 @@ interface PluginMatchView {
   description?: string;
   icon?: string;
   category: string | null;
-  source: { kind: "github"; repo: string; path?: string; ref: string };
+  integration?: PluginSearchMatch["integration"];
+  source: PluginSearchMatch["source"];
 }
 
 /**
@@ -886,12 +905,7 @@ function projectMatch(
     name: m.name,
     path: m.path,
     category: normalizeMarketplaceCategory(m.category, validSlugs),
-    source: {
-      kind: "github",
-      repo: m.source.repo,
-      ref: m.source.ref,
-      ...(m.source.path !== undefined ? { path: m.source.path } : {}),
-    },
+    source: { ...m.source },
   };
   if (m.description !== undefined) {
     view.description = m.description;
@@ -899,6 +913,9 @@ function projectMatch(
   if (m.icon !== undefined) {
     view.icon = m.icon;
   }
+  if (m.integration !== undefined) {
+    view.integration = m.integration;
+  }
   return view;
 }
 
@@ -1276,12 +1293,15 @@ async function handleInstallPlugin({ body = {}, headers }: RouteHandlerArgs) {
         {
           name,
           force,
-          trustedSource: {
-            owner: source.owner,
-            repo: source.repo,
-            rootPath: source.path,
-            ref: source.ref,
-          },
+          trustedSource:
+            source.kind === "local"
+              ? source
+              : {
+                  owner: source.owner,
+                  repo: source.repo,
+                  rootPath: source.path,
+                  ref: source.ref,
+                },
         },
         { fetch: globalThis.fetch.bind(globalThis) },
       );

package/src/skills/managed-store.ts

@@ -18,6 +18,7 @@ import { parseFrontmatter } from "../config/skills.js";
 import { deleteSkillCapabilityNode } from "../plugins/defaults/memory/graph/capability-seed.js";
 import { isDeniedBasename } from "../tools/shared/filesystem/path-policy.js";
 import { getLogger } from "../util/logger.js";
+import { isPlainObject } from "../util/object.js";
 import { getWorkspaceDir, getWorkspaceSkillsDir } from "../util/platform.js";
 import { parseFrontmatterFields } from "./frontmatter.js";
 import { writeInstallMeta } from "./install-meta.js";
@@ -212,11 +213,48 @@ interface BuildSkillMarkdownInput {
   name: string;
   description: string;
   bodyMarkdown: string;
+  /**
+   * The five fields the scaffold tool owns. `undefined` leaves whatever
+   * `preserve` carries for that field (nothing, on a create); an empty value
+   * clears it; a value sets it.
+   */
   emoji?: string;
   includes?: string[];
   activationHints?: string[];
   avoidWhen?: string[];
   category?: string;
+  /**
+   * The skill's existing frontmatter, as parsed from disk, for an overwrite.
+   * Every key survives except `name`, `description`, and the five fields
+   * above, so a `platforms` gate, a `display-name`, or custom metadata a
+   * person added by hand is not lost to a call that never mentions it.
+   */
+  preserve?: Record<string, unknown>;
+}
+
+/**
+ * Apply one tool-owned field to the vellum block: an input left `undefined`
+ * keeps the preserved value, an input given but empty (`value` undefined)
+ * clears it, and a value sets it.
+ */
+function setOrClear(
+  target: Record<string, unknown>,
+  key: string,
+  value: unknown,
+  input: unknown,
+): void {
+  if (input === undefined) {
+    return;
+  }
+  if (value === undefined) {
+    delete target[key];
+  } else {
+    target[key] = value;
+  }
+}
+
+function nonEmptyList(list: string[] | undefined): string[] | undefined {
+  return list && list.length > 0 ? list : undefined;
 }
 
 export function buildSkillMarkdown(input: BuildSkillMarkdownInput): string {
@@ -230,40 +268,55 @@ export function buildSkillMarkdown(input: BuildSkillMarkdownInput): string {
   lines.push(`name: "${esc(input.name)}"`);
   lines.push(`description: "${esc(input.description)}"`);
 
-  // Build metadata object matching the format parseFrontmatter expects:
-  // metadata:
-  //   vellum:
-  //     emoji: "..."
-  const vellum: Record<string, unknown> = {};
-  if (input.emoji) {
-    vellum.emoji = input.emoji;
-  }
-  if (input.includes && input.includes.length > 0) {
-    vellum.includes = input.includes;
-  }
-  // Kebab-case keys match what parseFrontmatter reads back
-  // (config/skills.ts: vellum["activation-hints"] / vellum["avoid-when"]).
-  // These flow through stringifyYaml below, which escapes/quotes values, so no
+  // Everything but name and description is emitted from one object: the
+  // preserved frontmatter with the tool-owned fields applied over it, under
+  // `metadata.vellum` where parseFrontmatter reads them back (kebab-case for
+  // the two list fields). stringifyYaml quotes and escapes values, so no
   // manual sanitization is needed here.
-  if (input.activationHints && input.activationHints.length > 0) {
-    vellum["activation-hints"] = input.activationHints;
+  const rest: Record<string, unknown> = structuredClone(input.preserve ?? {});
+  delete rest.name;
+  delete rest.description;
+  const metadata = isPlainObject(rest.metadata) ? rest.metadata : {};
+  const vellum = isPlainObject(metadata.vellum) ? metadata.vellum : {};
+  setOrClear(vellum, "emoji", input.emoji?.trim() || undefined, input.emoji);
+  // An emoji at the legacy `metadata.emoji` location wins over an absent
+  // vellum one on read, so a call that states the emoji retires it.
+  if (input.emoji !== undefined) {
+    delete metadata.emoji;
   }
-  if (input.avoidWhen && input.avoidWhen.length > 0) {
-    vellum["avoid-when"] = input.avoidWhen;
+  setOrClear(vellum, "includes", nonEmptyList(input.includes), input.includes);
+  setOrClear(
+    vellum,
+    "activation-hints",
+    nonEmptyList(input.activationHints),
+    input.activationHints,
+  );
+  setOrClear(
+    vellum,
+    "avoid-when",
+    nonEmptyList(input.avoidWhen),
+    input.avoidWhen,
+  );
+  // The web Skills UI buckets skills by this value; a blank one is a clear,
+  // never an empty bucket in the file.
+  setOrClear(
+    vellum,
+    "category",
+    input.category?.trim() || undefined,
+    input.category,
+  );
+  if (Object.keys(vellum).length > 0) {
+    metadata.vellum = vellum;
+  } else {
+    delete metadata.vellum;
   }
-  // The web Skills UI groups skills into a category sidebar by this value;
-  // skip it when blank so an empty bucket assignment never lands in frontmatter.
-  if (input.category?.trim()) {
-    vellum.category = input.category.trim();
+  if (Object.keys(metadata).length > 0) {
+    rest.metadata = metadata;
+  } else {
+    delete rest.metadata;
   }
-
-  if (Object.keys(vellum).length > 0) {
-    const metadata = { vellum };
-    const yamlBlock = stringifyYaml(metadata, { indent: 2 });
-    lines.push("metadata:");
-    for (const yamlLine of yamlBlock.trimEnd().split("\n")) {
-      lines.push(`  ${yamlLine}`);
-    }
+  if (Object.keys(rest).length > 0) {
+    lines.push(stringifyYaml(rest, { indent: 2 }).trimEnd());
   }
 
   lines.push("---");
@@ -350,7 +403,8 @@ export function createManagedSkill(
   const skillDir = getManagedSkillDir(params.id);
   const skillFilePath = join(skillDir, "SKILL.md");
 
-  if (existsSync(skillFilePath) && !params.overwrite) {
+  const skillExists = existsSync(skillFilePath);
+  if (skillExists && !params.overwrite) {
     return {
       created: false,
       path: skillFilePath,
@@ -358,6 +412,14 @@ export function createManagedSkill(
     };
   }
 
+  // An overwrite replaces the body and patches the frontmatter: a field the
+  // call leaves undefined keeps its current value, an explicit empty value
+  // clears it, and frontmatter the tool does not own passes through. Callers
+  // rarely hold every field (the retrospective sees a skill through a
+  // similarity hit; a user edit is "change step 3"), so a field they do not
+  // pass is kept rather than dropped.
+  const existing = skillExists ? readStoredManagedSkill(params.id) : null;
+
   // Resolve and validate every companion path before any write so an invalid
   // path leaves no partial files behind.
   const companionWrites: Array<{ resolvedPath: string; content: string }> = [];
@@ -413,6 +475,7 @@ export function createManagedSkill(
     activationHints: params.activationHints,
     avoidWhen: params.avoidWhen,
     category: params.category,
+    preserve: existing?.frontmatter,
   });
 
   mkdirSync(skillDir, { recursive: true });
@@ -461,11 +524,13 @@ export function createManagedSkill(
  * `{workspaceDir}` and strips feature-gated sections, and a caller that wrote
  * that output back would bake absolute paths into the skill; and a first line
  * that opens an indented code block must keep its indentation or a copy turns
- * it into prose.
+ * it into prose. `frontmatter` is the whole block as written, for an
+ * overwrite to carry keys through that the typed fields do not cover.
  */
 export interface StoredManagedSkill {
   name: string;
   description: string;
+  frontmatter: Record<string, unknown>;
   emoji?: string;
   includes?: string[];
   activationHints?: string[];
@@ -493,6 +558,7 @@ export function readStoredManagedSkill(
     return {
       name: parsed.name,
       description: parsed.description,
+      frontmatter: raw.fields,
       emoji: parsed.emoji,
       includes: parsed.includes,
       activationHints: parsed.activationHints,

package/src/tools/skills/find-similar-skills.test.ts

@@ -257,6 +257,7 @@ describe("find_similar_skills: current skill for a refinable hit", () => {
     "weekly-export": {
       name: "Weekly Report Export",
       description: "Export the weekly usage report",
+      frontmatter: {},
       emoji: "📊",
       category: "productivity",
       includes: ["csv-basics"],
@@ -267,11 +268,13 @@ describe("find_similar_skills: current skill for a refinable hit", () => {
     "user-skill": {
       name: "User Skill",
       description: "A person wrote this",
+      frontmatter: {},
       body: "Do the user's thing.",
     },
     "clean-disk": {
       name: "Clean Disk",
       description: "Free up disk space",
+      frontmatter: {},
       body: "Delete caches.",
     },
   };

package/src/tools/skills/resolve-execute-invocation.ts

@@ -0,0 +1,24 @@
+import { getTool } from "../registry.js";
+import { resolveToolInvocationAlias } from "../tool-name-aliases.js";
+import {
+  recoverSkillExecuteEnvelope,
+  resolveSkillExecuteInput,
+} from "./execute.js";
+
+export function resolveSkillExecuteInvocation(
+  input: Record<string, unknown>,
+  allowedToolNames?: ReadonlySet<string>,
+): { name: string; input: Record<string, unknown> } {
+  const envelope = recoverSkillExecuteEnvelope(input);
+  const rawToolName = typeof envelope.tool === "string" ? envelope.tool : "";
+  const innerSchema = rawToolName
+    ? getTool(rawToolName)?.input_schema
+    : undefined;
+  const rawToolInput = resolveSkillExecuteInput(envelope, innerSchema);
+
+  return resolveToolInvocationAlias(
+    rawToolName,
+    { ...rawToolInput },
+    allowedToolNames,
+  );
+}