zeitlich 0.2.23 → 0.2.25

package/src/adapters/sandbox/bedrock/proxy.ts

@@ -0,0 +1,56 @@
+/**
+ * Workflow-safe proxy for Bedrock sandbox operations.
+ *
+ * Uses longer timeouts than in-memory providers since Bedrock
+ * sandboxes are remote and creation involves provisioning.
+ *
+ * Import this from `zeitlich/adapters/sandbox/bedrock/workflow`
+ * in your Temporal workflow files.
+ *
+ * By default the scope is derived from `workflowInfo().workflowType`,
+ * so activities are automatically namespaced per workflow.
+ *
+ * @example
+ * ```typescript
+ * import { proxyBedrockSandboxOps } from 'zeitlich/adapters/sandbox/bedrock/workflow';
+ *
+ * const sandbox = proxyBedrockSandboxOps();
+ * ```
+ */
+import { proxyActivities, workflowInfo } from "@temporalio/workflow";
+import type { SandboxOps } from "../../../lib/sandbox/types";
+import type { BedrockSandboxCreateOptions } from "./types";
+
+const ADAPTER_PREFIX = "bedrock";
+
+export function proxyBedrockSandboxOps(
+  scope?: string,
+  options?: Parameters<typeof proxyActivities>[0]
+): SandboxOps<BedrockSandboxCreateOptions> {
+  const resolvedScope = scope ?? workflowInfo().workflowType;
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const acts = proxyActivities<Record<string, (...args: any[]) => any>>(
+    options ?? {
+      startToCloseTimeout: "120s",
+      retry: {
+        maximumAttempts: 3,
+        initialInterval: "5s",
+        maximumInterval: "60s",
+        backoffCoefficient: 3,
+      },
+    }
+  );
+
+  const prefix = `${ADAPTER_PREFIX}${resolvedScope.charAt(0).toUpperCase()}${resolvedScope.slice(1)}`;
+  const p = (key: string): string =>
+    `${prefix}${key.charAt(0).toUpperCase()}${key.slice(1)}`;
+
+  return {
+    createSandbox: acts[p("createSandbox")],
+    destroySandbox: acts[p("destroySandbox")],
+    pauseSandbox: acts[p("pauseSandbox")],
+    snapshotSandbox: acts[p("snapshotSandbox")],
+    forkSandbox: acts[p("forkSandbox")],
+  } as SandboxOps<BedrockSandboxCreateOptions>;
+}

package/src/adapters/sandbox/bedrock/types.ts

@@ -0,0 +1,24 @@
+import type { Sandbox, SandboxCreateOptions } from "../../../lib/sandbox/types";
+import type { BedrockSandboxFileSystem } from "./filesystem";
+import type { BedrockAgentCoreClientConfig } from "@aws-sdk/client-bedrock-agentcore";
+
+/**
+ * A Bedrock-backed {@link Sandbox} with its typed filesystem.
+ */
+export type BedrockSandbox = Sandbox & { fs: BedrockSandboxFileSystem };
+
+export interface BedrockSandboxConfig {
+  /** ARN or name of the Code Interpreter resource. */
+  codeInterpreterIdentifier: string;
+  /** AWS SDK client configuration (region, credentials, etc.). */
+  clientConfig?: BedrockAgentCoreClientConfig;
+  /** Default base path for resolving relative filesystem paths. */
+  workspaceBase?: string;
+}
+
+export interface BedrockSandboxCreateOptions extends SandboxCreateOptions {
+  /** Session name (human-readable, does not need to be unique). */
+  name?: string;
+  /** Session timeout in seconds. Default 900 (15 min). Max 28 800 (8 h). */
+  sessionTimeoutSeconds?: number;
+}

package/src/adapters/sandbox/virtual/filesystem.ts

@@ -64,7 +64,7 @@ export class VirtualSandboxFileSystem<
     tree: FileEntry<TMeta>[],
     private resolver: FileResolver<TCtx, TMeta>,
     private ctx: TCtx,
-    workspaceBase = "/"
+    workspaceBase = "/",
   ) {
     this.workspaceBase = normalisePath(workspaceBase);
     this.entries = new Map(
@@ -88,13 +88,15 @@ export class VirtualSandboxFileSystem<
   // --------------------------------------------------------------------------
 
   async readFile(path: string): Promise<string> {
-    const entry = this.entries.get(normalisePath(path, this.workspaceBase));
+    const norm = normalisePath(path, this.workspaceBase);
+    const entry = this.entries.get(norm);
     if (!entry) throw new Error(`ENOENT: no such file: ${path}`);
     return this.resolver.readFile(entry.id, this.ctx, entry.metadata);
   }
 
   async readFileBuffer(path: string): Promise<Uint8Array> {
-    const entry = this.entries.get(normalisePath(path, this.workspaceBase));
+    const norm = normalisePath(path, this.workspaceBase);
+    const entry = this.entries.get(norm);
     if (!entry) throw new Error(`ENOENT: no such file: ${path}`);
     return this.resolver.readFileBuffer(entry.id, this.ctx, entry.metadata);
   }

package/src/adapters/sandbox/virtual/provider.ts

@@ -69,6 +69,15 @@ export class VirtualSandboxProvider<
       workspaceBase,
     );
 
+    if (options.initialFiles) {
+      for (const [path, content] of Object.entries(options.initialFiles)) {
+        await sandbox.fs.writeFile(path, content);
+      }
+      for (const m of sandbox.fs.getMutations()) {
+        if (m.type === "add") fileTree.push(m.entry);
+      }
+    }
+
     return {
       sandbox,
       stateUpdate: {

package/src/adapters/sandbox/virtual/virtual-sandbox.test.ts

@@ -428,6 +428,32 @@ describe("VirtualSandboxProvider", () => {
       "requires resolverContext",
     );
   });
+
+  it("create seeds initialFiles via writeFile into sandbox and fileTree", async () => {
+    const { resolver } = createMockResolver();
+    const provider = new VirtualSandboxProvider(resolver);
+    const { sandbox, stateUpdate } = await provider.create({
+      resolverContext: ctx,
+      initialFiles: {
+        "/skills/my-skill/SKILL.md": "---\nname: my-skill\n---\nDo things.",
+        "/skills/my-skill/references/guide.md": "# Guide\nStep 1...",
+      },
+    });
+
+    expect(await sandbox.fs.readFile("/skills/my-skill/SKILL.md")).toBe(
+      "---\nname: my-skill\n---\nDo things.",
+    );
+    expect(await sandbox.fs.readFile("/skills/my-skill/references/guide.md")).toBe(
+      "# Guide\nStep 1...",
+    );
+    expect(await sandbox.fs.exists("/skills/my-skill")).toBe(true);
+    expect(await sandbox.fs.exists("/skills/my-skill/references")).toBe(true);
+
+    const tree = stateUpdate?.fileTree as FileEntry[];
+    expect(tree.find((e) => e.path === "/skills/my-skill/SKILL.md")).toBeDefined();
+    expect(tree.find((e) => e.path === "/skills/my-skill/references/guide.md")).toBeDefined();
+    expect(stateUpdate).not.toHaveProperty("localFiles");
+  });
 });
 
 // ============================================================================

package/src/index.ts

@@ -51,8 +51,9 @@ export {
 } from "./lib/activity";
 export type { AgentStateContext } from "./lib/activity";
 
-// Sandbox (activity-side: manager)
+// Sandbox (activity-side: manager + Node.js filesystem adapter)
 export { SandboxManager } from "./lib/sandbox/manager";
+export { NodeFsSandboxFileSystem } from "./lib/sandbox/node-fs";
 
 // Tool handlers (activity implementations)
 // Wrap sandbox handlers with withSandbox(manager, handler) at registration time

package/src/lib/lifecycle.ts

@@ -34,7 +34,7 @@ export type SandboxInit =
   | { mode: "new" }
   | { mode: "continue"; sandboxId: string }
   | { mode: "fork"; sandboxId: string }
-  | { mode: "inherit"; sandboxId: string };
+  | { mode: "inherit"; sandboxId: string; stateUpdate?: Record<string, unknown> };
 
 /**
  * What to do with the sandbox when the session exits.

package/src/lib/sandbox/node-fs.ts

@@ -0,0 +1,115 @@
+import { promises as fsp } from "node:fs";
+import { resolve, posix } from "node:path";
+import type { SandboxFileSystem, DirentEntry, FileStat } from "./types";
+
+/**
+ * Thin adapter from Node.js `fs` to {@link SandboxFileSystem}.
+ *
+ * All paths are resolved relative to {@link workspaceBase} using
+ * `node:path.resolve` (OS-native). Useful for loading skills from the
+ * worker's local disk inside a Temporal activity.
+ *
+ * @example
+ * ```typescript
+ * import { NodeFsSandboxFileSystem, FileSystemSkillProvider } from 'zeitlich';
+ *
+ * const fs = new NodeFsSandboxFileSystem('/path/to/skills-root');
+ * const provider = new FileSystemSkillProvider(fs, '/');
+ * const skills = await provider.loadAll();
+ * ```
+ */
+export class NodeFsSandboxFileSystem implements SandboxFileSystem {
+  readonly workspaceBase: string;
+
+  constructor(workspaceBase: string) {
+    this.workspaceBase = workspaceBase;
+  }
+
+  private abs(path: string): string {
+    return resolve(this.workspaceBase, path);
+  }
+
+  async readFile(path: string): Promise<string> {
+    return fsp.readFile(this.abs(path), "utf-8");
+  }
+
+  async readFileBuffer(path: string): Promise<Uint8Array> {
+    return fsp.readFile(this.abs(path));
+  }
+
+  async writeFile(path: string, content: string | Uint8Array): Promise<void> {
+    await fsp.writeFile(this.abs(path), content);
+  }
+
+  async appendFile(path: string, content: string | Uint8Array): Promise<void> {
+    await fsp.appendFile(this.abs(path), content);
+  }
+
+  async exists(path: string): Promise<boolean> {
+    try {
+      await fsp.access(this.abs(path));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async stat(path: string): Promise<FileStat> {
+    const s = await fsp.stat(this.abs(path));
+    return {
+      isFile: s.isFile(),
+      isDirectory: s.isDirectory(),
+      isSymbolicLink: s.isSymbolicLink(),
+      size: s.size,
+      mtime: s.mtime,
+    };
+  }
+
+  async mkdir(
+    path: string,
+    options?: { recursive?: boolean },
+  ): Promise<void> {
+    await fsp.mkdir(this.abs(path), options);
+  }
+
+  async readdir(path: string): Promise<string[]> {
+    return fsp.readdir(this.abs(path));
+  }
+
+  async readdirWithFileTypes(path: string): Promise<DirentEntry[]> {
+    const entries = await fsp.readdir(this.abs(path), { withFileTypes: true });
+    return entries.map((e) => ({
+      name: e.name,
+      isFile: e.isFile(),
+      isDirectory: e.isDirectory(),
+      isSymbolicLink: e.isSymbolicLink(),
+    }));
+  }
+
+  async rm(
+    path: string,
+    options?: { recursive?: boolean; force?: boolean },
+  ): Promise<void> {
+    await fsp.rm(this.abs(path), options);
+  }
+
+  async cp(
+    src: string,
+    dest: string,
+    options?: { recursive?: boolean },
+  ): Promise<void> {
+    await fsp.cp(this.abs(src), this.abs(dest), options);
+  }
+
+  async mv(src: string, dest: string): Promise<void> {
+    await fsp.rename(this.abs(src), this.abs(dest));
+  }
+
+  async readlink(path: string): Promise<string> {
+    return fsp.readlink(this.abs(path));
+  }
+
+  resolvePath(base: string, path: string): string {
+    return posix.resolve(base, path);
+  }
+}

package/src/lib/session/session.integration.test.ts

@@ -829,6 +829,103 @@ describe("createSession integration", () => {
     expect(stateManager.get("customField")).toBe("from-sandbox");
   });
 
+  // --- Skill resourceContents seeded as initialFiles ---
+
+  it("passes skill resourceContents as initialFiles to createSandbox", async () => {
+    const { ops } = createMockThreadOps();
+    let capturedOptions: Record<string, unknown> | undefined;
+
+    const sandboxOps: SandboxOps = {
+      createSandbox: async (options) => {
+        capturedOptions = options as Record<string, unknown>;
+        return { sandboxId: "sb-skill" };
+      },
+      destroySandbox: async () => {},
+      snapshotSandbox: async () => ({
+        sandboxId: "sb-skill",
+        providerId: "test",
+        data: null,
+        createdAt: new Date().toISOString(),
+      }),
+      forkSandbox: async () => "forked-sandbox-id",
+      pauseSandbox: async () => {},
+    };
+
+    const session = await createSession({
+      agentName: "TestAgent",
+      thread: { mode: "new", threadId: "thread-1" },
+      runAgent: createScriptedRunAgent([{ message: "done", toolCalls: [] }]),
+      threadOps: ops,
+      buildContextMessage: () => "go",
+      sandboxOps,
+      skills: [
+        {
+          name: "test-skill",
+          description: "Test",
+          instructions: "Do test",
+          location: "/skills/test-skill",
+          resourceContents: { "references/guide.md": "# Guide content" },
+        },
+      ],
+    });
+
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "test" },
+    });
+
+    await session.runSession({ stateManager });
+
+    expect(capturedOptions).toBeDefined();
+    expect(capturedOptions?.initialFiles).toEqual({
+      "/skills/test-skill/references/guide.md": "# Guide content",
+    });
+  });
+
+  it("does not pass initialFiles when skills have no resourceContents", async () => {
+    const { ops } = createMockThreadOps();
+    let capturedOptions: Record<string, unknown> | undefined;
+
+    const sandboxOps: SandboxOps = {
+      createSandbox: async (options) => {
+        capturedOptions = options as Record<string, unknown>;
+        return { sandboxId: "sb-no-rc" };
+      },
+      destroySandbox: async () => {},
+      snapshotSandbox: async () => ({
+        sandboxId: "sb-no-rc",
+        providerId: "test",
+        data: null,
+        createdAt: new Date().toISOString(),
+      }),
+      forkSandbox: async () => "forked-sandbox-id",
+      pauseSandbox: async () => {},
+    };
+
+    const session = await createSession({
+      agentName: "TestAgent",
+      thread: { mode: "new", threadId: "thread-1" },
+      runAgent: createScriptedRunAgent([{ message: "done", toolCalls: [] }]),
+      threadOps: ops,
+      buildContextMessage: () => "go",
+      sandboxOps,
+      skills: [
+        {
+          name: "test-skill",
+          description: "Test",
+          instructions: "Do test",
+        },
+      ],
+    });
+
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "test" },
+    });
+
+    await session.runSession({ stateManager });
+
+    expect(capturedOptions).toBeUndefined();
+  });
+
   // --- Tool usage tracking from tool results ---
 
   it("accumulates usage from tool call results", async () => {

package/src/lib/session/session.ts

@@ -13,8 +13,28 @@ import type { ParsedToolCallUnion, ToolMap } from "../tool-router/types";
 import { getShortId } from "../thread/id";
 import { buildSubagentRegistration } from "../subagent/register";
 import { buildSkillRegistration } from "../skills/register";
+import type { Skill } from "../skills/types";
 import { uuid4 } from "@temporalio/workflow";
 
+/**
+ * Collects resource file contents from all skills into a flat map
+ * keyed by absolute path (location + relative resource path).
+ * Returns undefined when no skills carry resource contents.
+ */
+function collectSkillFiles(
+  skills: Skill[],
+): Record<string, string> | undefined {
+  let files: Record<string, string> | undefined;
+  for (const skill of skills) {
+    if (!skill.resourceContents || !skill.location) continue;
+    for (const [relPath, content] of Object.entries(skill.resourceContents)) {
+      files ??= {};
+      files[`${skill.location}/${relPath}`] = content;
+    }
+  }
+  return files;
+}
+
 /**
  * Creates an agent session that manages the agent loop: LLM invocation,
  * tool routing, subagent coordination, and lifecycle hooks.
@@ -169,9 +189,15 @@ export async function createSession<T extends ToolMap, M = unknown>({
       const sandboxMode = sandboxInit?.mode;
       let sandboxId: string | undefined;
       let sandboxOwned = false;
+      let sandboxStateUpdate: Record<string, unknown> | undefined;
 
       if (sandboxMode === "inherit") {
-        sandboxId = (sandboxInit as { mode: "inherit"; sandboxId: string }).sandboxId;
+        const inheritInit = sandboxInit as { mode: "inherit"; sandboxId: string; stateUpdate?: Record<string, unknown> };
+        sandboxId = inheritInit.sandboxId;
+        if (inheritInit.stateUpdate) {
+          sandboxStateUpdate = inheritInit.stateUpdate;
+          stateManager.mergeUpdate(inheritInit.stateUpdate as Partial<TState>);
+        }
         if (!sandboxOps) {
           throw ApplicationFailure.create({
             message: "sandboxId provided but no sandboxOps — cannot manage sandbox lifecycle",
@@ -199,10 +225,14 @@ export async function createSession<T extends ToolMap, M = unknown>({
         );
         sandboxOwned = true;
       } else if (sandboxOps) {
-        const result = await sandboxOps.createSandbox();
+        const skillFiles = skills ? collectSkillFiles(skills) : undefined;
+        const result = await sandboxOps.createSandbox(
+          skillFiles ? { initialFiles: skillFiles } : undefined,
+        );
         sandboxId = result.sandboxId;
         sandboxOwned = true;
         if (result.stateUpdate) {
+          sandboxStateUpdate = result.stateUpdate;
           stateManager.mergeUpdate(result.stateUpdate as Partial<TState>);
         }
       }
@@ -293,6 +323,7 @@ export async function createSession<T extends ToolMap, M = unknown>({
             {
               turn: currentTurn,
               ...(sandboxId !== undefined && { sandboxId }),
+              ...(sandboxStateUpdate && { sandboxStateUpdate }),
             }
           );
 

package/src/lib/session/types.ts

@@ -94,7 +94,7 @@ export interface SessionConfig<T extends ToolMap, M = unknown> {
   tools?: T;
   /** Subagent configurations */
   subagents?: SubagentConfig[];
-  /** Skills available to this agent (metadata + instructions, loaded activity-side) */
+  /** Skills available to this agent (metadata + instructions, loaded before session creation) */
   skills?: Skill[];
   /** Session lifecycle hooks */
   hooks?: Hooks<T, ToolCallResultUnion<InferToolResults<T>>>;

package/src/lib/skills/fs-provider.ts

@@ -11,7 +11,11 @@ import { parseSkillFile } from "./parse";
  * ├── code-review/
  * │   └── SKILL.md
  * ├── pdf-processing/
- * │   └── SKILL.md
+ * │   ├── SKILL.md
+ * │   ├── references/
+ * │   │   └── spec-summary.md
+ * │   └── scripts/
+ * │       └── extract.py
  * ```
  *
  * Uses the sandbox filesystem abstraction — works with any backend
@@ -30,7 +34,11 @@ export class FileSystemSkillProvider implements SkillProvider {
     for (const dir of dirs) {
       const raw = await this.fs.readFile(join(this.baseDir, dir, "SKILL.md"));
       const { frontmatter } = parseSkillFile(raw);
-      skills.push(frontmatter);
+      const location = join(this.baseDir, dir);
+      skills.push({
+        ...frontmatter,
+        location,
+      });
     }
 
     return skills;
@@ -48,7 +56,15 @@ export class FileSystemSkillProvider implements SkillProvider {
       );
     }
 
-    return { ...frontmatter, instructions: body };
+    const location = join(this.baseDir, name);
+    const resourcePaths = await this.discoverResources(name);
+    const resourceContents = await this.readResourceContents(location, resourcePaths);
+    return {
+      ...frontmatter,
+      instructions: body,
+      location,
+      ...(resourceContents && { resourceContents }),
+    };
   }
 
   /**
@@ -62,12 +78,57 @@ export class FileSystemSkillProvider implements SkillProvider {
     for (const dir of dirs) {
       const raw = await this.fs.readFile(join(this.baseDir, dir, "SKILL.md"));
       const { frontmatter, body } = parseSkillFile(raw);
-      skills.push({ ...frontmatter, instructions: body });
+      const location = join(this.baseDir, dir);
+      const resourcePaths = await this.discoverResources(dir);
+      const resourceContents = await this.readResourceContents(location, resourcePaths);
+      skills.push({
+        ...frontmatter,
+        instructions: body,
+        location,
+        ...(resourceContents && { resourceContents }),
+      });
     }
 
     return skills;
   }
 
+  /**
+   * Recursively discovers all non-SKILL.md files inside the skill directory
+   * and returns their paths relative to the skill root.
+   */
+  private async discoverResources(skillDir: string): Promise<string[]> {
+    const skillRoot = join(this.baseDir, skillDir);
+    const resources: string[] = [];
+
+    const walk = async (dir: string, prefix: string): Promise<void> => {
+      const entries = await this.fs.readdirWithFileTypes(dir);
+      for (const e of entries) {
+        if (e.name.startsWith(".")) continue;
+        const relPath = prefix ? `${prefix}/${e.name}` : e.name;
+        if (e.isDirectory) {
+          await walk(join(dir, e.name), relPath);
+        } else if (e.isFile && e.name !== "SKILL.md") {
+          resources.push(relPath);
+        }
+      }
+    };
+
+    await walk(skillRoot, "");
+    return resources;
+  }
+
+  private async readResourceContents(
+    location: string,
+    resources: string[],
+  ): Promise<Record<string, string> | undefined> {
+    if (resources.length === 0) return undefined;
+    const contents: Record<string, string> = {};
+    for (const r of resources) {
+      contents[r] = await this.fs.readFile(join(location, r));
+    }
+    return contents;
+  }
+
   private async discoverSkillDirs(): Promise<string[]> {
     const entries = await this.fs.readdirWithFileTypes(this.baseDir);
     const dirs: string[] = [];

package/src/lib/skills/handler.ts

@@ -2,9 +2,51 @@ import type { Skill } from "./types";
 import type { ToolHandlerResponse } from "../tool-router";
 import type { ReadSkillArgs } from "./tool";
 
+/**
+ * Formats the skill activation response with structured wrapping.
+ *
+ * Follows the agentskills.io pattern: the instructions are wrapped in
+ * identifying tags and bundled resources are listed so the agent can
+ * load them on demand via its file-read tool.
+ */
+function formatSkillResponse(skill: Skill): string {
+  const parts: string[] = [];
+
+  parts.push(`<skill_content name="${skill.name}">`);
+  parts.push(skill.instructions);
+
+  if (skill.location) {
+    parts.push(`\nSkill directory: ${skill.location}`);
+    parts.push(
+      "Relative paths in this skill resolve against the skill directory above.",
+    );
+  }
+
+  const resources = skill.resourceContents
+    ? Object.keys(skill.resourceContents)
+    : [];
+  if (resources.length > 0) {
+    parts.push("");
+    parts.push("<skill_resources>");
+    for (const r of resources) {
+      parts.push(`  <file>${r}</file>`);
+    }
+    parts.push("</skill_resources>");
+  }
+
+  parts.push("</skill_content>");
+
+  return parts.join("\n");
+}
+
 /**
  * Creates a ReadSkill handler that looks up skills from an in-memory array.
  * Runs directly in the workflow (like task tools) — no activity needed.
+ *
+ * The response uses structured wrapping per the agentskills.io spec:
+ * instructions are enclosed in `<skill_content>` tags, the skill directory
+ * is included, and bundled resources are listed so the agent can load them
+ * individually via its file-read tool.
  */
 export function createReadSkillHandler(
   skills: Skill[]
@@ -24,7 +66,7 @@ export function createReadSkillHandler(
     }
 
     return {
-      toolResponse: skill.instructions,
+      toolResponse: formatSkillResponse(skill),
       data: null,
     };
   };

package/src/lib/skills/index.ts

@@ -4,4 +4,3 @@ export { createReadSkillTool, READ_SKILL_TOOL_NAME } from "./tool";
 export type { ReadSkillArgs } from "./tool";
 export { createReadSkillHandler } from "./handler";
 export { buildSkillRegistration } from "./register";
-

package/src/lib/skills/register.ts

@@ -1,8 +1,22 @@
 import type { ToolMap } from "../tool-router/types";
-import type { Skill } from "./types";
+import type { Skill, SkillMetadata } from "./types";
 import { createReadSkillTool } from "./tool";
 import { createReadSkillHandler } from "./handler";
 
+/**
+ * Validates that all skill names are unique. Throws immediately if duplicates
+ * are found so misconfiguration is caught at session wiring time.
+ */
+function validateSkillNames(skills: SkillMetadata[]): void {
+  const names = skills.map((s) => s.name);
+  const dupes = names.filter((n, i) => names.indexOf(n) !== i);
+  if (dupes.length > 0) {
+    throw new Error(
+      `Duplicate skill names: ${[...new Set(dupes)].join(", ")}`
+    );
+  }
+}
+
 /**
  * Builds a fully wired tool entry for the ReadSkill tool.
  *
@@ -13,6 +27,8 @@ export function buildSkillRegistration(
 ): ToolMap[string] | null {
   if (skills.length === 0) return null;
 
+  validateSkillNames(skills);
+
   return {
     ...createReadSkillTool(skills),
     handler: createReadSkillHandler(skills),