let loops run a skill instead of instructions

Author: charlesvien

packages/api-client/src/loops.ts

@@ -48,6 +48,7 @@ export namespace LoopSchemas {
     | "failed"
     | "cancelled";
   export type LoopRunEnvironmentEnum = "local" | "cloud";
+  export type LoopSkillSourceEnum = "user" | "repo" | "marketplace" | "codex";
 
   export type LoopRepositoryEntry = {
     github_integration_id: number;
@@ -202,6 +203,30 @@ export namespace LoopSchemas {
     created_at: string;
     updated_at: string;
     triggers: Array<LoopTrigger>;
+    /** Skill bundles attached to this loop, seeded into every fired run's sandbox.
+     * Replaced wholesale via `replaceLoopSkillBundles`, never through the loop write. */
+    skill_bundles: Array<LoopSkillBundle>;
+  };
+
+  /** A skill bundle attached to a loop. `content_sha256` is the stored snapshot's
+   * digest, so a client can detect drift from the local copy of the skill. */
+  export type LoopSkillBundle = {
+    id: string;
+    skill_name: string;
+    skill_source: LoopSkillSourceEnum;
+    size: number;
+    content_sha256: string;
+    uploaded_at: string;
+  };
+
+  /** One zipped local skill in a skill-bundle replace request. */
+  export type LoopSkillBundleUpload = {
+    file_name: string;
+    skill_name: string;
+    skill_source: LoopSkillSourceEnum;
+    content_sha256: string;
+    bundle_format: "zip";
+    content_base64: string;
   };
 
   /** Request body for create (all required fields present) and partial_update
@@ -389,6 +414,8 @@ const loopRunsPath = (projectId: string, loopId: string): string =>
   `/api/projects/${projectId}/loops/${loopId}/runs/`;
 const loopPreviewPath = (projectId: string, loopId: string): string =>
   `/api/projects/${projectId}/loops/${loopId}/preview/`;
+const loopSkillBundlesPath = (projectId: string, loopId: string): string =>
+  `/api/projects/${projectId}/loops/${loopId}/skill_bundles/`;
 
 function idempotencyHeader(
   idempotencyKey: string | undefined,
@@ -579,6 +606,17 @@ export async function listLoopRuns(
   });
 }
 
+export async function replaceLoopSkillBundles(
+  client: ApiClient,
+  projectId: string,
+  loopId: string,
+  bundles: Array<LoopSchemas.LoopSkillBundleUpload>,
+): Promise<LoopSchemas.Loop> {
+  return loopsRequest(client, "put", loopSkillBundlesPath(projectId, loopId), {
+    body: { bundles },
+  });
+}
+
 export async function previewLoop(
   client: ApiClient,
   projectId: string,

packages/ui/src/features/loops/components/LoopDetailView.tsx

@@ -1,5 +1,7 @@
 import { ArrowLeftIcon, RepeatIcon } from "@phosphor-icons/react";
 import type { LoopSchemas } from "@posthog/api-client/loops";
+import { isUploadableSkillSource } from "@posthog/core/message-editor/skillTags";
+import { useHostTRPC } from "@posthog/host-router/react";
 import {
   AlertDialog,
   AlertDialogClose,
@@ -17,14 +19,17 @@ import { UserAvatar } from "@posthog/ui/features/auth/UserAvatar";
 import { useOrgMembers } from "@posthog/ui/features/canvas/hooks/useOrgMembers";
 import { userDisplayName } from "@posthog/ui/features/canvas/utils/userDisplay";
 import { useSetHeaderContent } from "@posthog/ui/hooks/useSetHeaderContent";
+import { Button as ActionButton } from "@posthog/ui/primitives/Button";
 import { TimezoneTimestamp } from "@posthog/ui/primitives/TimezoneTimestamp";
 import { systemTimezone } from "@posthog/ui/primitives/timezone";
 import { toast } from "@posthog/ui/primitives/toast";
 import {
   navigateToEditLoop,
   navigateToLoops,
 } from "@posthog/ui/router/navigationBridge";
+import { useHostCapabilities } from "@posthog/ui/shell/useHostCapabilities";
 import { Flex, Text } from "@radix-ui/themes";
+import { useQuery } from "@tanstack/react-query";
 import { useRef, useState } from "react";
 import { useLoop } from "../hooks/useLoop";
 import { useLoopDisplayModel } from "../hooks/useLoopDisplayModel";
@@ -34,13 +39,15 @@ import {
   useUpdateLoop,
 } from "../hooks/useLoopMutations";
 import { RECENT_RUNS_LIMIT, useLoopRuns } from "../hooks/useLoopRuns";
+import { useSyncLoopSkillBundles } from "../hooks/useLoopSkillBundles";
 import {
   describeTrigger,
   loopStatusColor,
   loopStatusLabel,
   nextScheduleRun,
   summarizeNotificationDestinations,
 } from "../loopDisplay";
+import { primaryLoopSkillBundle } from "../loopSkill";
 import { LoopLoadError } from "./LoopFallbacks";
 import { LoopRunRow } from "./LoopRunRow";
 
@@ -315,6 +322,12 @@ function ConfigSummarySection({ loop }: { loop: LoopSchemas.Loop }) {
             .join(" · ")}
         </SummaryRow>
 
+        {loop.skill_bundles.length > 0 ? (
+          <SummaryRow label="Skill">
+            <LoopSkillSummary loop={loop} />
+          </SummaryRow>
+        ) : null}
+
         <SummaryRow label="Repository">
           {loop.repositories.length > 0
             ? loop.repositories.map((repo) => repo.full_name).join(", ")
@@ -350,6 +363,80 @@ function ConfigSummarySection({ loop }: { loop: LoopSchemas.Loop }) {
   );
 }
 
+function LoopSkillSummary({ loop }: { loop: LoopSchemas.Loop }) {
+  const { localWorkspaces } = useHostCapabilities();
+  const trpc = useHostTRPC();
+  const skillsQuery = useQuery({
+    ...trpc.skills.list.queryOptions(),
+    enabled: localWorkspaces,
+  });
+  const syncSkillBundles = useSyncLoopSkillBundles();
+
+  const primary = primaryLoopSkillBundle(loop);
+  if (!primary) return null;
+  const dependencyCount = loop.skill_bundles.length - 1;
+
+  const localMatch = (skillsQuery.data ?? []).find(
+    (skill) =>
+      skill.name === primary.skill_name &&
+      isUploadableSkillSource(skill.source),
+  );
+  const updateDisabledReason = !localWorkspaces
+    ? "updating the snapshot needs the desktop app"
+    : localMatch
+      ? null
+      : `no local skill named ${primary.skill_name} was found on this machine`;
+
+  const handleUpdate = () => {
+    if (!localMatch || !isUploadableSkillSource(localMatch.source)) return;
+    syncSkillBundles.mutate(
+      {
+        loopId: loop.id,
+        skill: {
+          name: localMatch.name,
+          source: localMatch.source,
+          path: localMatch.path,
+        },
+      },
+      {
+        onSuccess: () => toast.success("Skill snapshot updated"),
+        onError: (error) =>
+          toast.error("Failed to update the skill snapshot", {
+            description: error.message,
+          }),
+      },
+    );
+  };
+
+  return (
+    <Flex align="center" gap="2" wrap="wrap">
+      <Text className="text-[12.5px] text-gray-12">
+        {primary.skill_name}
+        {dependencyCount > 0
+          ? ` (+${dependencyCount} ${dependencyCount === 1 ? "dependency" : "dependencies"})`
+          : ""}
+      </Text>
+      <Text
+        className="text-[11px] text-gray-10"
+        title={new Date(primary.uploaded_at).toLocaleString()}
+      >
+        Snapshot {primary.content_sha256.slice(0, 8)}
+      </Text>
+      <ActionButton
+        variant="soft"
+        color="gray"
+        size="1"
+        loading={syncSkillBundles.isPending}
+        disabled={syncSkillBundles.isPending || !!updateDisabledReason}
+        disabledReason={updateDisabledReason}
+        onClick={handleUpdate}
+      >
+        Update from local skill
+      </ActionButton>
+    </Flex>
+  );
+}
+
 function InstructionsSection({ loop }: { loop: LoopSchemas.Loop }) {
   const updateLoop = useUpdateLoop(loop.id);
   const [draft, setDraft] = useState<string | null>(null);

packages/ui/src/features/loops/components/LoopForm.tsx

@@ -13,10 +13,11 @@ import {
   navigateToLoopDetail,
   navigateToLoops,
 } from "@posthog/ui/router/navigationBridge";
-import { Box, Flex, Text, TextArea, TextField } from "@radix-ui/themes";
+import { Box, Flex, Text, TextField } from "@radix-ui/themes";
 import { type ReactNode, useEffect, useState } from "react";
 import { useAuthStateValue } from "../../auth/store";
 import { useCreateLoop, useUpdateLoop } from "../hooks/useLoopMutations";
+import { useSyncLoopSkillBundles } from "../hooks/useLoopSkillBundles";
 import { summarizeTrigger } from "../loopDisplay";
 import { useLoopDraftStore } from "../loopDraftStore";
 import {
@@ -30,12 +31,14 @@ import {
   loopToFormValues,
   normalizeLoopFormValues,
 } from "../loopFormTypes";
+import { buildSkillInstructions } from "../loopSkill";
 import { LoopBehaviorFields } from "./LoopBehaviorFields";
 import { LoopContextFields } from "./LoopContextFields";
 import { Field } from "./LoopFormPrimitives";
 import { LoopModelFields } from "./LoopModelFields";
 import { LoopNotificationsFields } from "./LoopNotificationsFields";
 import { LoopRepositoryPicker } from "./LoopRepositoryPicker";
+import { LoopInstructionsFields } from "./LoopSkillFields";
 import { LoopTriggerEditor } from "./LoopTriggerEditor";
 
 const VISIBILITY_OPTIONS: {
@@ -85,13 +88,17 @@ export function LoopForm({ loop }: LoopFormProps) {
 
   const createLoop = useCreateLoop();
   const updateLoop = useUpdateLoop(loop?.id ?? "");
-  const isSubmitting = isEdit ? updateLoop.isPending : createLoop.isPending;
+  const syncSkillBundles = useSyncLoopSkillBundles();
+  const isSubmitting =
+    (isEdit ? updateLoop.isPending : createLoop.isPending) ||
+    syncSkillBundles.isPending;
   const canSubmit = isLoopFormValid(values) && !isSubmitting;
 
   // Per-step gate for the Next button. The final Create button is gated on the
   // whole form being valid, so jumping between steps can't submit a bad loop.
   const stepComplete = [
-    !!values.name.trim() && !!values.instructions.trim(),
+    !!values.name.trim() &&
+      (values.skill !== null || !!values.instructions.trim()),
     values.triggers.every(isTriggerDraftValid),
     true,
     isLoopFormValid(values),
@@ -124,13 +131,28 @@ export function LoopForm({ loop }: LoopFormProps) {
     if (!canSubmit) return;
     const body = formValuesToLoopWrite(values);
     try {
-      if (isEdit) {
-        const updated = await updateLoop.mutateAsync(body);
-        navigateToLoopDetail(updated.id);
-      } else {
-        const created = await createLoop.mutateAsync(body);
-        navigateToLoopDetail(created.id);
+      const saved = isEdit
+        ? await updateLoop.mutateAsync(body)
+        : await createLoop.mutateAsync(body);
+      // The skill snapshot rides separately from the loop write: a locally
+      // picked skill is bundled and uploaded, removing the skill detaches the
+      // stored bundles, and an unchanged attached snapshot is left alone.
+      const skillSync =
+        values.skill?.kind === "local"
+          ? { loopId: saved.id, skill: values.skill }
+          : values.skill === null && saved.skill_bundles.length > 0
+            ? { loopId: saved.id, skill: null }
+            : null;
+      if (skillSync) {
+        try {
+          await syncSkillBundles.mutateAsync(skillSync);
+        } catch (error) {
+          toast.error("Loop saved, but updating its skill failed", {
+            description: error instanceof Error ? error.message : undefined,
+          });
+        }
       }
+      navigateToLoopDetail(saved.id);
     } catch (error) {
       const safetyLimit =
         error instanceof LoopsApiError ? error.safetyLimit : null;
@@ -188,15 +210,11 @@ export function LoopForm({ loop }: LoopFormProps) {
                   onChange={(e) => patch({ description: e.target.value })}
                 />
               </Field>
-              <Field label="Instructions" required>
-                <TextArea
-                  value={values.instructions}
-                  placeholder="Summarize failing CI runs from the last 24 hours and post the summary to #eng-standup."
-                  disabled={isSubmitting}
-                  className="min-h-[220px] text-[13px] leading-relaxed"
-                  onChange={(e) => patch({ instructions: e.target.value })}
-                />
-              </Field>
+              <LoopInstructionsFields
+                values={values}
+                disabled={isSubmitting}
+                onPatch={patch}
+              />
             </Step>
           ) : null}
 
@@ -515,7 +533,11 @@ function ReviewList({ values }: { values: LoopFormValues }) {
       />
       <ReviewRow
         label="Prompt"
-        value={values.instructions.trim() || "No prompt"}
+        value={
+          values.skill
+            ? buildSkillInstructions(values.skill.name, values.skillContext)
+            : values.instructions.trim() || "No prompt"
+        }
         multiline
       />
       <ReviewRow