feat(core): add skill resource catalog + SkillManifest schemas

SkillMetadata + SkillManifest zod schemas alongside the existing
task/prompt ones. registerSkillMetadata / listSkillManifests /
getSkillManifest on ResourceCatalog (both Standard and Noop), wired
through the ResourceCatalogAPI facade. BuildManifest + WorkerManifest
gain an optional `skills` array so the built-in CLI bundler can
annotate discoveries and the indexer can report them.

Part 1/3 of Phase 1 for the new ai.skills primitive.

Author: ericallam

packages/core/src/v3/resource-catalog/catalog.ts

@@ -1,4 +1,11 @@
-import { PromptManifest, QueueManifest, TaskManifest, WorkerManifest } from "../schemas/index.js";
+import {
+  PromptManifest,
+  QueueManifest,
+  SkillManifest,
+  SkillMetadata,
+  TaskManifest,
+  WorkerManifest,
+} from "../schemas/index.js";
 import { PromptMetadataWithFunctions, TaskMetadataWithFunctions, TaskSchema } from "../types/index.js";
 
 export interface ResourceCatalog {
@@ -18,4 +25,7 @@ export interface ResourceCatalog {
   listPromptManifests(): Array<PromptManifest>;
   getPrompt(id: string): PromptMetadataWithFunctions | undefined;
   getPromptSchema(id: string): TaskSchema | undefined;
+  registerSkillMetadata(skill: SkillMetadata): void;
+  listSkillManifests(): Array<SkillManifest>;
+  getSkillManifest(id: string): SkillManifest | undefined;
 }

packages/core/src/v3/resource-catalog/index.ts

@@ -1,6 +1,13 @@
 const API_NAME = "resource-catalog";
 
-import { PromptManifest, QueueManifest, TaskManifest, WorkerManifest } from "../schemas/index.js";
+import {
+  PromptManifest,
+  QueueManifest,
+  SkillManifest,
+  SkillMetadata,
+  TaskManifest,
+  WorkerManifest,
+} from "../schemas/index.js";
 import { PromptMetadataWithFunctions, TaskMetadataWithFunctions, TaskSchema } from "../types/index.js";
 import { getGlobal, registerGlobal, unregisterGlobal } from "../utils/globals.js";
 import { type ResourceCatalog } from "./catalog.js";
@@ -93,6 +100,18 @@ export class ResourceCatalogAPI {
     return this.#getCatalog().getPromptSchema(id);
   }
 
+  public registerSkillMetadata(skill: SkillMetadata): void {
+    this.#getCatalog().registerSkillMetadata(skill);
+  }
+
+  public listSkillManifests(): Array<SkillManifest> {
+    return this.#getCatalog().listSkillManifests();
+  }
+
+  public getSkillManifest(id: string): SkillManifest | undefined {
+    return this.#getCatalog().getSkillManifest(id);
+  }
+
   #getCatalog(): ResourceCatalog {
     return getGlobal(API_NAME) ?? NOOP_RESOURCE_CATALOG;
   }

packages/core/src/v3/resource-catalog/noopResourceCatalog.ts

@@ -1,4 +1,11 @@
-import { PromptManifest, QueueManifest, TaskManifest, WorkerManifest } from "../schemas/index.js";
+import {
+  PromptManifest,
+  QueueManifest,
+  SkillManifest,
+  SkillMetadata,
+  TaskManifest,
+  WorkerManifest,
+} from "../schemas/index.js";
 import { type PromptMetadataWithFunctions, type TaskMetadataWithFunctions, type TaskSchema } from "../types/index.js";
 import { ResourceCatalog } from "./catalog.js";
 
@@ -70,4 +77,16 @@ export class NoopResourceCatalog implements ResourceCatalog {
   getPromptSchema(id: string): TaskSchema | undefined {
     return undefined;
   }
+
+  registerSkillMetadata(skill: SkillMetadata): void {
+    // noop
+  }
+
+  listSkillManifests(): Array<SkillManifest> {
+    return [];
+  }
+
+  getSkillManifest(id: string): SkillManifest | undefined {
+    return undefined;
+  }
 }

packages/core/src/v3/resource-catalog/standardResourceCatalog.ts

@@ -1,6 +1,8 @@
 import {
   PromptManifest,
   PromptMetadata,
+  SkillManifest,
+  SkillMetadata,
   TaskFileMetadata,
   TaskMetadata,
   TaskManifest,
@@ -21,6 +23,8 @@ export class StandardResourceCatalog implements ResourceCatalog {
   private _promptSchemas: Map<string, TaskSchema> = new Map();
   private _currentFileContext?: Omit<TaskFileMetadata, "exportName">;
   private _queueMetadata: Map<string, QueueManifest> = new Map();
+  private _skillMetadata: Map<string, SkillMetadata> = new Map();
+  private _skillFileMetadata: Map<string, TaskFileMetadata> = new Map();
 
   setCurrentFileContext(filePath: string, entryPoint: string) {
     this._currentFileContext = { filePath, entryPoint };
@@ -239,6 +243,58 @@ export class StandardResourceCatalog implements ResourceCatalog {
     };
   }
 
+  registerSkillMetadata(skill: SkillMetadata): void {
+    if (!this._currentFileContext) {
+      return;
+    }
+
+    if (!skill.id) {
+      return;
+    }
+
+    const existing = this._skillMetadata.get(skill.id);
+    if (existing && existing.sourcePath !== skill.sourcePath) {
+      console.warn(
+        `Skill "${skill.id}" is defined twice with different paths. Keeping the first:\n` +
+          `  existing: ${existing.sourcePath}\n` +
+          `  ignored:  ${skill.sourcePath}`
+      );
+      return;
+    }
+
+    this._skillFileMetadata.set(skill.id, {
+      ...this._currentFileContext,
+    });
+    this._skillMetadata.set(skill.id, skill);
+  }
+
+  listSkillManifests(): Array<SkillManifest> {
+    const result: Array<SkillManifest> = [];
+
+    for (const [id, metadata] of this._skillMetadata) {
+      const fileMetadata = this._skillFileMetadata.get(id);
+      if (!fileMetadata) continue;
+
+      result.push({
+        ...metadata,
+        ...fileMetadata,
+      });
+    }
+
+    return result;
+  }
+
+  getSkillManifest(id: string): SkillManifest | undefined {
+    const metadata = this._skillMetadata.get(id);
+    const fileMetadata = this._skillFileMetadata.get(id);
+    if (!metadata || !fileMetadata) return undefined;
+
+    return {
+      ...metadata,
+      ...fileMetadata,
+    };
+  }
+
   disable() {
     // noop
   }

packages/core/src/v3/schemas/build.ts

@@ -1,6 +1,12 @@
 import { z } from "zod";
 import { ConfigManifest } from "./config.js";
-import { PromptManifest, QueueManifest, TaskFile, TaskManifest } from "./schemas.js";
+import {
+  PromptManifest,
+  QueueManifest,
+  SkillManifest,
+  TaskFile,
+  TaskManifest,
+} from "./schemas.js";
 
 export const BuildExternal = z.object({
   name: z.string(),
@@ -70,6 +76,8 @@ export const BuildManifest = z.object({
     .optional(),
   /** Maps output file paths to their content hashes for deduplication during dev */
   outputHashes: z.record(z.string()).optional(),
+  /** Skills discovered and bundled into `.trigger/skills/{id}/` under `outputPath`. */
+  skills: SkillManifest.array().optional(),
 });
 
 export type BuildManifest = z.infer<typeof BuildManifest>;
@@ -87,6 +95,7 @@ export const WorkerManifest = z.object({
   configPath: z.string(),
   tasks: TaskManifest.array(),
   prompts: PromptManifest.array().optional(),
+  skills: SkillManifest.array().optional(),
   queues: QueueManifest.array().optional(),
   workerEntryPoint: z.string(),
   controllerEntryPoint: z.string().optional(),

packages/core/src/v3/schemas/schemas.ts

@@ -246,6 +246,28 @@ export const PromptManifest = z.object({
 
 export type PromptManifest = z.infer<typeof PromptManifest>;
 
+// ── Skills ────────────────────────────────────────────────────────────────
+//
+// A skill is a developer-authored folder (SKILL.md + scripts/references/assets)
+// bundled into the deploy image. SkillMetadata is registered at module load
+// by `ai.defineSkill({ id, path })`; the CLI's built-in bundler picks it up
+// during deploy and copies the folder into the deploy image.
+
+const skillMetadata = {
+  id: z.string(),
+  /** Path to the skill's source folder, relative to the project root. */
+  sourcePath: z.string(),
+};
+
+export const SkillMetadata = z.object(skillMetadata);
+export type SkillMetadata = z.infer<typeof SkillMetadata>;
+
+export const SkillManifest = z.object({
+  ...skillMetadata,
+  ...taskFileMetadata,
+});
+export type SkillManifest = z.infer<typeof SkillManifest>;
+
 export const PostStartCauses = z.enum(["index", "create", "restore"]);
 export type PostStartCauses = z.infer<typeof PostStartCauses>;
 

packages/core/test/skillCatalog.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it, vi } from "vitest";
+import { StandardResourceCatalog } from "../src/v3/resource-catalog/standardResourceCatalog.js";
+
+describe("StandardResourceCatalog — skills", () => {
+  it("registers and lists a skill manifest", () => {
+    const catalog = new StandardResourceCatalog();
+    catalog.setCurrentFileContext("trigger/chat.ts", "chat");
+
+    catalog.registerSkillMetadata({ id: "pdf-processing", sourcePath: "./skills/pdf-processing" });
+
+    const manifests = catalog.listSkillManifests();
+    expect(manifests).toHaveLength(1);
+    expect(manifests[0]).toMatchObject({
+      id: "pdf-processing",
+      sourcePath: "./skills/pdf-processing",
+      filePath: "trigger/chat.ts",
+      entryPoint: "chat",
+    });
+  });
+
+  it("getSkillManifest returns the registered skill", () => {
+    const catalog = new StandardResourceCatalog();
+    catalog.setCurrentFileContext("trigger/chat.ts", "chat");
+    catalog.registerSkillMetadata({ id: "a", sourcePath: "./skills/a" });
+
+    expect(catalog.getSkillManifest("a")?.sourcePath).toBe("./skills/a");
+    expect(catalog.getSkillManifest("missing")).toBeUndefined();
+  });
+
+  it("skips registration without a file context", () => {
+    const catalog = new StandardResourceCatalog();
+
+    catalog.registerSkillMetadata({ id: "pdf", sourcePath: "./skills/pdf" });
+
+    expect(catalog.listSkillManifests()).toHaveLength(0);
+  });
+
+  it("warns and ignores when the same id is registered with a different path", () => {
+    const catalog = new StandardResourceCatalog();
+    catalog.setCurrentFileContext("trigger/chat.ts", "chat");
+
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    catalog.registerSkillMetadata({ id: "pdf", sourcePath: "./skills/pdf" });
+    catalog.registerSkillMetadata({ id: "pdf", sourcePath: "./skills/other-pdf" });
+
+    const manifests = catalog.listSkillManifests();
+    expect(manifests).toHaveLength(1);
+    expect(manifests[0]?.sourcePath).toBe("./skills/pdf");
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining("defined twice"));
+
+    warn.mockRestore();
+  });
+
+  it("re-registering the same id + path is idempotent", () => {
+    const catalog = new StandardResourceCatalog();
+    catalog.setCurrentFileContext("trigger/chat.ts", "chat");
+
+    catalog.registerSkillMetadata({ id: "pdf", sourcePath: "./skills/pdf" });
+    catalog.registerSkillMetadata({ id: "pdf", sourcePath: "./skills/pdf" });
+
+    expect(catalog.listSkillManifests()).toHaveLength(1);
+  });
+
+  it("registers multiple distinct skills", () => {
+    const catalog = new StandardResourceCatalog();
+    catalog.setCurrentFileContext("trigger/chat.ts", "chat");
+
+    catalog.registerSkillMetadata({ id: "pdf", sourcePath: "./skills/pdf" });
+    catalog.registerSkillMetadata({ id: "researcher", sourcePath: "./skills/researcher" });
+
+    expect(catalog.listSkillManifests().map((s) => s.id).sort()).toEqual(["pdf", "researcher"]);
+  });
+});