Skip to content

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

feat(skills): expose skill management as a public v4 preview (#18948)

tobi_kl45680644604b
diff --git a/web/src/__tests__/server/organization-feature-flags.servertest.ts b/web/src/__tests__/server/organization-feature-flags.servertest.ts
index 7f51ce67f0..588c69ccea 100644
--- a/web/src/__tests__/server/organization-feature-flags.servertest.ts
+++ b/web/src/__tests__/server/organization-feature-flags.servertest.ts
@@ -280,6 +280,7 @@ describe("organization feature preview defaults", () => {
// here. Asserting that two REGISTERED defaults resolve differently needs
// a second preview; add that half back with the next one.
externalMediaStorage: false,
+ skillManagement: false,
sessionViewV2: false,
sessionViewV2Timeline: false,
});
@@ -541,6 +542,7 @@ describe("organization member feature preview overrides", () => {
// hidden, which is what this guards.
expect(row?.featurePreviews).toEqual({
externalMediaStorage: false,
+ skillManagement: false,
sessionViewV2: true,
sessionViewV2Timeline: false,
});
diff --git a/web/src/components/layouts/app-layout/utils/navigationFilters.ts b/web/src/components/layouts/app-layout/utils/navigationFilters.ts
index 5d31fa92a3..4e9ef11285 100644
--- a/web/src/components/layouts/app-layout/utils/navigationFilters.ts
+++ b/web/src/components/layouts/app-layout/utils/navigationFilters.ts
@@ -8,6 +8,7 @@ import type { NavigationFilterContext } from "./navigationFilters.types";
import { hasProjectAccess, hasOrganizationAccess } from "@/src/features/rbac";
import type { Session } from "next-auth";
import { isAdminOnlyFeaturePreviewFlag } from "@/src/features/feature-flags/available-flags";
+import { getContextualFeatureFlags } from "@/src/features/feature-flags/utils";
/** Organization type from user session (can be null when not in project/org context) */
type Organization =
@@ -72,6 +73,13 @@ const filters = {
featureFlags: (route: Route, ctx: NavigationFilterContext): Route | null => {
if (route.featureFlag === undefined) return route;
+ if (
+ route.featureFlag === "skillManagement" &&
+ ctx.session?.user?.v4BetaEnabled !== true
+ ) {
+ return null;
+ }
+
if (isAdminOnlyFeaturePreviewFlag(route.featureFlag)) {
return ctx.session?.user?.featureFlags?.[route.featureFlag] === true
? route
@@ -92,8 +100,11 @@ const filters = {
const hasFlag =
ctx.enableExperimentalFeatures ||
- ctx.cloudAdmin ||
- ctx.session?.user?.featureFlags?.[route.featureFlag] === true;
+ (ctx.cloudAdmin && route.featureFlag !== "skillManagement") ||
+ getContextualFeatureFlags(ctx.session?.user, {
+ projectId: ctx.routerProjectId,
+ organizationId: ctx.routerOrganizationId,
+ })?.[route.featureFlag] === true;
return hasFlag ? route : null;
},
diff --git a/web/src/components/layouts/routes.tsx b/web/src/components/layouts/routes.tsx
index e27bc256f4..40e388cc9a 100644
--- a/web/src/components/layouts/routes.tsx
+++ b/web/src/components/layouts/routes.tsx
@@ -1,4 +1,5 @@
import { type Flag } from "@/src/features/feature-flags/types";
+import { Badge } from "@/src/components/design-system/Badge/Badge";
import { type ProjectScope } from "@langfuse/shared";
import {
BellRing,
@@ -167,7 +168,8 @@ export const ROUTES: Route[] = [
},
{
title: "Skills",
- featureFlag: "internalFeatures",
+ featureFlag: "skillManagement",
+ label: <Badge text="Beta" color="blue" size="sm" />,
href: "/project/[projectId]/skills",
icon: FolderCode,
projectRbacScopes: ["skills:read"],
diff --git a/web/src/features/feature-flags/available-flags.ts b/web/src/features/feature-flags/available-flags.ts
index 10b7805300..891eda6cf5 100644
--- a/web/src/features/feature-flags/available-flags.ts
+++ b/web/src/features/feature-flags/available-flags.ts
@@ -5,6 +5,7 @@ export const organizationOnlyFeaturePreviewFlags = [
] as const;
export const userFeaturePreviewFlags = [
+ "skillManagement",
"sessionViewV2",
"sessionViewV2Timeline",
] as const;
@@ -76,6 +77,7 @@ export const filterFeaturePreviewFlags = (
): FeaturePreviewFlag[] => flags.filter(isFeaturePreviewFlag);
export const featurePreviewLabels = {
+ skillManagement: "Skill Management",
externalMediaStorage: "External Media Storage",
sessionViewV2: "Redesigned Session View",
sessionViewV2Timeline: "Session Timeline",
@@ -93,7 +95,11 @@ export const isFeaturePreviewAvailable = (
if (flag === "externalMediaStorage") {
return true;
}
- if (flag === "sessionViewV2" || flag === "sessionViewV2Timeline") {
+ if (
+ flag === "sessionViewV2" ||
+ flag === "sessionViewV2Timeline" ||
+ flag === "skillManagement"
+ ) {
return context.v4BetaEnabled;
}
diff --git a/web/src/features/feature-flags/components/UserFeaturePreviewsPopover.clienttest.tsx b/web/src/features/feature-flags/components/UserFeaturePreviewsPopover.clienttest.tsx
index e4cbc2dea2..a1759bd029 100644
--- a/web/src/features/feature-flags/components/UserFeaturePreviewsPopover.clienttest.tsx
+++ b/web/src/features/feature-flags/components/UserFeaturePreviewsPopover.clienttest.tsx
@@ -147,6 +147,7 @@ describe("UserFeaturePreviewsControl", () => {
userId: "user-1",
featurePreviews: {
externalMediaStorage: false,
+ skillManagement: false,
sessionViewV2: true,
sessionViewV2Timeline: false,
},
@@ -170,6 +171,7 @@ describe("UserFeaturePreviewsControl", () => {
userId: "user-1",
featurePreviews: {
externalMediaStorage: false,
+ skillManagement: false,
sessionViewV2: false,
sessionViewV2Timeline: false,
},
@@ -194,6 +196,7 @@ describe("UserFeaturePreviewsControl", () => {
userId: "user-1",
featurePreviews: {
externalMediaStorage: false,
+ skillManagement: false,
sessionViewV2: false,
sessionViewV2Timeline: false,
},
@@ -241,6 +244,7 @@ describe("UserFeaturePreviewsControl", () => {
userId: "user-1",
featurePreviews: {
externalMediaStorage: false,
+ skillManagement: false,
sessionViewV2: false,
sessionViewV2Timeline: false,
},
@@ -273,6 +277,7 @@ describe("UserFeaturePreviewsControl", () => {
userId: "user-1",
featurePreviews: {
externalMediaStorage: false,
+ skillManagement: false,
sessionViewV2: false,
sessionViewV2Timeline: false,
},
diff --git a/web/src/features/feature-flags/types.ts b/web/src/features/feature-flags/types.ts
index c57d815528..53743d2634 100644
--- a/web/src/features/feature-flags/types.ts
+++ b/web/src/features/feature-flags/types.ts
@@ -7,6 +7,7 @@ export type Flag = (typeof availableFlags)[number];
export type Flags = {
[key in Exclude<
Flag,
+ | "skillManagement"
| "externalMediaStorage"
| "sessionViewV2"
| "aiGateway"
@@ -15,6 +16,7 @@ export type Flags = {
>]: boolean;
} & {
// Optional while older sessions and test fixtures roll across new flags.
+ skillManagement?: boolean;
externalMediaStorage?: boolean;
sessionViewV2?: boolean;
aiGateway?: boolean;
diff --git a/web/src/features/feature-flags/utils.clienttest.ts b/web/src/features/feature-flags/utils.clienttest.ts
index 46816c3db3..7871f92512 100644
--- a/web/src/features/feature-flags/utils.clienttest.ts
+++ b/web/src/features/feature-flags/utils.clienttest.ts
@@ -9,8 +9,30 @@ import {
parseFlagsWithOrganizationDefaults,
} from "./utils";
import { getOrganizationFeaturePreviewDefaults } from "./fns/getOrganizationFeaturePreviewDefaults";
+import { isFeaturePreviewAvailable } from "./available-flags";
describe("parseFlags", () => {
+ it("makes Skill Management an opt-in preview that requires v4", () => {
+ const context = { email: "[email protected]", v4BetaEnabled: true };
+ expect(
+ isFeaturePreviewAvailable("skillManagement", { v4BetaEnabled: false }),
+ ).toBe(false);
+ expect(isFeaturePreviewAvailable("skillManagement", context)).toBe(true);
+ expect(parseFlags([], context).skillManagement).toBe(false);
+ expect(parseFlags(["skillManagement"], context).skillManagement).toBe(true);
+ expect(
+ parseFlagsWithOrganizationDefaults([], ["skillManagement"], context)
+ .skillManagement,
+ ).toBe(true);
+ expect(
+ parseFlagsWithOrganizationDefaults(
+ [getFeaturePreviewOptOutFlag("skillManagement")],
+ ["skillManagement"],
+ context,
+ ).skillManagement,
+ ).toBe(false);
+ });
+
it.each([
{ flag: "sessionViewV2" as const, expectedView: false },
{ flag: "sessionViewV2Timeline" as const, expectedView: true },
diff --git a/web/src/features/feature-previews/components/ControlledFeaturePreviewModal.tsx b/web/src/features/feature-previews/components/ControlledFeaturePreviewModal.tsx
index d68ef81f96..0344660516 100644
--- a/web/src/features/feature-previews/components/ControlledFeaturePreviewModal.tsx
+++ b/web/src/features/feature-previews/components/ControlledFeaturePreviewModal.tsx
@@ -56,6 +56,22 @@ export function ControlledFeaturePreviewModal({
authSession.data?.environment.enableExperimentalFeatures === true;
const state: Partial<Record<PreviewFlag, PreviewState>> = {
+ skillManagement: {
+ enabled:
+ isV4 &&
+ (authSession.data?.user?.featureFlags.skillManagement === true ||
+ authSession.data?.environment.enableExperimentalFeatures === true),
+ disabled:
+ !isV4 ||
+ authSession.data?.environment.enableExperimentalFeatures === true,
+ warningReason: !isV4
+ ? `Skill Management requires ${V4_PREVIEW_LABEL}. Turn it on to enable this preview.`
+ : authSession.data?.environment.enableExperimentalFeatures === true
+ ? "This preview is enabled by LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES, so a per-user opt-out does not disable it."
+ : undefined,
+ onToggle: onToggle("skillManagement"),
+ isToggling: setFeaturePreviewEnabled.isPending,
+ },
...(authSession.data?.user?.admin === true
? {
langfuseTopics: {
diff --git a/web/src/features/feature-previews/components/FeaturePreviewModal.clienttest.tsx b/web/src/features/feature-previews/components/FeaturePreviewModal.clienttest.tsx
index 715a227897..ebd6b49cf2 100644
--- a/web/src/features/feature-previews/components/FeaturePreviewModal.clienttest.tsx
+++ b/web/src/features/feature-previews/components/FeaturePreviewModal.clienttest.tsx
@@ -8,6 +8,24 @@ vi.mock("next/image", () => ({
}));
describe("FeaturePreviewModal", () => {
+ it("lets users opt into Skill Management without other previews", () => {
+ const onToggle = vi.fn();
+
+ render(
+ <FeaturePreviewModal
+ open
+ onOpenChange={vi.fn()}
+ state={{ skillManagement: { enabled: false, onToggle } }}
+ />,
+ );
+
+ fireEvent.click(
+ screen.getByRole("switch", { name: "Toggle Skill Management" }),
+ );
+
+ expect(onToggle).toHaveBeenCalledWith(true);
+ });
+
it("renders the session timeline toggle inside Redesigned Session View", () => {
const onTimelineToggle = vi.fn();
diff --git a/web/src/features/feature-previews/components/FeaturePreviewModal.tsx b/web/src/features/feature-previews/components/FeaturePreviewModal.tsx
index 808c683d80..57a3ba6e9d 100644
--- a/web/src/features/feature-previews/components/FeaturePreviewModal.tsx
+++ b/web/src/features/feature-previews/components/FeaturePreviewModal.tsx
@@ -53,6 +53,14 @@ export type PreviewState = {
// Static registry — one entry per preview, in sidebar order.
// Previews may include separate light/dark illustrations.
const PREVIEW_REGISTRY: PreviewRegistryItem[] = [
+ {
+ flag: "skillManagement",
+ description:
+ "Create, version, and distribute reusable agent skills from one place.",
+ details:
+ "Import skills, manage their versions and labels, install them with the CLI, and inspect the skills available or loaded in your traces.",
+ feedbackUrl: "https://github.com/orgs/langfuse/discussions",
+ },
{
flag: "langfuseTopics",
description:
diff --git a/web/src/features/prompts/components/ProtectedLabelsSettings.tsx b/web/src/features/prompts/components/ProtectedLabelsSettings.tsx
index 39b4a495c7..f9f5b10e5d 100644
--- a/web/src/features/prompts/components/ProtectedLabelsSettings.tsx
+++ b/web/src/features/prompts/components/ProtectedLabelsSettings.tsx
@@ -13,7 +13,8 @@ import {
import Header from "@/src/components/layouts/header";
import { useHasProjectAccess } from "@/src/features/rbac";
import { useHasEntitlement } from "@/src/features/entitlements";
-import { useInternalFeaturesEnabled } from "@/src/features/feature-flags";
+import { useIsFeatureEnabled } from "@/src/features/feature-flags";
+import { useReadPath } from "@/src/features/events";
import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";
import { XIcon, Check } from "lucide-react";
@@ -56,7 +57,12 @@ export default function ProtectedLabelsSettings({
scope: "promptProtectedLabels:CUD",
});
const hasEntitlement = useHasEntitlement("prompt-protected-labels");
- const skillsEnabled = useInternalFeaturesEnabled();
+ const { isV4 } = useReadPath();
+ const skillManagementEnabled = useIsFeatureEnabled("skillManagement", {
+ projectId,
+ enableForAdmins: false,
+ });
+ const skillsEnabled = isV4 && skillManagementEnabled;
const form = useForm({
resolver: zodResolver(AddLabelFormSchema),
diff --git a/web/src/features/skills/components/CliSkillImportInstructions.tsx b/web/src/features/skills/components/CliSkillImportInstructions.tsx
index 185ab7394f..90ab5837c8 100644
--- a/web/src/features/skills/components/CliSkillImportInstructions.tsx
+++ b/web/src/features/skills/components/CliSkillImportInstructions.tsx
@@ -18,10 +18,7 @@ export function CliSkillImportInstructions({
</p>
<div className="flex flex-col gap-2">
<h3 className="font-bold">1. Install or update the CLI</h3>
- <Codeblock
- language="bash"
- value="npm install -g @langfuse/[email protected]"
- />
+ <Codeblock language="bash" value="npm install -g @langfuse/cli@beta" />
</div>
<div className="flex flex-col items-start gap-2">
<h3 className="font-bold">2. Configure your project</h3>
diff --git a/web/src/features/skills/components/InstallSkillDialog.tsx b/web/src/features/skills/components/InstallSkillDialog.tsx
index 0eb4ce16c1..a82d741f1b 100644
--- a/web/src/features/skills/components/InstallSkillDialog.tsx
+++ b/web/src/features/skills/components/InstallSkillDialog.tsx
@@ -39,7 +39,7 @@ export function InstallSkillDialog({
<h3 className="font-bold">1. Install the CLI</h3>
<Codeblock
language="bash"
- value="npm install -g @langfuse/[email protected]"
+ value="npm install -g @langfuse/cli@beta"
/>
</div>
<div className="flex flex-col items-start gap-3">
diff --git a/web/src/features/skills/components/SkillsFeatureGate.tsx b/web/src/features/skills/components/SkillsFeatureGate.tsx
index 0680cac604..bc982800a3 100644
--- a/web/src/features/skills/components/SkillsFeatureGate.tsx
+++ b/web/src/features/skills/components/SkillsFeatureGate.tsx
@@ -1,11 +1,18 @@
import { type ReactNode } from "react";
import { ErrorPage } from "@/src/components/error-page";
-import { useInternalFeaturesEnabled } from "@/src/features/feature-flags";
+import { useIsFeatureEnabled } from "@/src/features/feature-flags";
+import useProjectIdFromURL from "@/src/hooks/useProjectIdFromURL";
+import { useReadPath } from "@/src/features/events";
export function SkillsFeatureGate({ children }: { children: ReactNode }) {
- const enabled = useInternalFeaturesEnabled();
+ const projectId = useProjectIdFromURL();
+ const { isV4 } = useReadPath();
+ const enabled = useIsFeatureEnabled("skillManagement", {
+ projectId,
+ enableForAdmins: false,
+ });
- return enabled ? (
+ return isV4 && enabled ? (
children
) : (
<ErrorPage title="Page not found" message="This page is not available." />
diff --git a/web/src/features/skills/components/SkillsPage.tsx b/web/src/features/skills/components/SkillsPage.tsx
index a47e5e971f..f1971684d7 100644
--- a/web/src/features/skills/components/SkillsPage.tsx
+++ b/web/src/features/skills/components/SkillsPage.tsx
@@ -45,7 +45,7 @@ import {
} from "@/src/features/search-bar";
import useProjectIdFromURL from "@/src/hooks/useProjectIdFromURL";
import { useHasProjectAccess } from "@/src/features/rbac/utils/checkProjectAccess";
-import { InternalFeatureBadge } from "@/src/features/feature-flags";
+import { Badge } from "@/src/components/design-system/Badge/Badge";
import { usePostHogClientCapture } from "@/src/features/posthog-analytics/usePostHogClientCapture";
import { api } from "@/src/utils/api";
import { type RouterOutput } from "@/src/utils/types";
@@ -89,7 +89,7 @@ export function SkillsPage() {
<Page
headerProps={{
title: "Skills",
- titleBadges: <InternalFeatureBadge />,
+ titleBadges: <Badge text="Beta" color="blue" size="sm" />,
help: {
description:
"Create, version, and distribute reusable agent skills from one place.",
@@ -149,6 +149,11 @@ function SkillsHeaderActions({
return (
<div className="flex max-w-full flex-wrap items-center gap-2">
+ <DesignSystemButton
+ text="API reference"
+ variant="ghost"
+ href="https://api.reference.langfuse.com/#tag/unstableskills"
+ />
<DesignSystemButton
text="Install with CLI"
icon={Terminal}
diff --git a/web/src/features/traces/components/IOPreview/components/SectionSkills.tsx b/web/src/features/traces/components/IOPreview/components/SectionSkills.tsx
index a4978fa42b..9c638ee00b 100644
--- a/web/src/features/traces/components/IOPreview/components/SectionSkills.tsx
+++ b/web/src/features/traces/components/IOPreview/components/SectionSkills.tsx
@@ -13,7 +13,6 @@ import {
CollapsibleContent,
CollapsibleTrigger,
} from "@/src/components/ui/collapsible";
-import { InternalFeatureBadge } from "@/src/features/feature-flags";
export function SectionSkills({ projectId, skills }: SectionSkillsProps) {
const [isGroupExpanded, setGroupExpanded] = useState(false);
@@ -37,7 +36,7 @@ export function SectionSkills({ projectId, skills }: SectionSkillsProps) {
<div className="flex items-center gap-2 px-1 py-1">
<h3 className="io-message-header text-base font-bold">Skills</h3>
<Badge color="filled" size="sm" text={String(groups.length)} />
- <InternalFeatureBadge />
+ <Badge text="Beta" color="blue" size="sm" />
</div>
<Collapsible
open={isGroupExpanded}
diff --git a/web/src/features/traces/components/ObservationDetailView/ConnectedObservationDetailView.tsx b/web/src/features/traces/components/ObservationDetailView/ConnectedObservationDetailView.tsx
index 8a228c9737..3e1e2558df 100644
--- a/web/src/features/traces/components/ObservationDetailView/ConnectedObservationDetailView.tsx
+++ b/web/src/features/traces/components/ObservationDetailView/ConnectedObservationDetailView.tsx
@@ -67,7 +67,10 @@ import { useHasProjectAccess } from "@/src/features/rbac";
import { useSession } from "next-auth/react";
import { ObservationPreview } from "./ObservationPreview";
import type { SectionSkillsProps } from "../IOPreview/components/SectionSkills";
-import { useInternalFeaturesEnabled } from "@/src/features/feature-flags";
+import {
+ useInternalFeaturesEnabled,
+ useIsFeatureEnabled,
+} from "@/src/features/feature-flags";
import { TraceMessagesView } from "../TraceMessagesView/TraceMessagesView";
import { DetailAttributesTab } from "../DetailAttributesTab";
import { buildModelParameters } from "@/src/features/traces/fns/buildModelParameters";
@@ -97,6 +100,10 @@ export function ConnectedObservationDetailView({
// V4 beta mode and observations for log tab
const { isV4: isV4Enabled } = useReadPath();
const internalFeaturesEnabled = useInternalFeaturesEnabled();
+ const skillManagementEnabled = useIsFeatureEnabled("skillManagement", {
+ projectId,
+ enableForAdmins: false,
+ });
const {
observations,
roots,
@@ -336,7 +343,7 @@ export function ConnectedObservationDetailView({
}, [observation.latency, observation.startTime, observation.endTime]);
const previewSkills = getPreviewSkills({
- internalFeaturesEnabled,
+ skillManagementEnabled: isV4Enabled && skillManagementEnabled,
observationType: observation.type,
skillsAvailable: observationWithIO?.skillsAvailable,
skillsResourceLoaded: observationWithIO?.skillsResourceLoaded,
@@ -613,12 +620,12 @@ export function ConnectedObservationDetailView({
}
function getPreviewSkills({
- internalFeaturesEnabled,
+ skillManagementEnabled,
observationType,
skillsAvailable,
skillsResourceLoaded,
}: PreviewSkillsInput): SectionSkillsProps["skills"] | undefined {
- if (!internalFeaturesEnabled) return undefined;
+ if (!skillManagementEnabled) return undefined;
if (observationType === "GENERATION") {
return { kind: "available", items: skillsAvailable ?? [] };
}
@@ -629,7 +636,7 @@ function getPreviewSkills({
}
type PreviewSkillsInput = {
- internalFeaturesEnabled: boolean;
+ skillManagementEnabled: boolean;
observationType: ObservationReturnTypeWithMetadata["type"];
skillsAvailable:
| ObservationReturnTypeWithMetadata["skillsAvailable"]