Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

feat(skills): import skills from local files and ZIPs (#18378)

tobi_klc1726739908c
diff --git a/web/src/features/posthog-analytics/usePostHogClientCapture.ts b/web/src/features/posthog-analytics/usePostHogClientCapture.ts
index 7c94bdd0fd..832cf26e86 100644
--- a/web/src/features/posthog-analytics/usePostHogClientCapture.ts
+++ b/web/src/features/posthog-analytics/usePostHogClientCapture.ts
@@ -165,7 +165,14 @@ const events = {
"bulk_export",
"bulk_import_submit",
],
- skills: ["new_form_open", "version_create", "version_download", "delete"],
+ skills: [
+ "new_form_open",
+ "version_create",
+ "version_download",
+ "delete",
+ "import_open",
+ "import",
+ ],
prompt_detail: [
"test_in_playground_button_click",
"add_label_submit",
diff --git a/web/src/features/skills/components/ImportSkillsDialog.clienttest.tsx b/web/src/features/skills/components/ImportSkillsDialog.clienttest.tsx
new file mode 100644
index 0000000000..f6a209fdd3
--- /dev/null
+++ b/web/src/features/skills/components/ImportSkillsDialog.clienttest.tsx
@@ -0,0 +1,96 @@
+import {
+ cleanup,
+ fireEvent,
+ render,
+ screen,
+ waitFor,
+} from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { ImportSkillsDialog } from "./ImportSkillsDialog";
+
+const { discoverLocalSkills, byName, createVersion } = vi.hoisted(() => ({
+ discoverLocalSkills: vi.fn(),
+ byName: vi.fn(),
+ createVersion: vi.fn(),
+}));
+
+vi.mock("../utils/local-import", () => ({ discoverLocalSkills }));
+vi.mock("@/src/features/notifications", () => ({ showSuccessToast: vi.fn() }));
+vi.mock("@/src/features/posthog-analytics/usePostHogClientCapture", () => ({
+ usePostHogClientCapture: () => vi.fn(),
+}));
+vi.mock("@/src/utils/api", () => ({
+ getTrpcErrorCode: vi.fn(),
+ api: {
+ useUtils: () => ({
+ skills: { invalidate: vi.fn() },
+ client: { skills: { byName: { query: byName } } },
+ }),
+ skills: {
+ createVersion: {
+ useMutation: () => ({ mutateAsync: createVersion, reset: vi.fn() }),
+ },
+ },
+ },
+}));
+
+const firstSkill = {
+ name: "review-code",
+ path: "review-code",
+ description: "Review a change",
+ files: [{ path: "SKILL.md", content: "Review instructions" }],
+ error: null,
+};
+const secondSkill = {
+ name: "write-tests",
+ path: "write-tests",
+ description: "Write regression tests",
+ files: [{ path: "SKILL.md", content: "Testing instructions" }],
+ error: null,
+};
+
+afterEach(cleanup);
+
+describe("ImportSkillsDialog", () => {
+ it("retries a failed import without creating another version of successful skills", async () => {
+ createVersion
+ .mockResolvedValueOnce({ version: 3 })
+ .mockRejectedValueOnce(new Error("Storage temporarily unavailable"))
+ .mockResolvedValueOnce({ version: 2 });
+ discoverLocalSkills.mockResolvedValue([firstSkill, secondSkill]);
+ byName.mockImplementation(async ({ name }) => ({ name, files: [] }));
+ render(
+ <ImportSkillsDialog projectId="project">
+ {(openDialog) => <button onClick={openDialog}>Open import</button>}
+ </ImportSkillsDialog>,
+ );
+ fireEvent.click(screen.getByRole("button", { name: "Open import" }));
+ fireEvent.change(
+ screen.getByRole("dialog").querySelector('input[type="file"]')!,
+ { target: { files: [new File(["Instructions"], "SKILL.md")] } },
+ );
+ await screen.findByRole("checkbox", { name: /review-code/ });
+ fireEvent.click(screen.getByRole("button", { name: "Select all" }));
+ fireEvent.click(screen.getByRole("button", { name: "Import 2 skills" }));
+
+ await screen.findByText("Storage temporarily unavailable");
+ expect(
+ screen.getByRole("checkbox", { name: /review-code/ }),
+ ).toBeDisabled();
+ expect(
+ screen.getByRole("checkbox", { name: /review-code/ }),
+ ).not.toBeChecked();
+ fireEvent.click(screen.getByRole("button", { name: "Deselect all" }));
+ fireEvent.click(screen.getByRole("button", { name: "Select all" }));
+ fireEvent.click(screen.getByRole("button", { name: "Import 1 skill" }));
+
+ await waitFor(() =>
+ expect(screen.queryByRole("dialog")).not.toBeInTheDocument(),
+ );
+ expect(createVersion.mock.calls.map(([input]) => input.files)).toEqual([
+ firstSkill.files,
+ secondSkill.files,
+ secondSkill.files,
+ ]);
+ });
+});
diff --git a/web/src/features/skills/components/ImportSkillsDialog.tsx b/web/src/features/skills/components/ImportSkillsDialog.tsx
new file mode 100644
index 0000000000..ba70f88ea3
--- /dev/null
+++ b/web/src/features/skills/components/ImportSkillsDialog.tsx
@@ -0,0 +1,404 @@
+import { useRef, useState, type ChangeEvent, type ReactNode } from "react";
+import {
+ COMMIT_MESSAGE_MAX_LENGTH,
+ SKILL_LATEST_LABEL,
+} from "@langfuse/shared";
+import { Badge } from "@/src/components/design-system/Badge/Badge";
+import { Button } from "@/src/components/design-system/Button/Button";
+import { Checkbox } from "@/src/components/design-system/Checkbox/Checkbox";
+import { Dialog } from "@/src/components/design-system/Dialog/Dialog";
+import { DialogController } from "@/src/components/design-system/DialogController/DialogController";
+import { Input } from "@/src/components/design-system/Input/Input";
+import { showSuccessToast } from "@/src/features/notifications";
+import { usePostHogClientCapture } from "@/src/features/posthog-analytics/usePostHogClientCapture";
+import { api, getTrpcErrorCode, type RouterOutputs } from "@/src/utils/api";
+
+import { LocalSkillImportSource } from "./LocalSkillImportSource";
+import type { ComparedSkill, SkillImportDiscovery } from "./skillImportTypes";
+import { compareImportedSkills } from "../utils/compare-imported-skills";
+
+type ImportResult =
+ | { status: "success"; version: number }
+ | { status: "error"; message: string };
+
+export function ImportSkillsDialog({
+ projectId,
+ children,
+}: {
+ projectId: string;
+ children: (openDialog: () => void) => ReactNode;
+}) {
+ const utils = api.useUtils();
+ const capture = usePostHogClientCapture();
+ const [discovery, setDiscovery] = useState<
+ Pick<SkillImportDiscovery, "source" | "commitMessage"> & {
+ skills: ComparedSkill[];
+ }
+ >();
+ const [scanError, setScanError] = useState<string>();
+ const [isScanning, setIsScanning] = useState(false);
+ const createVersion = api.skills.createVersion.useMutation();
+ const [search, setSearch] = useState("");
+ const [selected, setSelected] = useState<Set<string>>(new Set());
+ const [results, setResults] = useState<Record<string, ImportResult>>({});
+ const [isImporting, setIsImporting] = useState(false);
+ const inFlight = useRef(false);
+ const busy = isScanning || isImporting;
+ const skills = discovery?.skills ?? [];
+ const searchTerm = search.trim().toLowerCase();
+ const visibleSkills = skills.filter((skill) =>
+ [skill.name, skill.description, skill.path].some((value) =>
+ value.toLowerCase().includes(searchTerm),
+ ),
+ );
+ const selectable = skills.filter(
+ (skill) =>
+ !skill.error &&
+ (!skill.exists || skill.hasChanges) &&
+ results[skill.path]?.status !== "success",
+ );
+ const selectedSkills = selectable.filter((skill) => selected.has(skill.path));
+ const visiblePaths = new Set(visibleSkills.map((skill) => skill.path));
+ const visibleSelectable = selectable.filter((skill) =>
+ visiblePaths.has(skill.path),
+ );
+ const allVisibleSelected =
+ visibleSelectable.length > 0 &&
+ visibleSelectable.every((skill) => selected.has(skill.path));
+
+ const reset = () => {
+ setDiscovery(undefined);
+ setScanError(undefined);
+ createVersion.reset();
+ setSelected(new Set());
+ setResults({});
+ setSearch("");
+ };
+
+ const scan = async (load: () => Promise<SkillImportDiscovery>) => {
+ if (inFlight.current) return;
+ inFlight.current = true;
+ reset();
+ setIsScanning(true);
+ try {
+ const discovered = await load();
+ const names = [
+ ...new Set(
+ discovered.skills
+ .filter((skill) => !skill.error)
+ .map((skill) => skill.name),
+ ),
+ ];
+ const existing: RouterOutputs["skills"]["byName"][] = [];
+ for (let offset = 0; offset < names.length; offset += 4) {
+ const versions = await Promise.all(
+ names.slice(offset, offset + 4).map(async (name) => {
+ try {
+ return await utils.client.skills.byName.query({
+ projectId,
+ name,
+ label: SKILL_LATEST_LABEL,
+ });
+ } catch (error) {
+ if (getTrpcErrorCode(error) === "NOT_FOUND") return undefined;
+ throw error;
+ }
+ }),
+ );
+ for (const version of versions) {
+ if (version) existing.push(version);
+ }
+ }
+ const data = {
+ ...discovered,
+ skills: await compareImportedSkills(discovered.skills, existing),
+ };
+ setDiscovery(data);
+ setSelected(
+ new Set(
+ data.skills
+ .filter((skill) => !skill.error && !skill.exists)
+ .map((skill) => skill.path),
+ ),
+ );
+ } catch (error) {
+ setScanError(
+ error instanceof Error
+ ? error.message
+ : "Could not scan this source. Please try again.",
+ );
+ } finally {
+ inFlight.current = false;
+ setIsScanning(false);
+ }
+ };
+
+ const importSelected = async (closeDialog: () => void) => {
+ if (inFlight.current || !discovery || !selectedSkills.length) return;
+ inFlight.current = true;
+ setIsImporting(true);
+ const source = discovery;
+ let importedCount = 0;
+ try {
+ for (const skill of selectedSkills) {
+ try {
+ const version = await createVersion.mutateAsync({
+ projectId,
+ files: skill.files,
+ commitMessage: `${source.commitMessage} (${skill.path})`.slice(
+ 0,
+ COMMIT_MESSAGE_MAX_LENGTH,
+ ),
+ });
+ importedCount += 1;
+ setResults((current) => ({
+ ...current,
+ [skill.path]: { status: "success", version: version.version },
+ }));
+ setSelected((current) => {
+ const next = new Set(current);
+ next.delete(skill.path);
+ return next;
+ });
+ } catch (error) {
+ // Preserve successful imports so retrying only submits remaining skills.
+ setResults((current) => ({
+ ...current,
+ [skill.path]: {
+ status: "error",
+ message:
+ error instanceof Error
+ ? error.message
+ : "Import failed. Please try again.",
+ },
+ }));
+ }
+ }
+ if (importedCount > 0) {
+ capture("skills:import", {
+ skillCount: importedCount,
+ source: source.source,
+ });
+ utils.skills.invalidate();
+ showSuccessToast({
+ title: `Imported ${importedCount} ${importedCount === 1 ? "skill" : "skills"}`,
+ description: "The imported copies are available in your skills list.",
+ });
+ }
+ } finally {
+ inFlight.current = false;
+ setIsImporting(false);
+ }
+ if (importedCount === selectedSkills.length) closeDialog();
+ };
+
+ const handleSearchChange = (event: ChangeEvent<HTMLInputElement>) => {
+ setSearch(event.target.value);
+ };
+
+ const toggleVisibleSelection = () => {
+ setSelected((current) => {
+ const next = new Set(current);
+ for (const skill of visibleSelectable) {
+ if (allVisibleSelected) next.delete(skill.path);
+ else next.add(skill.path);
+ }
+ return next;
+ });
+ };
+
+ const createSkillSelectHandler = (path: string) => {
+ return function handleSkillSelectChange(
+ checked: boolean | "indeterminate",
+ ) {
+ setSelected((current) => {
+ const next = new Set(current);
+ if (checked === true) next.add(path);
+ else next.delete(path);
+ return next;
+ });
+ };
+ };
+
+ const canCloseDialog = () => !inFlight.current;
+
+ const createImportHandler = (closeDialog: () => void) => {
+ return function handleImportSelected() {
+ return importSelected(closeDialog);
+ };
+ };
+
+ const createOpenHandler = (openDialog: () => void) => {
+ return function handleOpenDialog() {
+ reset();
+ capture("skills:import_open");
+ openDialog();
+ };
+ };
+
+ return (
+ <DialogController
+ onBeforeClose={canCloseDialog}
+ renderDialog={({ closeDialog }) => (
+ <Dialog
+ title="Import skills"
+ actions={
+ discovery
+ ? [
+ {
+ label: `Import ${selectedSkills.length} ${selectedSkills.length === 1 ? "skill" : "skills"}`,
+ loading: isImporting,
+ disabled: busy || selectedSkills.length === 0,
+ onClick: createImportHandler(closeDialog),
+ },
+ ]
+ : undefined
+ }
+ >
+ <Dialog.Body>
+ <LocalSkillImportSource busy={busy} onScan={scan} onReset={reset} />
+ {scanError ? (
+ <p role="alert" className="ph-no-capture text-destructive">
+ {scanError}
+ </p>
+ ) : null}
+ {discovery && skills.length === 0 ? (
+ <p role="status" className="text-muted-foreground">
+ No SKILL.md files found in this source.
+ </p>
+ ) : null}
+ {discovery && skills.length > 0 ? (
+ <>
+ <div className="ph-no-capture">
+ <Input
+ aria-label="Search skills"
+ placeholder="Search skills by name, description, or path"
+ value={search}
+ onChange={handleSearchChange}
+ />
+ </div>
+ <div className="flex items-center justify-between gap-2">
+ <p role="status">
+ {searchTerm ? `${visibleSkills.length} of ` : ""}
+ {skills.length} {skills.length === 1 ? "skill" : "skills"}{" "}
+ {searchTerm ? "shown" : "found"}
+ {" · "}
+ {selectedSkills.length} selected
+ </p>
+ <Button
+ text={`${allVisibleSelected ? "Deselect all" : "Select all"}${searchTerm ? " shown" : ""}`}
+ variant="ghost"
+ size="sm"
+ disabled={busy || visibleSelectable.length === 0}
+ onClick={toggleVisibleSelection}
+ />
+ </div>
+ {visibleSkills.length === 0 ? (
+ <p role="status" className="text-muted-foreground">
+ No skills match your search.
+ </p>
+ ) : null}
+ <ul className="ph-no-capture flex flex-col divide-y rounded-md border">
+ {visibleSkills.map((skill, index) => {
+ const result = results[skill.path];
+ const error =
+ skill.error ||
+ (result?.status === "error" ? result.message : null);
+ const imported = result?.status === "success";
+ const existingStatus = skill.hasChanges
+ ? "New version"
+ : "Already up to date";
+ return (
+ <li
+ key={skill.path}
+ className="flex items-start gap-3 p-3"
+ >
+ <div className="pt-0.5">
+ <Checkbox
+ id={`import-skill-${index}`}
+ checked={selected.has(skill.path)}
+ disabled={
+ busy ||
+ Boolean(skill.error) ||
+ imported ||
+ (skill.exists && !skill.hasChanges)
+ }
+ onCheckedChange={createSkillSelectHandler(
+ skill.path,
+ )}
+ />
+ </div>
+ <label
+ htmlFor={`import-skill-${index}`}
+ className="flex min-w-0 flex-1 cursor-pointer flex-col gap-1"
+ >
+ <span className="flex flex-wrap items-center gap-2">
+ <span className="font-bold break-words">
+ {skill.name}
+ </span>
+ {!skill.error ? (
+ <Badge
+ text={skill.exists ? existingStatus : "Import"}
+ color={
+ skill.exists && !skill.hasChanges
+ ? "yellow"
+ : "blue"
+ }
+ size="sm"
+ />
+ ) : null}
+ {!skill.error ? (
+ <Badge
+ text={`${skill.files.length} ${skill.files.length === 1 ? "file" : "files"}`}
+ color="primary"
+ size="sm"
+ />
+ ) : null}
+ </span>
+ {skill.exists && !skill.error ? (
+ <span className="text-muted-foreground text-xs">
+ {skill.hasChanges
+ ? "Files differ from the latest saved version. Import to create a new version."
+ : "Files match the latest saved version."}
+ </span>
+ ) : null}
+ <span className="text-muted-foreground text-xs break-all">
+ {skill.path}
+ </span>
+ {skill.description ? (
+ <span className="text-muted-foreground text-sm break-words">
+ {skill.description}
+ </span>
+ ) : null}
+ {error ? (
+ <span
+ className="text-destructive text-sm"
+ role="alert"
+ >
+ {error}
+ </span>
+ ) : null}
+ {result?.status === "success" ? (
+ <span className="text-sm" role="status">
+ Imported as v{result.version}
+ </span>
+ ) : null}
+ </label>
+ </li>
+ );
+ })}
+ </ul>
+ <p className="text-muted-foreground text-xs">
+ Skills with an existing name will get a new version.
+ Production labels stay unchanged.
+ </p>
+ </>
+ ) : null}
+ </Dialog.Body>
+ </Dialog>
+ )}
+ >
+ {({ openDialog }) => children(createOpenHandler(openDialog))}
+ </DialogController>
+ );
+}
diff --git a/web/src/features/skills/components/LocalSkillImportSource.tsx b/web/src/features/skills/components/LocalSkillImportSource.tsx
new file mode 100644
index 0000000000..41ec04fd58
--- /dev/null
+++ b/web/src/features/skills/components/LocalSkillImportSource.tsx
@@ -0,0 +1,70 @@
+import { useState } from "react";
+import type { FileWithPath } from "react-dropzone";
+import { Dropzone } from "@/src/components/design-system/Dropzone/Dropzone";
+import { discoverLocalSkills } from "../utils/local-import";
+import type { SkillImportSourceProps } from "./skillImportTypes";
+
+export function LocalSkillImportSource({
+ busy,
+ onScan,
+ onReset,
+}: SkillImportSourceProps) {
+ const [files, setFiles] = useState<File[]>();
+ const [error, setError] = useState<string>();
+
+ const handleDropError = (error: Error) => {
+ onReset();
+ setFiles(undefined);
+ setError(error.message);
+ };
+
+ const handleDrop = async (acceptedFiles: FileWithPath[]) => {
+ if (acceptedFiles.length === 0 || busy) return;
+ setFiles(acceptedFiles);
+ setError(undefined);
+ await onScan(async () => ({
+ skills: await discoverLocalSkills(
+ acceptedFiles.map((file) => ({
+ // file-selector prefixes dropped paths with "/" or "./".
+ path: (
+ file.webkitRelativePath ||
+ file.relativePath ||
+ file.path ||
+ file.name
+ ).replace(/^(\.\/|\/)/, ""),
+ file,
+ })),
+ ),
+ source: "local",
+ commitMessage: "Imported from local files",
+ }));
+ };
+
+ return (
+ <div className="flex flex-col gap-2">
+ <p className="text-muted-foreground text-sm">
+ Drop files, folders, or ZIPs containing SKILL.md and supporting files.
+ ZIPs can be up to 3 MB each.
+ </p>
+ <div className="ph-no-capture">
+ <Dropzone
+ variant="panel"
+ accept={undefined}
+ maxFiles={10_000}
+ maxSize={undefined}
+ minSize={undefined}
+ src={files}
+ isDisabled={busy}
+ onError={handleDropError}
+ onDrop={handleDrop}
+ />
+ </div>
+ {busy ? <p role="status">Scanning local files for skills…</p> : null}
+ {error ? (
+ <p role="alert" className="ph-no-capture text-destructive">
+ {error}
+ </p>
+ ) : null}
+ </div>
+ );
+}
diff --git a/web/src/features/skills/components/SkillsPage.tsx b/web/src/features/skills/components/SkillsPage.tsx
index 39d06d5481..2f6fe468b5 100644
--- a/web/src/features/skills/components/SkillsPage.tsx
+++ b/web/src/features/skills/components/SkillsPage.tsx
@@ -1,9 +1,10 @@
import { useMemo } from "react";
import Link from "next/link";
-import { FileCode2, Plus, Trash } from "lucide-react";
+import { Download, FileCode2, Plus, Trash } from "lucide-react";
import { NumberParam, useQueryParams, withDefault } from "use-query-params";
import Page from "@/src/components/layouts/page";
import { Button } from "@/src/components/ui/button";
+import { Button as DesignSystemButton } from "@/src/components/design-system/Button/Button";
import { Dialog } from "@/src/components/design-system/Dialog/Dialog";
import { DialogController } from "@/src/components/design-system/DialogController/DialogController";
import { PaginationBar } from "@/src/components/design-system/PaginationBar/PaginationBar";
@@ -38,6 +39,7 @@ import {
SKILLS_FIELD_REGISTRY,
skillsFilterConfig,
} from "../constants/skillsFilterConfig";
+import { ImportSkillsDialog } from "./ImportSkillsDialog";
type SkillRow = RouterOutput["skills"]["all"]["data"][number];
@@ -58,11 +60,24 @@ export function SkillsPage() {
href: "https://langfuse.com/docs",
},
actionButtonsRight: (
- <NewSkillButton
- canCreate={canCreate}
- href={newSkillHref}
- onOpen={() => capture("skills:new_form_open")}
- />
+ <div className="flex items-center gap-2">
+ <ImportSkillsDialog key={projectId} projectId={projectId}>
+ {(openDialog) => (
+ <DesignSystemButton
+ text="Import"
+ icon={Download}
+ variant="secondary"
+ disabled={!canCreate}
+ onClick={openDialog}
+ />
+ )}
+ </ImportSkillsDialog>
+ <NewSkillButton
+ canCreate={canCreate}
+ href={newSkillHref}
+ onOpen={() => capture("skills:new_form_open")}
+ />
+ </div>
),
}}
>
diff --git a/web/src/features/skills/components/skillImportTypes.ts b/web/src/features/skills/components/skillImportTypes.ts
new file mode 100644
index 0000000000..de9abece71
--- /dev/null
+++ b/web/src/features/skills/components/skillImportTypes.ts
@@ -0,0 +1,17 @@
+import type { discoverFileSkills } from "../utils/archive-import";
+
+export type DiscoveredSkill = ReturnType<typeof discoverFileSkills>[number];
+export type ComparedSkill = DiscoveredSkill & {
+ exists: boolean;
+ hasChanges: boolean;
+};
+export type SkillImportDiscovery = {
+ skills: DiscoveredSkill[];
+ source: "local";
+ commitMessage: string;
+};
+export type SkillImportSourceProps = {
+ busy: boolean;
+ onScan: (load: () => Promise<SkillImportDiscovery>) => Promise<void>;
+ onReset: () => void;
+};
diff --git a/web/src/features/skills/utils/archive-import.ts b/web/src/features/skills/utils/archive-import.ts
new file mode 100644
index 0000000000..a45158821c
--- /dev/null
+++ b/web/src/features/skills/utils/archive-import.ts
@@ -0,0 +1,228 @@
+import { Unzip, UnzipInflate, unzipSync } from "fflate";
+import { z } from "zod/v4";
+import {
+ CreateSkillVersionBodySchema,
+ InvalidRequestError,
+} from "@langfuse/shared";
+import { parseSkillFrontmatterMetadata } from "@/src/features/skills/utils/parseSkillFrontmatterMetadata";
+
+const MAX_EXPANDED_BYTES = 20 * 1024 * 1024;
+const MAX_RESPONSE_BYTES = 3 * 1024 * 1024;
+
+export function readSkillArchive(
+ archive: Uint8Array,
+ maxExpandedBytes = MAX_EXPANDED_BYTES,
+) {
+ if (archive.byteLength > 10 * 1024 * 1024) {
+ throw new InvalidRequestError("This archive is too large to import.");
+ }
+ const declaredSizes = new Map<string, number>();
+ const byteLimit = Math.min(maxExpandedBytes, MAX_EXPANDED_BYTES);
+ const entries = new Map<string, Uint8Array>();
+ let declaredBytes = 0;
+ let expandedBytes = 0;
+ try {
+ // Read the central directory without inflating content or trusting its sizes.
+ unzipSync(archive, {
+ filter: (entry) => {
+ declaredBytes += entry.originalSize;
+ if (declaredBytes > byteLimit || declaredSizes.size >= 10_000) {
+ throw new InvalidRequestError("This archive is too large to import.");
+ }
+ if (declaredSizes.has(entry.name)) {
+ throw new InvalidRequestError(
+ "The archive contains duplicate paths.",
+ );
+ }
+ declaredSizes.set(entry.name, entry.originalSize);
+ return false;
+ },
+ });
+ const started = new Set<string>();
+ const unzip = new Unzip((file) => {
+ const expectedSize = declaredSizes.get(file.name);
+ if (
+ expectedSize === undefined ||
+ started.has(file.name) ||
+ (file.originalSize !== undefined && file.originalSize !== expectedSize)
+ ) {
+ throw new InvalidRequestError(
+ "This ZIP archive has inconsistent file metadata.",
+ );
+ }
+ started.add(file.name);
+ const chunks: Uint8Array[] = [];
+ let fileBytes = 0;
+ file.ondata = (error, chunk, final) => {
+ if (error) throw error;
+ fileBytes += chunk.byteLength;
+ expandedBytes += chunk.byteLength;
+ if (expandedBytes > byteLimit) {
+ throw new InvalidRequestError("This archive is too large to import.");
+ }
+ if (fileBytes > expectedSize || (final && fileBytes !== expectedSize)) {
+ throw new InvalidRequestError(
+ "This ZIP archive has inconsistent file sizes.",
+ );
+ }
+ chunks.push(chunk);
+ if (final) {
+ const bytes = new Uint8Array(fileBytes);
+ let offset = 0;
+ for (const part of chunks) {
+ bytes.set(part, offset);
+ offset += part.byteLength;
+ }
+ entries.set(file.name, bytes);
+ }
+ };
+ file.start();
+ });
+ unzip.register(UnzipInflate);
+ // Bound each inflate operation so a forged ZIP cannot expand in one allocation.
+ for (let offset = 0; offset < archive.byteLength; offset += 1024) {
+ unzip.push(
+ archive.subarray(offset, offset + 1024),
+ offset + 1024 >= archive.byteLength,
+ );
+ }
+ if (entries.size !== declaredSizes.size) {
+ throw new InvalidRequestError("This ZIP archive is incomplete.");
+ }
+ } catch (error) {
+ if (error instanceof InvalidRequestError) throw error;
+ throw new InvalidRequestError("This file is not a valid ZIP archive.");
+ }
+ return [...entries]
+ .filter(([path]) => !path.endsWith("/"))
+ .map(([path, bytes]) => ({ path, bytes }));
+}
+
+export function discoverFileSkills({
+ files: inputFiles,
+ fallbackName,
+ sourceRoots = [],
+}: {
+ files: { path: string; bytes: Uint8Array }[];
+ fallbackName: string;
+ sourceRoots?: string[];
+}) {
+ const files = inputFiles.filter(
+ ({ path }) =>
+ !path
+ .split("/")
+ .some((part) => part === "__MACOSX" || part === ".DS_Store"),
+ );
+ const skillFiles = files.filter(
+ ({ path }) => path.split("/").at(-1)?.toLowerCase() === "skill.md",
+ );
+ if (skillFiles.length > 100)
+ throw new InvalidRequestError(
+ "A source can contain at most 100 skills per import.",
+ );
+ const directories = new Map<string, typeof skillFiles>();
+ for (const skillFile of skillFiles) {
+ const directory = skillFile.path.slice(
+ 0,
+ skillFile.path.lastIndexOf("/") + 1,
+ );
+ directories.set(directory, [
+ ...(directories.get(directory) ?? []),
+ skillFile,
+ ]);
+ }
+ const orderedDirectories = [...directories.keys()].sort(
+ (a, b) => b.length - a.length,
+ );
+ const filesByDirectory = new Map<string, typeof files>(
+ orderedDirectories.map((directory) => [directory, []]),
+ );
+ // Each file belongs to the nearest ancestor directory containing SKILL.md.
+ for (const file of files) {
+ const sourceRoot = sourceRoots.find((root) => file.path.startsWith(root));
+ const directory = orderedDirectories.find(
+ (directory) =>
+ file.path.startsWith(directory) &&
+ (!sourceRoot || directory.startsWith(sourceRoot)),
+ );
+ if (directory !== undefined) filesByDirectory.get(directory)!.push(file);
+ }
+ const discovered = [...directories].map(([directory, candidates]) => {
+ const skillFile = candidates[0]!;
+ const path = directory.slice(0, -1) || ".";
+ const fallback = {
+ path,
+ name: path === "." ? fallbackName : path.split("/").at(-1)!,
+ description: "",
+ files: [] as { path: string; content: string }[],
+ };
+ try {
+ if (candidates.length > 1)
+ throw new InvalidRequestError(
+ "This directory contains multiple SKILL.md files with different casing.",
+ );
+ const input = CreateSkillVersionBodySchema.parse({
+ files: filesByDirectory.get(directory)!.map((file) => ({
+ path:
+ file.path === skillFile.path
+ ? "SKILL.md"
+ : file.path.slice(directory.length),
+ content: new TextDecoder("utf-8", {
+ fatal: true,
+ ignoreBOM: true,
+ }).decode(file.bytes),
+ })),
+ });
+ const importedFiles = input.files.map((file) => ({
+ path: file.path,
+ content: file.content!,
+ }));
+ const metadata = parseSkillFrontmatterMetadata(
+ importedFiles.find((file) => file.path === "SKILL.md")!.content,
+ );
+ if (!metadata || metadata.nameError || !metadata.description)
+ throw new InvalidRequestError(
+ "SKILL.md must have valid YAML frontmatter with a name and description.",
+ );
+ return {
+ path,
+ name: metadata.name.trim(),
+ description: metadata.description,
+ files: importedFiles,
+ error: null,
+ };
+ } catch (error) {
+ let message = "Invalid skill files.";
+ if (error instanceof Error) message = error.message;
+ if (error instanceof z.ZodError)
+ message = error.issues[0]?.message ?? message;
+ return {
+ ...fallback,
+ error: message,
+ };
+ }
+ });
+ const names = new Map<string, number>();
+ for (const skill of discovered) {
+ if (!skill.error) names.set(skill.name, (names.get(skill.name) ?? 0) + 1);
+ }
+ const skills = discovered.map((skill) =>
+ !skill.error && names.get(skill.name)! > 1
+ ? {
+ ...skill,
+ files: [],
+ error:
+ "Multiple skills in this source have the same name. Give them unique names before importing.",
+ }
+ : skill,
+ );
+ if (
+ new TextEncoder().encode(JSON.stringify(skills)).byteLength >
+ MAX_RESPONSE_BYTES
+ ) {
+ throw new InvalidRequestError(
+ "The discovered skills are too large to import together.",
+ );
+ }
+ return skills;
+}
diff --git a/web/src/features/skills/utils/compare-imported-skills.clienttest.ts b/web/src/features/skills/utils/compare-imported-skills.clienttest.ts
new file mode 100644
index 0000000000..41dbb422ca
--- /dev/null
+++ b/web/src/features/skills/utils/compare-imported-skills.clienttest.ts
@@ -0,0 +1,36 @@
+import { createHash } from "node:crypto";
+import { describe, expect, it } from "vitest";
+import { compareImportedSkills } from "./compare-imported-skills";
+
+const files = [
+ { path: "SKILL.md", content: "Instructions" },
+ { path: "references/notes.md", content: "Notes" },
+];
+const existing = [
+ {
+ name: "existing-skill",
+ files: files.map(({ path, content }) => ({
+ path,
+ sha256Hash: createHash("sha256").update(content, "utf8").digest("base64"),
+ })),
+ },
+];
+
+describe("browser skill comparison", () => {
+ it("matches saved backend hashes independent of order and detects supporting file changes", async () => {
+ const skill = {
+ name: "existing-skill",
+ path: "skill",
+ description: "Example",
+ files: [...files].reverse(),
+ error: null,
+ };
+ const [unchanged] = await compareImportedSkills([skill], existing);
+ expect(unchanged).toMatchObject({ exists: true, hasChanges: false });
+ const [changed] = await compareImportedSkills(
+ [{ ...skill, files: [files[0]!, { ...files[1]!, content: "Changed" }] }],
+ existing,
+ );
+ expect(changed).toMatchObject({ exists: true, hasChanges: true });
+ });
+});
diff --git a/web/src/features/skills/utils/compare-imported-skills.ts b/web/src/features/skills/utils/compare-imported-skills.ts
new file mode 100644
index 0000000000..fd1a685114
--- /dev/null
+++ b/web/src/features/skills/utils/compare-imported-skills.ts
@@ -0,0 +1,43 @@
+import { Sha256 } from "@aws-crypto/sha256-browser";
+import type {
+ DiscoveredSkill,
+ ComparedSkill,
+} from "../components/skillImportTypes";
+
+export async function compareImportedSkills(
+ skills: DiscoveredSkill[],
+ existingSkills: {
+ name: string;
+ files: { path: string; sha256Hash: string }[];
+ }[],
+): Promise<ComparedSkill[]> {
+ const existingByName = new Map(
+ existingSkills.map((skill) => [skill.name, skill]),
+ );
+ return Promise.all(
+ skills.map(async (skill) => {
+ const existing = existingByName.get(skill.name);
+ let hasChanges = false;
+ if (existing && !skill.error) {
+ const hashesByPath = new Map(
+ existing.files.map((file) => [file.path, file.sha256Hash]),
+ );
+ const hashes = await Promise.all(
+ skill.files.map(async (file) => {
+ const sha256 = new Sha256();
+ sha256.update(new TextEncoder().encode(file.content));
+ const digest = await sha256.digest();
+ return {
+ path: file.path,
+ hash: btoa(String.fromCharCode(...digest)),
+ };
+ }),
+ );
+ hasChanges =
+ existing.files.length !== skill.files.length ||
+ hashes.some(({ path, hash }) => hashesByPath.get(path) !== hash);
+ }
+ return { ...skill, exists: Boolean(existing), hasChanges };
+ }),
+ );
+}
diff --git a/web/src/features/skills/utils/importLimits.ts b/web/src/features/skills/utils/importLimits.ts
new file mode 100644
index 0000000000..f7d6b0cf7d
--- /dev/null
+++ b/web/src/features/skills/utils/importLimits.ts
@@ -0,0 +1 @@
+export const MAX_SKILL_ZIP_UPLOAD_BYTES = 3 * 1024 * 1024;
diff --git a/web/src/features/skills/utils/local-import.clienttest.ts b/web/src/features/skills/utils/local-import.clienttest.ts
new file mode 100644
index 0000000000..adc460c649
--- /dev/null
+++ b/web/src/features/skills/utils/local-import.clienttest.ts
@@ -0,0 +1,64 @@
+import { describe, expect, it, vi } from "vitest";
+import { strToU8, zipSync } from "fflate";
+import { readSkillArchive } from "./archive-import";
+import { discoverLocalSkills } from "./local-import";
+
+const markdown = (name: string) =>
+ `---\nname: ${name}\ndescription: Example skill\n---\nInstructions`;
+describe("ZIP skill discovery", () => {
+ it("rejects a ZIP whose actual expansion exceeds its forged size", () => {
+ const archive = zipSync({
+ "SKILL.md": strToU8(markdown("root") + "x".repeat(1024 * 1024)),
+ });
+ const view = new DataView(
+ archive.buffer,
+ archive.byteOffset,
+ archive.byteLength,
+ );
+ for (let offset = 0; offset < archive.byteLength - 28; offset++) {
+ const signature = view.getUint32(offset, true);
+ if (signature === 0x02014b50) view.setUint32(offset + 24, 36, true);
+ if (signature === 0x04034b50) view.setUint32(offset + 22, 36, true);
+ }
+ expect(() => readSkillArchive(archive)).toThrow("ZIP");
+ });
+});
+
+describe("local skill discovery", () => {
+ const input = (path: string, bytes: Uint8Array) => {
+ const file = new File([], path.split("/").at(-1)!);
+ Object.defineProperty(file, "size", { value: bytes.byteLength });
+ const read = vi.fn(async () => bytes.slice().buffer);
+ Object.defineProperty(file, "arrayBuffer", { value: read });
+ return { path, file, read };
+ };
+
+ it("preserves folder resources and combines files and ZIPs without reading unrelated files", async () => {
+ const unrelated = input(
+ "repo/src/large.bin",
+ new Uint8Array(4 * 1024 * 1024),
+ );
+ const result = await discoverLocalSkills([
+ input("repo/skills/review/SKILL.md", strToU8(markdown("review"))),
+ input("repo/skills/review/references/checklist.md", strToU8("Checklist")),
+ unrelated,
+ input(
+ "other.zip",
+ zipSync({ "write/SKILL.md": strToU8(markdown("write")) }),
+ ),
+ ]);
+ expect(unrelated.read).not.toHaveBeenCalled();
+ expect(result).toMatchObject([
+ {
+ name: "review",
+ path: "repo/skills/review",
+ error: null,
+ files: [
+ { path: "SKILL.md", content: markdown("review") },
+ { path: "references/checklist.md", content: "Checklist" },
+ ],
+ },
+ { name: "write", path: "other/write", error: null },
+ ]);
+ });
+});
diff --git a/web/src/features/skills/utils/local-import.ts b/web/src/features/skills/utils/local-import.ts
new file mode 100644
index 0000000000..25968a3634
--- /dev/null
+++ b/web/src/features/skills/utils/local-import.ts
@@ -0,0 +1,86 @@
+import { MAX_SKILL_BYTES } from "@langfuse/shared";
+import { discoverFileSkills, readSkillArchive } from "./archive-import";
+import { MAX_SKILL_ZIP_UPLOAD_BYTES } from "./importLimits";
+
+const MAX_LOCAL_BYTES = 20 * 1024 * 1024;
+
+export async function discoverLocalSkills(
+ inputs: { path: string; file: File }[],
+) {
+ if (inputs.length > 10_000)
+ throw new Error("Select at most 10,000 files per import.");
+
+ // Folder drops have relative directory paths; only scan directly selected ZIPs.
+ const archives = inputs.filter(
+ ({ path }) => !path.includes("/") && path.toLowerCase().endsWith(".zip"),
+ );
+ const ordinaryFiles = inputs.filter(
+ ({ path }) => !path.toLowerCase().endsWith(".zip"),
+ );
+ const skillDirectories = ordinaryFiles
+ .filter(({ path }) => path.split("/").at(-1)?.toLowerCase() === "skill.md")
+ .map(({ path }) => path.slice(0, path.lastIndexOf("/") + 1));
+ if (skillDirectories.length > 100)
+ throw new Error("A source can contain at most 100 skills per import.");
+
+ // Inspect paths before reading content so unrelated repository files are skipped.
+ const relevantFiles = ordinaryFiles.filter(({ path }) =>
+ skillDirectories.some((directory) => path.startsWith(directory)),
+ );
+ for (const { path, file } of [...relevantFiles, ...archives]) {
+ const isArchive = path.toLowerCase().endsWith(".zip");
+ if (file.size > (isArchive ? MAX_SKILL_ZIP_UPLOAD_BYTES : MAX_SKILL_BYTES))
+ throw new Error(
+ isArchive
+ ? "ZIP files must be 3 MB or smaller."
+ : "Skill files must be 1 MB or smaller.",
+ );
+ }
+ if (
+ [...relevantFiles, ...archives].reduce(
+ (total, { file }) => total + file.size,
+ 0,
+ ) > MAX_LOCAL_BYTES
+ )
+ throw new Error(
+ "The selected skill files and ZIPs must total 20 MB or less.",
+ );
+
+ const files: { path: string; bytes: Uint8Array }[] = [];
+ const sourceRoots: string[] = [];
+ const sourceDirectories = new Set(
+ ordinaryFiles.map(({ path }) => path.split("/")[0]!),
+ );
+ let expandedBytes = 0;
+ for (const { path, file } of [...relevantFiles, ...archives]) {
+ const bytes = new Uint8Array(await file.arrayBuffer());
+ let archiveDirectory = path.slice(0, -4) || path;
+ if (path.toLowerCase().endsWith(".zip")) {
+ for (let suffix = 2; sourceDirectories.has(archiveDirectory); suffix++)
+ archiveDirectory = `${path} (${suffix})`;
+ sourceDirectories.add(archiveDirectory);
+ sourceRoots.push(`${archiveDirectory}/`);
+ }
+ const entries = path.toLowerCase().endsWith(".zip")
+ ? readSkillArchive(bytes, MAX_LOCAL_BYTES - expandedBytes).map(
+ (entry) => ({
+ ...entry,
+ path: `${archiveDirectory}/${entry.path}`,
+ }),
+ )
+ : [{ path, bytes }];
+ for (const entry of entries) {
+ expandedBytes += entry.bytes.byteLength;
+ if (expandedBytes > MAX_LOCAL_BYTES)
+ throw new Error("The expanded skill files must total 20 MB or less.");
+ files.push(entry);
+ if (files.length > 10_000)
+ throw new Error("Select at most 10,000 files per import.");
+ }
+ }
+ return discoverFileSkills({
+ files,
+ fallbackName: "Local files",
+ sourceRoots,
+ });
+}