kraken-ai 0.0.8 → 0.0.9

package/README.md

@@ -50,6 +50,40 @@ if (result.status === "complete") {
 }
 ```
 
+## Adding skills to a kernel
+
+`defineSkillTool` and `skillDiscoveryMessage` give you the [Agent Skills](https://agentskills.io/specification) progressive-disclosure pattern with no framework lock-in. The SDK stays governance-agnostic — you wire the loader to whatever backend fetches the skill body (an in-memory map for tests, a file walker for a CLI, an authenticated service for production).
+
+```ts
+import { Agent, defineSkillTool, skillDiscoveryMessage, openai } from "kraken-ai";
+
+const SKILLS = {
+  "pdf-processing": "# PDF Processing\n\nUse pdfminer.six to extract …",
+  "csv-cleaning": "# CSV Cleaning\n\nNormalize headers via …",
+};
+
+const skillTools = Object.keys(SKILLS).map((id) =>
+  defineSkillTool({
+    skillId: id,
+    description: `Load the ${id} skill body`,
+    load: async (skillId) => SKILLS[skillId as keyof typeof SKILLS],
+  }),
+);
+
+const catalog = skillDiscoveryMessage([
+  { skillId: "pdf-processing", description: "Extract structured data from PDFs" },
+  { skillId: "csv-cleaning", description: "Normalize and dedupe CSVs" },
+]);
+
+const agent = new Agent({
+  model: openai("gpt-4o"),
+  instructions: `You are a data assistant.\n\n${catalog}`,
+  tools: skillTools,
+});
+```
+
+Only the skill names + descriptions are in the system prompt at startup. The full skill body is loaded only when the model decides to call the matching `load_skill_*` tool.
+
 ## Documentation
 
 - [Models](docs/models.md) — providers, lazy resolution, custom providers

package/dist/index.cjs

@@ -318,10 +318,12 @@ __export(index_exports, {
   ValidationError: () => ValidationError,
   configure: () => configure,
   defineKernel: () => defineKernel,
+  defineSkillTool: () => defineSkillTool,
   formatEvent: () => formatEvent,
   google: () => google,
   mock: () => mock,
   openai: () => openai,
+  skillDiscoveryMessage: () => skillDiscoveryMessage,
   tool: () => tool
 });
 module.exports = __toCommonJS(index_exports);
@@ -388,17 +390,12 @@ var z = __toESM(require("zod"), 1);
 var delegationSchema = z.object({
   task: z.string().describe("The task to delegate to this team member")
 });
-var createDelegationTools = (team, propagatedOptions, childRunIds) => team.map((member) => ({
+var createDelegationTools = (team, propagatedOptions) => team.map((member) => ({
   name: `delegate_to_${member.name}`,
   description: member.description ?? `Delegate a task to ${member.name}`,
   execute: async (args) => {
     const { task } = delegationSchema.parse(args);
-    const childRunId = childRunIds?.get(member.name)?.shift();
-    const childOptions = {
-      ...propagatedOptions,
-      ...childRunId ? { runId: childRunId } : {}
-    };
-    const result = await member.run([{ role: "user", content: task }], childOptions);
+    const result = await member.run([{ role: "user", content: task }], propagatedOptions);
     if (result.status === "complete") return result.output;
     throw new Error(`Delegation to ${member.name} was interrupted`);
   },
@@ -710,18 +707,11 @@ var createRunner = (config2) => {
             for (const { tc } of approved) {
               if (tc.name.startsWith("delegate_to_")) {
                 const targetName = tc.name.replace("delegate_to_", "");
-                const childRunId = crypto.randomUUID();
                 emitter.emit({
                   type: "delegation",
-                  childRunId,
+                  childRunId: crypto.randomUUID(),
                   childAgentName: targetName
                 });
-                const queue = options?._childRunIds?.get(targetName);
-                if (queue) {
-                  queue.push(childRunId);
-                } else {
-                  options?._childRunIds?.set(targetName, [childRunId]);
-                }
               }
             }
           }
@@ -909,7 +899,6 @@ var Agent = class {
     }
     const resolvedThinkingLevel = options?.thinkingLevel ?? this.config.thinkingLevel;
     const resolvedMaxOutputTokens = options?.maxOutputTokens ?? this.config.maxOutputTokens;
-    const childRunIds = /* @__PURE__ */ new Map();
     if (this.config.team?.length) {
       const propagated = {
         middleware: options?.middleware,
@@ -920,7 +909,7 @@ var Agent = class {
         ...resolvedThinkingLevel ? { thinkingLevel: resolvedThinkingLevel } : {},
         ...resolvedMaxOutputTokens != null ? { maxOutputTokens: resolvedMaxOutputTokens } : {}
       };
-      const delegationTools = createDelegationTools(this.config.team, propagated, childRunIds);
+      const delegationTools = createDelegationTools(this.config.team, propagated);
       allTools.push(...delegationTools);
     }
     const runner = createRunner({
@@ -937,7 +926,7 @@ var Agent = class {
       responseSchema: this.config.outputSchema ? z2.toJSONSchema(this.config.outputSchema, { target: "draft-2020-12" }) : void 0,
       logLevel: this.config.logLevel
     });
-    const result = await runner.run(messages, { ...options, runId, _childRunIds: childRunIds });
+    const result = await runner.run(messages, { ...options, runId });
     if (result.status === "complete" && this.config.outputSchema) {
       const validated = await this.produceStructuredOutput(result, options);
       options?.onEvent?.({
@@ -1115,6 +1104,9 @@ var mock = (config2) => {
 // src/index.ts
 init_openai();
 
+// src/skills.ts
+var z4 = __toESM(require("zod"), 1);
+
 // src/tool.ts
 var z3 = __toESM(require("zod"), 1);
 init_errors();
@@ -1155,6 +1147,43 @@ Hint: The LLM provided arguments that don't match the tool's parameter schema. T
     }
   };
 };
+
+// src/skills.ts
+var skillContentBlock = (skillId, content) => `<skill_content name="${skillId}">
+${content}
+</skill_content>`;
+var notLoadedMessage = (skillId) => `<skill_load_failed name="${skillId}">no content returned by loader</skill_load_failed>`;
+var defineSkillTool = (config2) => {
+  const toolDescription = config2.description ?? (config2.displayName ? `Load the "${config2.displayName}" skill body.` : `Load the "${config2.skillId}" skill body.`);
+  return tool({
+    name: `load_skill_${config2.skillId.replace(/-/g, "_")}`,
+    description: toolDescription,
+    parameters: z4.object({
+      args: z4.record(z4.string(), z4.unknown()).optional().describe("Optional arguments forwarded to the skill loader.")
+    }),
+    execute: async ({ args }) => {
+      const content = await config2.load(config2.skillId, args);
+      if (content === null || content === void 0) {
+        return notLoadedMessage(config2.skillId);
+      }
+      return skillContentBlock(config2.skillId, content);
+    }
+  });
+};
+var skillDiscoveryMessage = (skills) => {
+  if (skills.length === 0) return "";
+  const blocks = skills.map((s) => {
+    const name = s.displayName ?? s.skillId;
+    return `  <skill id="${s.skillId}" name="${name}">${s.description}</skill>`;
+  });
+  return [
+    "<available_skills>",
+    ...blocks,
+    "</available_skills>",
+    "",
+    "If a skill is relevant to the user's request, call its load tool to retrieve the full skill body before relying on it."
+  ].join("\n");
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Agent,
@@ -1166,9 +1195,11 @@ Hint: The LLM provided arguments that don't match the tool's parameter schema. T
   ValidationError,
   configure,
   defineKernel,
+  defineSkillTool,
   formatEvent,
   google,
   mock,
   openai,
+  skillDiscoveryMessage,
   tool
 });

package/dist/index.d.cts

@@ -389,8 +389,6 @@ interface RunOptions {
     responseSchema?: Record<string, unknown>;
     /** When true, tool calls are logged but not executed. */
     dryRun?: boolean;
-    /** @internal Shared map for pre-generated child runIds during delegation. */
-    _childRunIds?: Map<string, string[]>;
 }
 /** Specification for spawning a sub-agent from a kernel. */
 interface SpawnSpec {
@@ -646,6 +644,74 @@ declare const mock: (config?: MockModelConfig) => MockModel;
  */
 declare const openai: (_modelId: OpenAIModelId) => Model;
 
+/**
+ * Configuration for {@link defineSkillTool}.
+ *
+ * @typeParam TLoadResult - Inferred return type of the `load` callback.
+ *   Whatever the loader returns is wrapped in a `<skill_content>` block
+ *   and returned to the LLM verbatim, so callers can shape the payload
+ *   for their own progressive-disclosure tier.
+ */
+interface SkillToolConfig {
+    /** Stable identifier for the skill — what the LLM passes back via the tool call. */
+    skillId: string;
+    /** Optional display name surfaced in the tool description. */
+    displayName?: string;
+    /** Short description rendered alongside the tool definition. */
+    description?: string;
+    /**
+     * Loader invoked when the LLM activates this skill. Receives the
+     * (already-validated) `skillId` and any opaque `args` the LLM passed.
+     * Returning a string sends it back as `<skill_content>` text; returning
+     * `null` / `undefined` short-circuits with a "not loaded" message.
+     */
+    load: (skillId: string, args?: Record<string, unknown>) => Promise<string | null | undefined>;
+}
+/**
+ * Build a `loadSkill`-style tool for an Agent that defers content fetch
+ * to a caller-provided `load` function. The engine stays governance-
+ * agnostic: production deployments wire `load` to call a governance
+ * gateway; tests can inline an in-memory loader; CLIs can read from disk.
+ *
+ * The returned tool accepts a single `args?: Record<string, unknown>`
+ * parameter — keep it permissive so end-user skills can describe their
+ * own argument shape inside the skill body without re-engineering this
+ * helper.
+ *
+ * @example
+ * ```ts
+ * const skillTool = defineSkillTool({
+ *   skillId: "pdf-processing",
+ *   description: "Loads the PDF processing skill body",
+ *   load: async (id, args) => `# Skill body for ${id}: ${JSON.stringify(args)}`,
+ * });
+ * ```
+ */
+declare const defineSkillTool: (config: SkillToolConfig) => Tool;
+/**
+ * Catalog entry for {@link skillDiscoveryMessage}. Mirrors the Agent
+ * Skills spec's tier-1 metadata shape (~100 tokens per skill) — `name`
+ * + `description` only.
+ */
+interface SkillCatalogEntry {
+    skillId: string;
+    description: string;
+    /** Optional display name; defaults to `skillId` when absent. */
+    displayName?: string;
+}
+/**
+ * Build a system-reminder string listing every available skill so the
+ * LLM can discover what's loadable before deciding to call `loadSkill`.
+ *
+ * Format follows the Agent Skills spec's recommended catalog wrapping —
+ * `<available_skills>` with one `<skill>` block per entry plus an
+ * instruction footer telling the model when to call the loader.
+ *
+ * Returns an empty string when `skills` is empty, so callers can drop
+ * the result into their system prompt unconditionally.
+ */
+declare const skillDiscoveryMessage: (skills: ReadonlyArray<SkillCatalogEntry>) => string;
+
 /**
  * Configuration for creating a tool.
  *
@@ -696,4 +762,4 @@ interface ToolConfig<TParams extends z.ZodType, TReturn = unknown> {
  */
 declare const tool: <TParams extends z.ZodType, TReturn>(config: ToolConfig<TParams, TReturn>) => Tool;
 
-export { Agent, type AgentConfig, type AgentConfigEvent, type AgentDelegationEvent, type AgentErrorEvent, type AgentEvent, type AgentEventBase, type AgentEventPayload, type AgentEventType, type AgentInterruptEvent, type AgentKillEvent, type AgentLLMCallEvent, type AgentLifecycleEvent, type AgentLike, type AgentNotificationEvent, type AgentRef, type AgentState, type AgentStructuredOutputCompleteEvent, type AgentThoughtEvent, type AgentToolCallEvent, type AgentTranscriptInitEvent, type ExecutionContext, type GenerateParams, type GenerateResponse, type GlobalConfig, type GoogleModelConfig, type GoogleModelId, type HumanDecision, type Interrupt, type Kernel, type KernelSignal, KrakenError, type LogLevel, type Message, type Middleware, type MiddlewareContext, type Model, type ModelParams, type ModelString, type OpenAIModelId, OutputValidationError, ProviderError, type RetryConfig, type RunOptions, type RunResult, type RunnerResponse, type SpawnSpec, type StreamChunk, type TeamAccessor, type ThinkingLevel, type Tool, type ToolCall, type ToolConfig, type ToolDefinition, ToolError, ToolInputValidationError, type ToolResult, type TransitionRecord, type Usage, ValidationError, configure, defineKernel, formatEvent, google, mock, openai, tool };
+export { Agent, type AgentConfig, type AgentConfigEvent, type AgentDelegationEvent, type AgentErrorEvent, type AgentEvent, type AgentEventBase, type AgentEventPayload, type AgentEventType, type AgentInterruptEvent, type AgentKillEvent, type AgentLLMCallEvent, type AgentLifecycleEvent, type AgentLike, type AgentNotificationEvent, type AgentRef, type AgentState, type AgentStructuredOutputCompleteEvent, type AgentThoughtEvent, type AgentToolCallEvent, type AgentTranscriptInitEvent, type ExecutionContext, type GenerateParams, type GenerateResponse, type GlobalConfig, type GoogleModelConfig, type GoogleModelId, type HumanDecision, type Interrupt, type Kernel, type KernelSignal, KrakenError, type LogLevel, type Message, type Middleware, type MiddlewareContext, type Model, type ModelParams, type ModelString, type OpenAIModelId, OutputValidationError, ProviderError, type RetryConfig, type RunOptions, type RunResult, type RunnerResponse, type SkillCatalogEntry, type SkillToolConfig, type SpawnSpec, type StreamChunk, type TeamAccessor, type ThinkingLevel, type Tool, type ToolCall, type ToolConfig, type ToolDefinition, ToolError, ToolInputValidationError, type ToolResult, type TransitionRecord, type Usage, ValidationError, configure, defineKernel, defineSkillTool, formatEvent, google, mock, openai, skillDiscoveryMessage, tool };

package/dist/index.d.ts

@@ -389,8 +389,6 @@ interface RunOptions {
     responseSchema?: Record<string, unknown>;
     /** When true, tool calls are logged but not executed. */
     dryRun?: boolean;
-    /** @internal Shared map for pre-generated child runIds during delegation. */
-    _childRunIds?: Map<string, string[]>;
 }
 /** Specification for spawning a sub-agent from a kernel. */
 interface SpawnSpec {
@@ -646,6 +644,74 @@ declare const mock: (config?: MockModelConfig) => MockModel;
  */
 declare const openai: (_modelId: OpenAIModelId) => Model;
 
+/**
+ * Configuration for {@link defineSkillTool}.
+ *
+ * @typeParam TLoadResult - Inferred return type of the `load` callback.
+ *   Whatever the loader returns is wrapped in a `<skill_content>` block
+ *   and returned to the LLM verbatim, so callers can shape the payload
+ *   for their own progressive-disclosure tier.
+ */
+interface SkillToolConfig {
+    /** Stable identifier for the skill — what the LLM passes back via the tool call. */
+    skillId: string;
+    /** Optional display name surfaced in the tool description. */
+    displayName?: string;
+    /** Short description rendered alongside the tool definition. */
+    description?: string;
+    /**
+     * Loader invoked when the LLM activates this skill. Receives the
+     * (already-validated) `skillId` and any opaque `args` the LLM passed.
+     * Returning a string sends it back as `<skill_content>` text; returning
+     * `null` / `undefined` short-circuits with a "not loaded" message.
+     */
+    load: (skillId: string, args?: Record<string, unknown>) => Promise<string | null | undefined>;
+}
+/**
+ * Build a `loadSkill`-style tool for an Agent that defers content fetch
+ * to a caller-provided `load` function. The engine stays governance-
+ * agnostic: production deployments wire `load` to call a governance
+ * gateway; tests can inline an in-memory loader; CLIs can read from disk.
+ *
+ * The returned tool accepts a single `args?: Record<string, unknown>`
+ * parameter — keep it permissive so end-user skills can describe their
+ * own argument shape inside the skill body without re-engineering this
+ * helper.
+ *
+ * @example
+ * ```ts
+ * const skillTool = defineSkillTool({
+ *   skillId: "pdf-processing",
+ *   description: "Loads the PDF processing skill body",
+ *   load: async (id, args) => `# Skill body for ${id}: ${JSON.stringify(args)}`,
+ * });
+ * ```
+ */
+declare const defineSkillTool: (config: SkillToolConfig) => Tool;
+/**
+ * Catalog entry for {@link skillDiscoveryMessage}. Mirrors the Agent
+ * Skills spec's tier-1 metadata shape (~100 tokens per skill) — `name`
+ * + `description` only.
+ */
+interface SkillCatalogEntry {
+    skillId: string;
+    description: string;
+    /** Optional display name; defaults to `skillId` when absent. */
+    displayName?: string;
+}
+/**
+ * Build a system-reminder string listing every available skill so the
+ * LLM can discover what's loadable before deciding to call `loadSkill`.
+ *
+ * Format follows the Agent Skills spec's recommended catalog wrapping —
+ * `<available_skills>` with one `<skill>` block per entry plus an
+ * instruction footer telling the model when to call the loader.
+ *
+ * Returns an empty string when `skills` is empty, so callers can drop
+ * the result into their system prompt unconditionally.
+ */
+declare const skillDiscoveryMessage: (skills: ReadonlyArray<SkillCatalogEntry>) => string;
+
 /**
  * Configuration for creating a tool.
  *
@@ -696,4 +762,4 @@ interface ToolConfig<TParams extends z.ZodType, TReturn = unknown> {
  */
 declare const tool: <TParams extends z.ZodType, TReturn>(config: ToolConfig<TParams, TReturn>) => Tool;
 
-export { Agent, type AgentConfig, type AgentConfigEvent, type AgentDelegationEvent, type AgentErrorEvent, type AgentEvent, type AgentEventBase, type AgentEventPayload, type AgentEventType, type AgentInterruptEvent, type AgentKillEvent, type AgentLLMCallEvent, type AgentLifecycleEvent, type AgentLike, type AgentNotificationEvent, type AgentRef, type AgentState, type AgentStructuredOutputCompleteEvent, type AgentThoughtEvent, type AgentToolCallEvent, type AgentTranscriptInitEvent, type ExecutionContext, type GenerateParams, type GenerateResponse, type GlobalConfig, type GoogleModelConfig, type GoogleModelId, type HumanDecision, type Interrupt, type Kernel, type KernelSignal, KrakenError, type LogLevel, type Message, type Middleware, type MiddlewareContext, type Model, type ModelParams, type ModelString, type OpenAIModelId, OutputValidationError, ProviderError, type RetryConfig, type RunOptions, type RunResult, type RunnerResponse, type SpawnSpec, type StreamChunk, type TeamAccessor, type ThinkingLevel, type Tool, type ToolCall, type ToolConfig, type ToolDefinition, ToolError, ToolInputValidationError, type ToolResult, type TransitionRecord, type Usage, ValidationError, configure, defineKernel, formatEvent, google, mock, openai, tool };
+export { Agent, type AgentConfig, type AgentConfigEvent, type AgentDelegationEvent, type AgentErrorEvent, type AgentEvent, type AgentEventBase, type AgentEventPayload, type AgentEventType, type AgentInterruptEvent, type AgentKillEvent, type AgentLLMCallEvent, type AgentLifecycleEvent, type AgentLike, type AgentNotificationEvent, type AgentRef, type AgentState, type AgentStructuredOutputCompleteEvent, type AgentThoughtEvent, type AgentToolCallEvent, type AgentTranscriptInitEvent, type ExecutionContext, type GenerateParams, type GenerateResponse, type GlobalConfig, type GoogleModelConfig, type GoogleModelId, type HumanDecision, type Interrupt, type Kernel, type KernelSignal, KrakenError, type LogLevel, type Message, type Middleware, type MiddlewareContext, type Model, type ModelParams, type ModelString, type OpenAIModelId, OutputValidationError, ProviderError, type RetryConfig, type RunOptions, type RunResult, type RunnerResponse, type SkillCatalogEntry, type SkillToolConfig, type SpawnSpec, type StreamChunk, type TeamAccessor, type ThinkingLevel, type Tool, type ToolCall, type ToolConfig, type ToolDefinition, ToolError, ToolInputValidationError, type ToolResult, type TransitionRecord, type Usage, ValidationError, configure, defineKernel, defineSkillTool, formatEvent, google, mock, openai, skillDiscoveryMessage, tool };

package/dist/index.js

@@ -73,17 +73,12 @@ import * as z from "zod";
 var delegationSchema = z.object({
   task: z.string().describe("The task to delegate to this team member")
 });
-var createDelegationTools = (team, propagatedOptions, childRunIds) => team.map((member) => ({
+var createDelegationTools = (team, propagatedOptions) => team.map((member) => ({
   name: `delegate_to_${member.name}`,
   description: member.description ?? `Delegate a task to ${member.name}`,
   execute: async (args) => {
     const { task } = delegationSchema.parse(args);
-    const childRunId = childRunIds?.get(member.name)?.shift();
-    const childOptions = {
-      ...propagatedOptions,
-      ...childRunId ? { runId: childRunId } : {}
-    };
-    const result = await member.run([{ role: "user", content: task }], childOptions);
+    const result = await member.run([{ role: "user", content: task }], propagatedOptions);
     if (result.status === "complete") return result.output;
     throw new Error(`Delegation to ${member.name} was interrupted`);
   },
@@ -392,18 +387,11 @@ var createRunner = (config2) => {
             for (const { tc } of approved) {
               if (tc.name.startsWith("delegate_to_")) {
                 const targetName = tc.name.replace("delegate_to_", "");
-                const childRunId = crypto.randomUUID();
                 emitter.emit({
                   type: "delegation",
-                  childRunId,
+                  childRunId: crypto.randomUUID(),
                   childAgentName: targetName
                 });
-                const queue = options?._childRunIds?.get(targetName);
-                if (queue) {
-                  queue.push(childRunId);
-                } else {
-                  options?._childRunIds?.set(targetName, [childRunId]);
-                }
               }
             }
           }
@@ -591,7 +579,6 @@ var Agent = class {
     }
     const resolvedThinkingLevel = options?.thinkingLevel ?? this.config.thinkingLevel;
     const resolvedMaxOutputTokens = options?.maxOutputTokens ?? this.config.maxOutputTokens;
-    const childRunIds = /* @__PURE__ */ new Map();
     if (this.config.team?.length) {
       const propagated = {
         middleware: options?.middleware,
@@ -602,7 +589,7 @@ var Agent = class {
         ...resolvedThinkingLevel ? { thinkingLevel: resolvedThinkingLevel } : {},
         ...resolvedMaxOutputTokens != null ? { maxOutputTokens: resolvedMaxOutputTokens } : {}
       };
-      const delegationTools = createDelegationTools(this.config.team, propagated, childRunIds);
+      const delegationTools = createDelegationTools(this.config.team, propagated);
       allTools.push(...delegationTools);
     }
     const runner = createRunner({
@@ -619,7 +606,7 @@ var Agent = class {
       responseSchema: this.config.outputSchema ? z2.toJSONSchema(this.config.outputSchema, { target: "draft-2020-12" }) : void 0,
       logLevel: this.config.logLevel
     });
-    const result = await runner.run(messages, { ...options, runId, _childRunIds: childRunIds });
+    const result = await runner.run(messages, { ...options, runId });
     if (result.status === "complete" && this.config.outputSchema) {
       const validated = await this.produceStructuredOutput(result, options);
       options?.onEvent?.({
@@ -788,6 +775,9 @@ var mock = (config2) => {
   };
 };
 
+// src/skills.ts
+import * as z4 from "zod";
+
 // src/tool.ts
 import * as z3 from "zod";
 var tool = (config2) => {
@@ -827,6 +817,43 @@ Hint: The LLM provided arguments that don't match the tool's parameter schema. T
     }
   };
 };
+
+// src/skills.ts
+var skillContentBlock = (skillId, content) => `<skill_content name="${skillId}">
+${content}
+</skill_content>`;
+var notLoadedMessage = (skillId) => `<skill_load_failed name="${skillId}">no content returned by loader</skill_load_failed>`;
+var defineSkillTool = (config2) => {
+  const toolDescription = config2.description ?? (config2.displayName ? `Load the "${config2.displayName}" skill body.` : `Load the "${config2.skillId}" skill body.`);
+  return tool({
+    name: `load_skill_${config2.skillId.replace(/-/g, "_")}`,
+    description: toolDescription,
+    parameters: z4.object({
+      args: z4.record(z4.string(), z4.unknown()).optional().describe("Optional arguments forwarded to the skill loader.")
+    }),
+    execute: async ({ args }) => {
+      const content = await config2.load(config2.skillId, args);
+      if (content === null || content === void 0) {
+        return notLoadedMessage(config2.skillId);
+      }
+      return skillContentBlock(config2.skillId, content);
+    }
+  });
+};
+var skillDiscoveryMessage = (skills) => {
+  if (skills.length === 0) return "";
+  const blocks = skills.map((s) => {
+    const name = s.displayName ?? s.skillId;
+    return `  <skill id="${s.skillId}" name="${name}">${s.description}</skill>`;
+  });
+  return [
+    "<available_skills>",
+    ...blocks,
+    "</available_skills>",
+    "",
+    "If a skill is relevant to the user's request, call its load tool to retrieve the full skill body before relying on it."
+  ].join("\n");
+};
 export {
   Agent,
   KrakenError,
@@ -837,9 +864,11 @@ export {
   ValidationError,
   configure,
   defineKernel,
+  defineSkillTool,
   formatEvent,
   google,
   mock,
   openai,
+  skillDiscoveryMessage,
   tool
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kraken-ai",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "Kraken AI SDK: a very lightweight, fully-typed multi-model AI agent framework",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -14,16 +14,16 @@
     }
   },
   "devDependencies": {
-    "@google/genai": "^1.48.0",
-    "@types/node": "^25.5.2",
+    "@google/genai": "^1.50.1",
+    "@types/node": "^25.6.0",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
-    "typescript": "^6.0.2",
-    "vitest": "^4.1.3",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5",
     "zod": "^4.3.6"
   },
   "peerDependencies": {
-    "@google/genai": ">=1.0.0",
+    "@google/genai": "^1.50.1",
     "zod": "^4.0.0"
   },
   "peerDependenciesMeta": {