@dbx-tools/appkit-mastra 0.9.120 → 0.9.122

package/package.json

@@ -19,6 +19,7 @@
     "projen": "projen"
   },
   "devDependencies": {
+    "@mastra/isolated-vm": "0.1.2",
     "@mlflow/core": "0.4.0",
     "@types/express": "^5.0.5",
     "@types/json-schema": "^7",
@@ -34,26 +35,25 @@
   },
   "dependencies": {
     "@databricks/appkit": "0.81.0",
-    "@dbx-tools/appkit": "^0.9.120",
-    "@dbx-tools/cache": "^0.9.120",
-    "@dbx-tools/core": "^0.9.120",
-    "@dbx-tools/databricks": "^0.9.120",
-    "@dbx-tools/fs": "^0.9.120",
-    "@dbx-tools/genie": "^0.9.120",
-    "@dbx-tools/model": "^0.9.120",
-    "@dbx-tools/model-protocol": "^0.9.120",
-    "@dbx-tools/path": "^0.9.120",
-    "@dbx-tools/postgres": "^0.9.120",
-    "@dbx-tools/shared-core": "^0.9.120",
-    "@dbx-tools/shared-fs": "^0.9.120",
-    "@dbx-tools/shared-genie": "^0.9.120",
-    "@dbx-tools/shared-mastra": "^0.9.120",
-    "@dbx-tools/shared-model": "^0.9.120",
+    "@dbx-tools/appkit": "^0.9.122",
+    "@dbx-tools/cache": "^0.9.122",
+    "@dbx-tools/core": "^0.9.122",
+    "@dbx-tools/databricks": "^0.9.122",
+    "@dbx-tools/fs": "^0.9.122",
+    "@dbx-tools/genie": "^0.9.122",
+    "@dbx-tools/model": "^0.9.122",
+    "@dbx-tools/model-protocol": "^0.9.122",
+    "@dbx-tools/path": "^0.9.122",
+    "@dbx-tools/postgres": "^0.9.122",
+    "@dbx-tools/shared-core": "^0.9.122",
+    "@dbx-tools/shared-fs": "^0.9.122",
+    "@dbx-tools/shared-genie": "^0.9.122",
+    "@dbx-tools/shared-mastra": "^0.9.122",
+    "@dbx-tools/shared-model": "^0.9.122",
     "@mastra/ai-sdk": "1.10.5",
     "@mastra/core": "1.71.0",
     "@mastra/express": "1.5.15",
     "@mastra/fastembed": "1.3.2",
-    "@mastra/isolated-vm": "0.1.2",
     "@mastra/mcp": "2.1.0",
     "@mastra/memory": "1.32.1",
     "@mastra/observability": "1.18.1",
@@ -219,7 +219,7 @@
       "./package.json": "./package.json"
     }
   },
-  "version": "0.9.120",
+  "version": "0.9.122",
   "types": "./lib/index.d.ts",
   "dbxToolsConfig": {
     "tags": [
@@ -372,6 +372,9 @@
     "exports.ts",
     "lib"
   ],
+  "optionalDependencies": {
+    "@mastra/isolated-vm": "0.1.2"
+  },
   "peerDependenciesMeta": {
     "skills": {
       "optional": true

package/src/agents.ts

@@ -39,10 +39,11 @@ import { SkillSearchProcessor, ToolCallFilter } from "@mastra/core/processors";
 import type { OutputProcessor } from "@mastra/core/processors";
 import { MASTRA_RESOURCE_ID_KEY } from "@mastra/core/request-context";
 import type { RequestContext } from "@mastra/core/request-context";
+import { resolveAgentSkills, type InlineSkill } from "@mastra/core/skills";
 import type { CodeModeTransport, Tool } from "@mastra/core/tools";
 import { createCodeMode, createTool } from "@mastra/core/tools";
 import type { Workspace } from "@mastra/core/workspace";
-import { createWorkspaceTools } from "@mastra/core/workspace";
+import { createSkillTools, createWorkspaceTools } from "@mastra/core/workspace";
 import type { PgVectorConfig, PostgresStoreConfig } from "@mastra/pg";
 import { QuickJsCodeModeTransport } from "@mastra/quickjs";
 
@@ -706,13 +707,24 @@ export async function buildAgents(opts: {
   memoryBuilder?: MemoryBuilder;
   log: log.Logger;
   /**
-   * Local skill scan paths (remote skills provisioned to a temp dir at
-   * startup) folded into every agent that uses the auto-created default
-   * workspace.
+   * Local skill filesystems mounted into every auto-created default workspace.
+   * Skill activation comes from {@link standardSkills}, not workspace search.
    */
   extraSkillMounts?: DatabricksWorkspaceOptions["extraSkillMounts"];
+  /** Fast in-memory skills passed through Mastra's standard agent skill tools. */
+  standardSkills?: readonly InlineSkill[];
+  /** Standard skill names omitted from slower Databricks workspace search. */
+  excludedWorkspaceSkillNames?: readonly string[];
 }): Promise<BuiltAgents> {
-  const { config, context, memoryBuilder, log, extraSkillMounts } = opts;
+  const {
+    config,
+    context,
+    memoryBuilder,
+    log,
+    extraSkillMounts,
+    standardSkills = [],
+    excludedWorkspaceSkillNames = [],
+  } = opts;
   const definitions = resolveDefinitions(config);
   const ids = Object.keys(definitions);
   const defaultAgentId = config.defaultAgent ?? ids[0] ?? FALLBACK_AGENT_ID;
@@ -723,13 +735,16 @@ export async function buildAgents(opts: {
   // offloading text condensing to the fast / small chat tier. The
   // user can shadow either by including a same-named tool in their own
   // `config.tools` or per-agent `tools`. Merge order is
-  // `system -> user-ambient -> per-agent`, last write wins.
+  // `system -> standard skills -> user-ambient -> per-agent`, last write wins.
   const systemTools: MastraTools = {
     render_data: buildRenderDataTool(config),
     summarize: buildSummarizeTool(config),
   };
+  const standardSkillTools =
+    standardSkills.length > 0 ? createSkillTools(resolveAgentSkills([...standardSkills])) : {};
   const ambientTools = {
     ...systemTools,
+    ...standardSkillTools,
     ...(config.tools ?? {}),
   };
   const style = resolveStyleInstructions(config);
@@ -764,6 +779,7 @@ export async function buildAgents(opts: {
     ) {
       workspace = databricksWorkspace({
         extraSkillMounts,
+        excludeSkillNames: excludedWorkspaceSkillNames,
         fallbackToTmp: config.workspaceFallbackToTmp,
         ...(config.workspaceTools !== undefined ? { tools: config.workspaceTools } : {}),
         pluginContext: context,
@@ -771,7 +787,7 @@ export async function buildAgents(opts: {
       });
       markDefaultWorkspace(workspace);
     } else if (workspace) {
-      workspace = bindDatabricksWorkspaceContext(workspace, context);
+      workspace = bindDatabricksWorkspaceContext(workspace, context, excludedWorkspaceSkillNames);
     }
     const gated = approvalGatedToolIds(tools);
     if (gated.length > 0) approvalGatedByAgent.push({ agentId: id, toolIds: gated });
@@ -1249,7 +1265,7 @@ function toolkitEntryToMastraTool(entry: ToolkitEntry, plugin: ContextualToolPro
             abortSignal?: AbortSignal;
             requestContext?: { get(key: string): unknown };
             writer?: {
-              custom(part: { type: string; data: unknown }): Promise<void>;
+              custom(part: { type: string; data: unknown; transient?: boolean }): Promise<void>;
             };
           }
         | undefined;
@@ -1262,12 +1278,13 @@ function toolkitEntryToMastraTool(entry: ToolkitEntry, plugin: ContextualToolPro
         ...(typeof model === "string" ? { model } : {}),
         ...(writer && toolCallId
           ? {
-              writeProgress: async (event: unknown) => {
+              writeProgress: async (event, options) => {
                 const parsed = ToolProgressEventSchema.parse(event);
                 await writer
                   .custom({
                     type: TOOL_PROGRESS_PART_TYPE,
                     data: { toolCallId, event: parsed },
+                    ...(options?.transient ? { transient: true } : {}),
                   })
                   .catch(() => undefined);
               },

package/src/config.ts

@@ -658,7 +658,7 @@ export interface MastraPluginConfig extends BasePluginConfig {
    * ```
    */
   remoteSkills?: RemoteSkillsOption;
-  /** Read-only local skill trees mounted into every default agent workspace. */
+  /** Read-only local skill trees mounted for files and passed as standard agent-level skills. */
   localSkillMounts?: LocalSkillMount[];
 }
 
@@ -686,7 +686,7 @@ export const MASTRA_CONFIG_SCHEMA: ConfigSchema = {
     remoteSkills: {
       type: ["string", "array", "object"],
       description:
-        'Remote Agent-Skill sources provisioned at startup: "aitools" for Databricks\' own skill set (daily @dbx-tools/cache snapshot served from the shared in-memory /.databricks/skills mount), a GitHub owner/repo, a git/GitLab URL, or a direct SKILL.md/archive URL. Non-aitools sources prefer the optional `skills` npm CLI, else a direct fetch; fails startup on error unless failOnError:false. Other sources write to the Databricks user Assistant skills folder or a read-only local-memory fallback.',
+        'Remote Agent-Skill sources provisioned at startup and passed through Mastra standard agent-level skill tools: "aitools" for Databricks\' own skill set, a GitHub owner/repo, a git/GitLab URL, or a direct SKILL.md/archive URL. Sources retain a process-memory copy even when persisted to the Databricks user Assistant skills folder.',
     },
     storage: {
       type: ["boolean", "object"],

package/src/mlflow.ts

@@ -27,7 +27,7 @@
 
 import { ConfigurationError, createWorkspaceClient } from "@databricks/appkit";
 import { appkit } from "@dbx-tools/appkit";
-import { asyncUtils, errorUtils, log, object } from "@dbx-tools/shared-core";
+import { asyncUtils, environmentUtils, errorUtils, log, object } from "@dbx-tools/shared-core";
 import { feedback } from "@dbx-tools/shared-mastra";
 import { TraceLocationType, TraceMetadataKey } from "@mlflow/core";
 import { TraceInfo } from "@mlflow/core/dist/core/entities/trace_info.js";
@@ -298,7 +298,7 @@ function configuredExperiment(): { id?: string; name?: string } {
 
 /** Tracking URI for direct local MLflow tracing, with CLI-profile auth injected. */
 export function directMlflowTrackingUri(): string | undefined {
-  if (appkit.isDatabricksAppEnv()) return undefined;
+  if (environmentUtils.isDatabricksAppEnv()) return undefined;
   const configured = process.env.MLFLOW_TRACKING_URI?.trim();
   if (configured && configured !== "databricks") return configured;
   const profile = process.env.DATABRICKS_CONFIG_PROFILE?.trim();
@@ -331,7 +331,7 @@ export function directMlflowTraceLocation():
 /** Whether the local direct-to-experiment MLflow SDK has enough configuration. */
 export function directMlflowTracingConfigured(): boolean {
   return Boolean(
-    !appkit.isDatabricksAppEnv() &&
+    !environmentUtils.isDatabricksAppEnv() &&
     process.env.MLFLOW_EXPERIMENT_ID?.trim() &&
     directMlflowTrackingUri(),
   );
@@ -340,7 +340,7 @@ export function directMlflowTracingConfigured(): boolean {
 /** Whether a Databricks App can promote OTLP spans into full MLflow trace info. */
 export function appMlflowTraceInfoConfigured(): boolean {
   return Boolean(
-    appkit.isDatabricksAppEnv() &&
+    environmentUtils.isDatabricksAppEnv() &&
     (process.env.MLFLOW_EXPERIMENT_ID?.trim() || process.env.MLFLOW_EXPERIMENT_NAME?.trim()) &&
     (process.env.OTEL_EXPORTER_OTLP_ENDPOINT?.trim() ||
       process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT?.trim()),

package/src/plugin.ts

@@ -120,6 +120,7 @@ import { resolveServingConfig } from "./serving.ts";
 import { fetchStatementData, STATEMENT_ROW_CAP } from "./statement.ts";
 import { attachChatTurnTelemetry } from "./telemetry.ts";
 import { invalidFields } from "./validation.ts";
+import { inlineSkillsFromLocalMounts } from "./workspaces.ts";
 
 const GENIE_MANIFEST = pluginRegistry.data(genie).plugin.manifest;
 const LAKEBASE_MANIFEST = pluginRegistry.data(lakebase).plugin.manifest;
@@ -1055,23 +1056,34 @@ export class MastraPlugin extends Plugin<MastraPluginConfig> {
     // Materialize any remote Agent-Skill sources ONCE at startup. Runs
     // outside a request scope, so it uses the app service principal's client
     // and defaults to the shared workspace Assistant skills tree; a source
-    // backed by local temp storage (no writable workspace) is folded into
-    // every default-workspace agent via `extraSkillMounts`.
+    // backed by local or memory storage is converted into native agent-level
+    // skills; Databricks workspace directories remain search-discovered.
     const provisioned = await provisionRemoteSkills(this.config.remoteSkills);
     if (provisioned.skillNames.length > 0) {
       this.logger.info("remote skills configured", {
         skills: provisioned.skillNames,
         databricksBasePath: provisioned.databricksBasePath,
         localSkillMounts: provisioned.localSkillMounts.length,
+        standardSkillMounts: provisioned.standardSkillMounts.length,
       });
     }
 
+    const localSkillMounts = [
+      ...(this.config.localSkillMounts ?? []),
+      ...provisioned.localSkillMounts,
+    ];
+    const standardSkills = await inlineSkillsFromLocalMounts([
+      ...(this.config.localSkillMounts ?? []),
+      ...provisioned.standardSkillMounts,
+    ]);
     this.built = await buildAgents({
       config: this.config,
       context: this.context,
       memoryBuilder,
       log: this.logger,
-      extraSkillMounts: [...(this.config.localSkillMounts ?? []), ...provisioned.localSkillMounts],
+      extraSkillMounts: localSkillMounts,
+      standardSkills,
+      excludedWorkspaceSkillNames: provisioned.skillNames,
     });
 
     // `mastra.server.apiRoutes` is only honored by Mastra's standalone

package/src/remote-skills.ts

@@ -26,11 +26,11 @@
  * source (or the top-level call) sets `failOnError: false`, in which case it is
  * logged and skipped so one bad source never takes the app down.
  *
- * AI Tools uses the shared `@dbx-tools/cache` project cache with a one-day TTL,
- * then hydrates one process-memory filesystem mounted at
- * {@link AITOOLS_SKILLS_MOUNT} for every default workspace. Other sources keep
- * a {@link METADATA_FILE} beside their provisioned tree and default to a
- * seven-day refresh window. Pass `refreshTtlMs: 0` to download on every boot.
+ * AI Tools uses the shared `@dbx-tools/cache` project cache with a one-day TTL.
+ * Every source hydrates a process-memory filesystem that the plugin converts to
+ * native agent-level skills; persisted workspace copies are not used for
+ * runtime discovery. Other sources keep a {@link METADATA_FILE} beside their
+ * provisioned tree and default to a seven-day refresh window.
  *
  * For non-AI-Tools sources, the default destination is the Databricks workspace
  * Assistant skills tree (`/Workspace/.assistant/skills`). Pass `userEmail` or
@@ -253,12 +253,11 @@ export interface ProvisionRemoteSkillsOptions {
 /** What {@link provisionRemoteSkills} resolved. */
 export interface ProvisionedRemoteSkills {
   /**
-   * Extra read-only local or process-memory skill mounts to hand Mastra. AI
-   * Tools always uses process memory; other sources use this fallback when
-   * they could not be written to Databricks. Physical paths remain hidden
-   * behind stable virtual workspace paths.
+   * Extra read-only filesystem mounts retained for direct workspace file access.
    */
   localSkillMounts: LocalSkillMount[];
+  /** Process-memory trees converted into standard agent-level skills. */
+  standardSkillMounts: LocalSkillMount[];
   /** Absolute Databricks destination each source was written to, if any. */
   databricksBasePath?: string;
   /**
@@ -491,7 +490,11 @@ export async function provisionRemoteSkills(
   option: RemoteSkillsOption | undefined,
 ): Promise<ProvisionedRemoteSkills> {
   const options = normalizeRemoteSkillsOption(option);
-  const empty: ProvisionedRemoteSkills = { localSkillMounts: [], skillNames: [] };
+  const empty: ProvisionedRemoteSkills = {
+    localSkillMounts: [],
+    standardSkillMounts: [],
+    skillNames: [],
+  };
   if (!options) return empty;
 
   const failDefault = options.failOnError !== false;
@@ -512,6 +515,7 @@ export async function provisionRemoteSkills(
   const databricksBasePath = destination ? requestedBasePath : undefined;
 
   const localSkillMounts: LocalSkillMount[] = [];
+  const standardSkillMounts: LocalSkillMount[] = [];
   const skillNames: string[] = [];
   let staging: LocalFileSystem | undefined;
 
@@ -526,10 +530,12 @@ export async function provisionRemoteSkills(
         if (isAiToolsSource(sourceOptions.source)) {
           staging ??= await initializedScratch("mastra-remote-skills");
           const tree = await cachedAiToolsTree(sourceOptions, staging.root, options, key);
-          localSkillMounts.push({
+          const mount = {
             filesystem: await memorySkillTree(tree.files, `aitools-${key}`),
             mountPath,
-          });
+          };
+          localSkillMounts.push(mount);
+          standardSkillMounts.push(mount);
           skillNames.push(...tree.record.skills);
           logger.info("remote skill ready", {
             source: sourceOptions.source,
@@ -545,6 +551,15 @@ export async function provisionRemoteSkills(
         const cached = metadata?.sources[key];
         if (cached && isFresh(cached, resolveRefreshTtl(sourceOptions, options))) {
           skillNames.push(...cached.skills);
+          const standardMount = {
+            filesystem: await memorySkillTreeFromFileSystem(
+              cacheFS,
+              cached.skills,
+              `remote-${key}`,
+            ),
+            mountPath,
+          };
+          standardSkillMounts.push(standardMount);
           if (!destination) localSkillMounts.push({ root: cacheFS.root, mountPath });
           logger.info("remote skill ready", {
             source: sourceOptions.source,
@@ -584,6 +599,10 @@ export async function provisionRemoteSkills(
             mountPath,
           });
         }
+        standardSkillMounts.push({
+          filesystem: await memorySkillTree(await serializeSkillDirs(staged), `remote-${key}`),
+          mountPath,
+        });
         skillNames.push(...record.skills);
         logger.info("remote skill installed", {
           source: sourceOptions.source,
@@ -610,7 +629,7 @@ export async function provisionRemoteSkills(
   }
 
   assertUniqueLocalSkillMounts(localSkillMounts);
-  return { localSkillMounts, databricksBasePath, skillNames };
+  return { localSkillMounts, standardSkillMounts, databricksBasePath, skillNames };
 }
 
 async function cachedAiToolsTree(
@@ -685,6 +704,27 @@ async function memorySkillTree(
   return filesystem;
 }
 
+async function memorySkillTreeFromFileSystem(
+  source: FileSystem,
+  skillNames: readonly string[],
+  id: string,
+): Promise<MemoryFileSystem> {
+  await source.init();
+  const files: CachedSkillFile[] = [];
+  for (const skill of skillNames) {
+    for (const entry of await source.readdir(skill, { recursive: true })) {
+      if (entry.type !== "file") continue;
+      const path = posix.join(skill, entry.name);
+      const content = await source.readFile(path);
+      files.push({
+        path,
+        content: Buffer.from(content).toString("base64"),
+      });
+    }
+  }
+  return memorySkillTree(files, id);
+}
+
 /** Fail before workspace composition when two sources claim one virtual mount. */
 function assertUniqueLocalSkillMounts(mounts: readonly LocalSkillMount[]): void {
   const rootsByMount = new Map<string, string>();

package/src/telemetry.ts

@@ -20,9 +20,8 @@
 
 import { StringDecoder } from "node:string_decoder";
 
-import { appkit } from "@dbx-tools/appkit";
 import { getRequestTags } from "@dbx-tools/appkit/request-tags";
-import { json, log, object, stringUtils } from "@dbx-tools/shared-core";
+import { environmentUtils, json, log, object, stringUtils } from "@dbx-tools/shared-core";
 import { feedback, thread } from "@dbx-tools/shared-mastra";
 import { context, createContextKey, SpanKind, trace, type Span } from "@opentelemetry/api";
 import { getRPCMetadata, RPCType } from "@opentelemetry/core";
@@ -488,7 +487,7 @@ export function chatTurnTelemetryMiddleware(
   }
   const traceState: ChatTraceState = { tags: new Map() };
   const traceRequestTime = Date.now();
-  if (!appkit.isDatabricksAppEnv()) {
+  if (!environmentUtils.isDatabricksAppEnv()) {
     setChatTraceTag(traceState, MLFLOW_LOCAL_TAG, true);
   }
   for (const [name, value] of Object.entries(getRequestTags(req))) {

package/src/workspaces.ts

@@ -36,6 +36,7 @@ import {
   MemoryFileSystem,
 } from "@dbx-tools/shared-fs";
 import type { RequestContext } from "@mastra/core/request-context";
+import { createSkill, validateSkillContent, type InlineSkill } from "@mastra/core/skills";
 import {
   Workspace,
   type SkillsResolver,
@@ -208,13 +209,12 @@ export interface DatabricksWorkspaceOptions extends Omit<
   /** Add user-scoped `/tmp` only when no configured Databricks path mounts writable. */
   fallbackToTmp?: boolean;
   /**
-   * Extra LOCAL skill trees mounted read-only for every request's skill
-   * discovery. Used by the plugin to expose remote skills from local backing
-   * storage at stable virtual paths (see `remote-skills.ts`). Databricks-hosted
-   * remote skills need no entry here because the built-in Assistant mount
-   * already scans them.
+   * Extra local skill trees mounted read-only for file access. The plugin also
+   * converts them to native agent-level skills without workspace scanning.
    */
   extraSkillMounts?: LocalSkillMount[];
+  /** Skill names provided directly to agents and excluded from workspace search. */
+  excludeSkillNames?: readonly string[];
 }
 
 /* ------------------------------- defaults ------------------------------- */
@@ -292,7 +292,8 @@ export function databricksWorkspaceConfig(
       retainFilesystemSource ? mountFilesCache : undefined,
       filesystemSourceKey,
     );
-  const hasSkillPaths = paths.some(pathMayProvideSkills) || extraSkillMounts.length > 0;
+  const hasSkillPaths = paths.some(pathMayProvideSkills);
+  const excludedSkillNames = new Set(options.excludeSkillNames ?? []);
   const skills: SkillsResolver =
     options.skills ??
     (async ({ requestContext }) => {
@@ -301,6 +302,7 @@ export function databricksWorkspaceConfig(
       return resolveDistinctSkillPaths(
         await resolveFilesystem(context),
         contribution.skillPaths ?? [],
+        excludedSkillNames,
       );
     });
   const checkSkillFileMtime = options.checkSkillFileMtime ?? false;
@@ -318,6 +320,7 @@ export function databricksWorkspaceConfig(
     checkSkillFileMtime,
     bm25,
     extraSkillMounts: extraSkillMounts.length,
+    excludedSkillNames: excludedSkillNames.size,
     sandbox: sandbox ? sandboxName(options.sandbox) : "disabled",
   });
 
@@ -331,6 +334,7 @@ export function databricksWorkspaceConfig(
     sandbox: _sandbox,
     fallbackToTmp: _fallbackToTmp,
     extraSkillMounts: _extraSkillMounts,
+    excludeSkillNames: _excludeSkillNames,
     ...workspaceOptions
   } = options;
   return {
@@ -366,12 +370,22 @@ export function databricksWorkspace(options: DatabricksWorkspaceOptions = {}): W
 export function bindDatabricksWorkspaceContext(
   workspace: Workspace,
   pluginContext: pluginRegistry.PluginContextLike | undefined,
+  excludeSkillNames: readonly string[] = [],
 ): Workspace {
   const options = databricksWorkspaceOptions.get(workspace);
-  if (!options || options.pluginContext !== undefined || pluginContext === undefined) {
+  if (!options) return workspace;
+  const excluded = [...new Set([...(options.excludeSkillNames ?? []), ...excludeSkillNames])];
+  if (
+    (options.pluginContext !== undefined || pluginContext === undefined) &&
+    excluded.length === (options.excludeSkillNames?.length ?? 0)
+  ) {
     return workspace;
   }
-  return databricksWorkspace({ ...options, pluginContext });
+  return databricksWorkspace({
+    ...options,
+    ...(pluginContext !== undefined ? { pluginContext } : {}),
+    ...(excluded.length > 0 ? { excludeSkillNames: excluded } : {}),
+  });
 }
 
 /**
@@ -806,12 +820,60 @@ function localSkillMountResolvers(mounts: readonly LocalSkillMount[]): Workspace
       const source = await filesystem;
       return {
         mounts: { [mount]: filesystems(source, { readOnly: true }) },
-        skillPaths: [mount],
       };
     };
   });
 }
 
+/** Convert fast local or in-memory skill trees into native agent-level skills. */
+export async function inlineSkillsFromLocalMounts(
+  mounts: readonly LocalSkillMount[],
+): Promise<InlineSkill[]> {
+  const selected = new Map<string, InlineSkill>();
+  for (const mount of mounts) {
+    const filesystem = await inMemorySkillFilesystem(mount);
+    const entries = await filesystem.readdir("/");
+    for (const entry of entries) {
+      if (entry.type !== "directory" || selected.has(entry.name)) continue;
+      const skillPath = entry.name;
+      const skillFile = `${skillPath}/SKILL.md`;
+      if (!(await filesystem.exists(skillFile))) continue;
+      const content = await filesystem.readFile(skillFile, { encoding: "utf8" });
+      const parsed = validateSkillContent({
+        content: String(content),
+        directoryName: entry.name,
+      });
+      if (!parsed.valid || !parsed.metadata || parsed.instructions === undefined) {
+        throw new Error(`Invalid local skill ${entry.name}: ${parsed.errors.join("; ")}`);
+      }
+      const references: Record<string, string> = {};
+      for (const file of await filesystem.readdir(skillPath, { recursive: true })) {
+        if (file.type !== "file" || file.name === "SKILL.md") continue;
+        if (!/\.(md|txt|json|ya?ml|toml|sh|[cm]?[jt]sx?|py)$/i.test(file.name)) continue;
+        references[file.name] = String(
+          await filesystem.readFile(`${skillPath}/${file.name}`, { encoding: "utf8" }),
+        );
+      }
+      const metadata = parsed.metadata;
+      selected.set(
+        entry.name,
+        createSkill({
+          name: String(metadata.name),
+          description: String(metadata.description),
+          instructions: parsed.instructions,
+          ...(typeof metadata.license === "string" ? { license: metadata.license } : {}),
+          ...(metadata.compatibility !== undefined
+            ? { compatibility: metadata.compatibility }
+            : {}),
+          ...(object.isRecord(metadata.metadata) ? { metadata: metadata.metadata } : {}),
+          ...(Object.keys(references).length > 0 ? { references } : {}),
+        }),
+      );
+    }
+  }
+  return [...selected.values()];
+}
+
 function inMemorySkillFilesystem(mount: LocalSkillMount): Promise<FileSystem> {
   const key = "root" in mount ? `root:${mount.root}` : `filesystem:${mount.filesystem.id}`;
   const existing = sharedSkillFilesystems.get(key);
@@ -1062,6 +1124,7 @@ async function resolveWorkspaceFilesystem(
 async function resolveDistinctSkillPaths(
   filesystem: WorkspaceFilesystem,
   paths: readonly string[],
+  excludedSkillNames: ReadonlySet<string>,
 ): Promise<string[]> {
   const selected = new Map<string, string>();
   for (const path of paths) {
@@ -1069,11 +1132,17 @@ async function resolveDistinctSkillPaths(
       const entries = await filesystem.readdir(path);
       if (entries.some((entry) => entry.type === "file" && entry.name === "SKILL.md")) {
         const name = posixPath.basename(path);
-        if (!selected.has(name)) selected.set(name, path);
+        if (!excludedSkillNames.has(name) && !selected.has(name)) selected.set(name, path);
         continue;
       }
       for (const entry of entries) {
-        if (entry.type !== "directory" || selected.has(entry.name)) continue;
+        if (
+          entry.type !== "directory" ||
+          excludedSkillNames.has(entry.name) ||
+          selected.has(entry.name)
+        ) {
+          continue;
+        }
         selected.set(entry.name, posixPath.join(path, entry.name));
       }
     } catch (error) {