feat(skills): auto-bundle declared skill dependencies in cloud runs

Author: tatoalo

apps/code/src/renderer/di/bindings.ts

@@ -59,6 +59,8 @@ import {
   type BundleLocalSkill,
   CLOUD_ARTIFACT_BUNDLE_LOCAL_SKILL,
   CLOUD_ARTIFACT_READ_FILE_AS_BASE64,
+  CLOUD_ARTIFACT_RESOLVE_SKILL_DEPENDENCIES,
+  type ResolveSkillBundleDependencies,
 } from "@posthog/core/sessions/cloudArtifactIdentifiers";
 import {
   LOCAL_HANDOFF_DIALOG,
@@ -272,6 +274,7 @@ export interface RendererBindings {
   [REVERT_HUNK_SERVICE]: RevertHunkService;
   [SKILLS_WORKSPACE_CLIENT]: SkillsWorkspaceClient;
   [CLOUD_ARTIFACT_BUNDLE_LOCAL_SKILL]: BundleLocalSkill;
+  [CLOUD_ARTIFACT_RESOLVE_SKILL_DEPENDENCIES]: ResolveSkillBundleDependencies;
   [CLOUD_ARTIFACT_READ_FILE_AS_BASE64]: ReadFileAsBase64;
   [LLM_GATEWAY_SERVICE]: LlmGatewayService;
   [TITLE_GENERATOR_FILE_READ_CLIENT]: FileReadClient;

apps/code/src/renderer/di/container.ts

@@ -32,6 +32,7 @@ import type { LlmMessage } from "@posthog/core/llm-gateway/schemas";
 import {
   CLOUD_ARTIFACT_BUNDLE_LOCAL_SKILL,
   CLOUD_ARTIFACT_READ_FILE_AS_BASE64,
+  CLOUD_ARTIFACT_RESOLVE_SKILL_DEPENDENCIES,
 } from "@posthog/core/sessions/cloudArtifactIdentifiers";
 import {
   LOCAL_HANDOFF_DIALOG,
@@ -393,6 +394,11 @@ container
   .toConstantValue((skillBundleRef) =>
     hostTrpcClient.skills.bundleLocal.query(skillBundleRef),
   );
+container
+  .bind(CLOUD_ARTIFACT_RESOLVE_SKILL_DEPENDENCIES)
+  .toConstantValue((skillBundleRefs) =>
+    hostTrpcClient.skills.resolveDependencies.query(skillBundleRefs),
+  );
 container.bind(LLM_GATEWAY_SERVICE).toConstantValue({
   prompt: (
     messages: LlmMessage[],

packages/core/src/sessions/cloudArtifactIdentifiers.ts

@@ -67,6 +67,14 @@ export type BundleLocalSkill = (
   skillBundleRef: CloudSkillBundleRef,
 ) => Promise<LocalSkillBundle>;
 
+/**
+ * Expand tagged skill refs to include their transitively-declared dependency
+ * skills so a cloud run gets every skill it needs, not just the tagged one.
+ */
+export type ResolveSkillBundleDependencies = (
+  skillBundleRefs: CloudSkillBundleRef[],
+) => Promise<CloudSkillBundleRef[]>;
+
 export const CLOUD_ARTIFACT_SERVICE = Symbol.for(
   "posthog.core.sessions.cloudArtifactService",
 );
@@ -76,3 +84,6 @@ export const CLOUD_ARTIFACT_READ_FILE_AS_BASE64 = Symbol.for(
 export const CLOUD_ARTIFACT_BUNDLE_LOCAL_SKILL = Symbol.for(
   "posthog.core.sessions.cloudArtifactBundleLocalSkill",
 );
+export const CLOUD_ARTIFACT_RESOLVE_SKILL_DEPENDENCIES = Symbol.for(
+  "posthog.core.sessions.cloudArtifactResolveSkillDependencies",
+);

packages/core/src/sessions/cloudArtifactService.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it, vi } from "vitest";
 import type {
   BundleLocalSkill,
   CloudArtifactClient,
+  ResolveSkillBundleDependencies,
 } from "./cloudArtifactIdentifiers";
 import {
   CLOUD_ATTACHMENT_MAX_SIZE_BYTES,
@@ -18,6 +19,8 @@ function makeClient(): CloudArtifactClient {
   };
 }
 
+const passthroughDeps: ResolveSkillBundleDependencies = async (refs) => refs;
+
 const bundleLocalSkill: BundleLocalSkill = vi.fn(async (skillBundleRef) => {
   const contentBase64 = btoa("skill-bundle");
   return {
@@ -34,7 +37,11 @@ const bundleLocalSkill: BundleLocalSkill = vi.fn(async (skillBundleRef) => {
 
 describe("CloudArtifactService", () => {
   it("returns empty ids when no file paths are provided", async () => {
-    const service = new CloudArtifactService(vi.fn(), bundleLocalSkill);
+    const service = new CloudArtifactService(
+      vi.fn(),
+      bundleLocalSkill,
+      passthroughDeps,
+    );
     expect(
       await service.uploadRunAttachments(makeClient(), "t", "r", []),
     ).toEqual([]);
@@ -46,6 +53,7 @@ describe("CloudArtifactService", () => {
     const service = new CloudArtifactService(
       vi.fn().mockResolvedValue(base64),
       bundleLocalSkill,
+      passthroughDeps,
     );
 
     await expect(
@@ -61,6 +69,7 @@ describe("CloudArtifactService", () => {
     const service = new CloudArtifactService(
       vi.fn().mockResolvedValue(base64),
       bundleLocalSkill,
+      passthroughDeps,
     );
 
     await expect(
@@ -76,6 +85,7 @@ describe("CloudArtifactService", () => {
     const service = new CloudArtifactService(
       vi.fn().mockResolvedValue(null),
       bundleLocalSkill,
+      passthroughDeps,
     );
 
     await expect(
@@ -93,6 +103,7 @@ describe("CloudArtifactService", () => {
     const service = new CloudArtifactService(
       vi.fn().mockResolvedValue(base64),
       bundleLocalSkill,
+      passthroughDeps,
     );
 
     const client = makeClient();
@@ -127,7 +138,11 @@ describe("CloudArtifactService", () => {
     const fetchMock = vi
       .spyOn(globalThis, "fetch")
       .mockResolvedValue({ ok: true } as Response);
-    const service = new CloudArtifactService(vi.fn(), bundleLocalSkill);
+    const service = new CloudArtifactService(
+      vi.fn(),
+      bundleLocalSkill,
+      passthroughDeps,
+    );
     const client = makeClient();
 
     (
@@ -173,4 +188,52 @@ describe("CloudArtifactService", () => {
     );
     fetchMock.mockRestore();
   });
+
+  it("uploads dependency skills the resolver adds to a tagged skill", async () => {
+    const fetchMock = vi
+      .spyOn(globalThis, "fetch")
+      .mockResolvedValue({ ok: true } as Response);
+    const resolveDeps: ResolveSkillBundleDependencies = vi.fn(async (refs) => [
+      ...refs,
+      { name: "dep-skill", source: "user", path: "/tmp/dep-skill" },
+    ]);
+    const service = new CloudArtifactService(
+      vi.fn(),
+      bundleLocalSkill,
+      resolveDeps,
+    );
+    const client = makeClient();
+
+    (
+      client.prepareTaskRunArtifactUploads as ReturnType<typeof vi.fn>
+    ).mockImplementation((_taskId, _runId, uploads: unknown[]) =>
+      uploads.map((_upload, index) => ({
+        id: `prep-${index}`,
+        name: `skill-${index}.zip`,
+        type: "skill_bundle",
+        size: 12,
+        presigned_post: { url: "https://s3/upload", fields: { key: "k" } },
+      })),
+    );
+    (
+      client.finalizeTaskRunArtifactUploads as ReturnType<typeof vi.fn>
+    ).mockResolvedValue([{ id: "primary-1" }, { id: "dep-1" }]);
+
+    const ids = await service.uploadRunAttachments(
+      client,
+      "task-1",
+      "run-1",
+      [],
+      [{ name: "primary-skill", source: "user", path: "/tmp/primary-skill" }],
+    );
+
+    expect(resolveDeps).toHaveBeenCalledWith([
+      { name: "primary-skill", source: "user", path: "/tmp/primary-skill" },
+    ]);
+    expect(bundleLocalSkill).toHaveBeenCalledWith(
+      expect.objectContaining({ name: "dep-skill" }),
+    );
+    expect(ids).toEqual(["primary-1", "dep-1"]);
+    fetchMock.mockRestore();
+  });
 });

packages/core/src/sessions/cloudArtifactService.ts

@@ -5,11 +5,13 @@ import {
   type BundleLocalSkill,
   CLOUD_ARTIFACT_BUNDLE_LOCAL_SKILL,
   CLOUD_ARTIFACT_READ_FILE_AS_BASE64,
+  CLOUD_ARTIFACT_RESOLVE_SKILL_DEPENDENCIES,
   type CloudArtifactClient,
   type CloudArtifactUploadRequest,
   type CloudSkillBundleRef,
   type FinalizedCloudArtifact,
   type PreparedCloudArtifact,
+  type ResolveSkillBundleDependencies,
 } from "./cloudArtifactIdentifiers";
 
 const ATTACHMENT_SOURCE = "posthog_code";
@@ -123,6 +125,8 @@ export class CloudArtifactService {
     private readonly readFileAsBase64: ReadFileAsBase64,
     @inject(CLOUD_ARTIFACT_BUNDLE_LOCAL_SKILL)
     private readonly bundleLocalSkill: BundleLocalSkill,
+    @inject(CLOUD_ARTIFACT_RESOLVE_SKILL_DEPENDENCIES)
+    private readonly resolveSkillBundleDependencies: ResolveSkillBundleDependencies,
   ) {}
 
   async uploadTaskStagedAttachments(
@@ -225,8 +229,15 @@ export class CloudArtifactService {
   private async loadCloudSkillBundles(
     skillBundleRefs: CloudSkillBundleRef[],
   ): Promise<LoadedCloudAttachment[]> {
+    if (skillBundleRefs.length === 0) {
+      return [];
+    }
+    // Pull in dependency skills the tagged ones declare, so a skill that needs
+    // another arrives in the sandbox together with it.
+    const expandedRefs =
+      await this.resolveSkillBundleDependencies(skillBundleRefs);
     return Promise.all(
-      skillBundleRefs.map(async (skillBundleRef) => {
+      expandedRefs.map(async (skillBundleRef) => {
         const bundle = await this.bundleLocalSkill(skillBundleRef);
         const bytes = base64ToUint8Array(bundle.contentBase64);
         if (bytes.byteLength !== bundle.size) {

packages/host-router/src/routers/skills.router.ts

@@ -14,6 +14,8 @@ import {
   readSkillFileInput,
   readSkillFileOutput,
   renameSkillFileInput,
+  resolveSkillDependenciesInput,
+  resolveSkillDependenciesOutput,
   saveSkillFileInput,
   saveSkillManifestInput,
   skillContentsInput,
@@ -44,6 +46,14 @@ export const skillsRouter = router({
     .query(({ ctx, input }) =>
       ctx.container.get<SkillsService>(SKILLS_SERVICE).bundleLocalSkill(input),
     ),
+  resolveDependencies: publicProcedure
+    .input(resolveSkillDependenciesInput)
+    .output(resolveSkillDependenciesOutput)
+    .query(({ ctx, input }) =>
+      ctx.container
+        .get<SkillsService>(SKILLS_SERVICE)
+        .resolveSkillBundleDependencies(input),
+    ),
   contents: publicProcedure
     .input(skillContentsInput)
     .output(skillContentsOutput)

packages/ui/src/features/sessions/sessionServiceHost.test.ts

@@ -47,6 +47,7 @@ const mockTrpcFs = vi.hoisted(() => ({
 const mockTrpcSkills = vi.hoisted(() => ({
   list: { query: vi.fn() },
   bundleLocal: { query: vi.fn() },
+  resolveDependencies: { query: vi.fn() },
 }));
 
 const mockTrpcHandoff = vi.hoisted(() => ({
@@ -427,6 +428,10 @@ describe("SessionService", () => {
     mockTrpcSkills.bundleLocal.query.mockRejectedValue(
       new Error("Unexpected skill bundle upload"),
     );
+    // Dependency resolution is a no-op passthrough by default (no declared deps).
+    mockTrpcSkills.resolveDependencies.query.mockImplementation(
+      async (refs: unknown) => refs,
+    );
     mockTrpcHandoff.preflightToCloud.query.mockResolvedValue({
       canHandoff: true,
     });

packages/ui/src/features/sessions/sessionServiceHost.ts

@@ -62,6 +62,7 @@ function buildSessionServiceDeps(): SessionServiceDeps {
   const cloudArtifactService = new CloudArtifactService(
     (filePath) => trpc.fs.readFileAsBase64.query({ filePath }),
     (skillBundleRef) => trpc.skills.bundleLocal.query(skillBundleRef),
+    (skillBundleRefs) => trpc.skills.resolveDependencies.query(skillBundleRefs),
   );
 
   return {

packages/workspace-server/src/services/skills/parse-skill-frontmatter.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import { parseSkillDependencies } from "./parse-skill-frontmatter";
+
+describe("parseSkillDependencies", () => {
+  it.each([
+    ["absent", `---\nname: a\ndescription: d\n---\nbody`, []],
+    [
+      "block sequence",
+      `---\nname: a\ndependencies:\n  - one\n  - two\n---\nbody`,
+      ["one", "two"],
+    ],
+    [
+      "flow sequence",
+      `---\nname: a\ndependencies: [one, two]\n---\nbody`,
+      ["one", "two"],
+    ],
+    [
+      "quoted entries",
+      `---\nname: a\ndependencies:\n  - "one"\n  - 'two'\n---\nbody`,
+      ["one", "two"],
+    ],
+    ["no frontmatter", `just a body`, []],
+  ])("parses %s", (_label, content, expected) => {
+    expect(parseSkillDependencies(content)).toEqual(expected);
+  });
+});

packages/workspace-server/src/services/skills/parse-skill-frontmatter.ts

@@ -21,6 +21,64 @@ export function parseSkillFrontmatter(
   return { name, description };
 }
 
+/**
+ * Extracts the optional `dependencies` list from a SKILL.md frontmatter — the
+ * names of other skills this skill needs. Supports flow (`dependencies: [a, b]`)
+ * and block (`dependencies:\n  - a\n  - b`) sequences. Returns [] when absent.
+ */
+export function parseSkillDependencies(content: string): string[] {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return [];
+  return extractYamlList(match[1], "dependencies");
+}
+
+function unquoteYamlScalar(value: string): string {
+  if (
+    (value.startsWith("'") && value.endsWith("'")) ||
+    (value.startsWith('"') && value.endsWith('"'))
+  ) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+function extractYamlList(yaml: string, key: string): string[] {
+  const lines = yaml.split("\n");
+  // Match `key:` at the start of the line with a literal prefix rather than a
+  // RegExp built from the (caller-supplied) key — avoids a metacharacter
+  // footgun if this helper is ever reused with a key like `my.key`.
+  const prefix = `${key}:`;
+
+  for (let i = 0; i < lines.length; i++) {
+    if (!lines[i].startsWith(prefix)) continue;
+
+    const inline = lines[i].slice(prefix.length).trim();
+    // Flow sequence or comma list: `[a, b]` / `a, b`
+    if (inline) {
+      const stripped = inline.replace(/^\[/, "").replace(/\]$/, "");
+      return stripped
+        .split(",")
+        .map((entry) => unquoteYamlScalar(entry.trim()))
+        .filter((entry) => entry.length > 0);
+    }
+
+    // Block sequence: subsequent `- item` lines
+    const items: string[] = [];
+    for (let j = i + 1; j < lines.length; j++) {
+      const itemMatch = lines[j].match(/^\s*-\s+(.*)$/);
+      if (!itemMatch) {
+        if (/^\s*$/.test(lines[j])) continue;
+        break;
+      }
+      const value = unquoteYamlScalar(itemMatch[1].trim());
+      if (value) items.push(value);
+    }
+    return items;
+  }
+
+  return [];
+}
+
 function extractYamlValue(yaml: string, key: string): string | null {
   const lines = yaml.split("\n");