feat(skills): live refresh from the filesystem

- SkillsService.watchSkills merges @parcel/watcher streams over
  ~/.claude/skills (created if missing) and each open workspace
  folder's .claude/skills into a single debounced "skills changed"
  event stream. One failing root cannot break the others.
- skills.watch tRPC subscription using the async-generator pattern,
  with the watcher bound alongside SkillsService in skills.module.
- useSkillsWatcher subscribes once at the SkillsView boundary and
  invalidates every skills query on change; the 30s staleTime
  fallbacks are gone.

Generated-By: PostHog Code
Task-Id: f4e84f1a-19c9-490c-9b98-47787a7dddcf

Author: k11kirky

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

@@ -83,4 +83,10 @@ export const skillsRouter = router({
         .get<SkillsService>(SKILLS_SERVICE)
         .deleteSkill(input.skillPath),
     ),
+  watch: publicProcedure.subscription(async function* (opts) {
+    const service = opts.ctx.container.get<SkillsService>(SKILLS_SERVICE);
+    for await (const event of service.watchSkills(opts.signal)) {
+      yield event;
+    }
+  }),
 });

packages/ui/src/features/skills/SkillsView.tsx

@@ -16,11 +16,13 @@ import { SkillSection, SOURCE_CONFIG } from "./SkillCard";
 import { SkillDetailPanel } from "./SkillDetailPanel";
 import { useSkillsSidebarStore } from "./skillsSidebarStore";
 import { useSkills } from "./useSkills";
+import { useSkillsWatcher } from "./useSkillsWatcher";
 
 const SOURCE_ORDER: SkillSource[] = ["user", "marketplace", "repo", "bundled"];
 
 export function SkillsView() {
   const { data: skills = [], isLoading } = useSkills();
+  useSkillsWatcher();
 
   const [selectedPath, setSelectedPath] = useState<string | null>(null);
   const [searchQuery, setSearchQuery] = useState("");

packages/ui/src/features/skills/useSkillContents.ts

@@ -3,17 +3,15 @@ import { useQuery } from "@tanstack/react-query";
 
 export function useSkillContents(skillPath: string) {
   const trpc = useHostTRPC();
-  return useQuery(
-    trpc.skills.contents.queryOptions({ skillPath }, { staleTime: 30_000 }),
-  );
+  return useQuery(trpc.skills.contents.queryOptions({ skillPath }));
 }
 
 export function useSkillFile(skillPath: string, filePath: string | null) {
   const trpc = useHostTRPC();
   return useQuery(
     trpc.skills.readFile.queryOptions(
       { skillPath, filePath: filePath ?? "" },
-      { enabled: filePath !== null, staleTime: 30_000 },
+      { enabled: filePath !== null },
     ),
   );
 }

packages/ui/src/features/skills/useSkills.ts

@@ -3,7 +3,5 @@ import { useQuery } from "@tanstack/react-query";
 
 export function useSkills() {
   const trpc = useHostTRPC();
-  return useQuery(
-    trpc.skills.list.queryOptions(undefined, { staleTime: 30_000 }),
-  );
+  return useQuery(trpc.skills.list.queryOptions());
 }

packages/ui/src/features/skills/useSkillsWatcher.ts

@@ -0,0 +1,19 @@
+import { useHostTRPC } from "@posthog/host-router/react";
+import { useQueryClient } from "@tanstack/react-query";
+import { useSubscription } from "@trpc/tanstack-react-query";
+
+/**
+ * Invalidates every skills query when the writable skill roots change on
+ * disk, so external edits (terminals, agent sessions) appear live.
+ */
+export function useSkillsWatcher() {
+  const trpc = useHostTRPC();
+  const queryClient = useQueryClient();
+  useSubscription(
+    trpc.skills.watch.subscriptionOptions(undefined, {
+      onData: () => {
+        void queryClient.invalidateQueries(trpc.skills.pathFilter());
+      },
+    }),
+  );
+}

packages/workspace-server/src/services/skills/schemas.ts

@@ -74,6 +74,10 @@ export const deleteSkillInput = z.object({
   skillPath: z.string(),
 });
 
+export const skillsChangedEvent = z.object({
+  changed: z.literal(true),
+});
+
 export type SkillInfo = z.infer<typeof skillInfo>;
 export type SkillScope = z.infer<typeof skillScope>;
 export type CreateSkillInput = z.infer<typeof createSkillInput>;

packages/workspace-server/src/services/skills/skills.module.ts

@@ -1,7 +1,12 @@
 import { ContainerModule } from "inversify";
+import { WATCHER_SERVICE } from "../../di/tokens";
+import { WatcherService } from "../watcher/service";
 import { SKILLS_SERVICE } from "./identifiers";
 import { SkillsService } from "./skills";
 
 export const skillsModule = new ContainerModule(({ bind }) => {
   bind(SKILLS_SERVICE).to(SkillsService).inSingletonScope();
+  // SkillsService watches the writable skill roots. Hosts that load this
+  // module (Electron main) do not otherwise bind WatcherService.
+  bind(WATCHER_SERVICE).to(WatcherService).inSingletonScope();
 });

packages/workspace-server/src/services/skills/skills.test.ts

@@ -4,6 +4,7 @@ import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import type { FoldersService } from "../folders/folders";
 import type { PosthogPluginService } from "../posthog-plugin/posthog-plugin";
+import { WatcherService } from "../watcher/service";
 import { SkillsService } from "./skills";
 
 let root: string;
@@ -18,7 +19,7 @@ function makeService(): SkillsService {
   const folders = {
     getFolders: async () => [{ path: folderPath, name: "my-repo" }],
   } as unknown as FoldersService;
-  return new SkillsService(plugin, folders);
+  return new SkillsService(plugin, folders, new WatcherService());
 }
 
 async function createSkill(
@@ -180,6 +181,45 @@ describe("readSkillFile", () => {
   });
 });
 
+describe("watchSkillDirs", () => {
+  it(
+    "emits a debounced change event when a watched dir changes",
+    { timeout: 15_000 },
+    async () => {
+      const service = makeService();
+      const controller = new AbortController();
+      const generator = service.watchSkillDirs(
+        [repoSkillsDir],
+        controller.signal,
+      );
+
+      const firstEvent = generator.next();
+      // Give the native watcher a moment to attach before mutating the dir.
+      await new Promise((r) => setTimeout(r, 500));
+      await createSkill(repoSkillsDir, "watched-skill");
+
+      const result = await Promise.race([
+        firstEvent,
+        new Promise<never>((_, reject) =>
+          setTimeout(
+            () => reject(new Error("timed out waiting for change event")),
+            10_000,
+          ),
+        ),
+      ]);
+      expect(result).toEqual({ value: { changed: true }, done: false });
+
+      controller.abort();
+      await generator.return(undefined);
+    },
+  );
+
+  it("finishes immediately with no directories", async () => {
+    const generator = makeService().watchSkillDirs([]);
+    expect(await generator.next()).toEqual({ value: undefined, done: true });
+  });
+});
+
 describe("createSkill", () => {
   it("scaffolds a directory with a parseable SKILL.md", async () => {
     const service = makeService();

packages/workspace-server/src/services/skills/skills.ts

@@ -2,10 +2,12 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { inject, injectable } from "inversify";
+import { WATCHER_SERVICE } from "../../di/tokens";
 import type { FoldersService } from "../folders/folders";
 import { FOLDERS_SERVICE } from "../folders/identifiers";
 import { POSTHOG_PLUGIN_SERVICE } from "../posthog-plugin/identifiers";
 import type { PosthogPluginService } from "../posthog-plugin/posthog-plugin";
+import type { WatcherService } from "../watcher/service";
 import { parseSkillFrontmatter } from "./parse-skill-frontmatter";
 import type {
   CreateSkillInput,
@@ -22,6 +24,7 @@ import { serializeSkillMarkdown } from "./write-skill-frontmatter";
 
 const MAX_SKILL_FILES = 500;
 const MAX_SKILL_FILE_BYTES = 2 * 1024 * 1024;
+const SKILLS_WATCH_DEBOUNCE_MS = 300;
 const SKILL_DIR_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
 const MAX_SKILL_DIR_NAME_LENGTH = 64;
 
@@ -45,6 +48,8 @@ export class SkillsService {
     private readonly plugin: PosthogPluginService,
     @inject(FOLDERS_SERVICE)
     private readonly folders: FoldersService,
+    @inject(WATCHER_SERVICE)
+    private readonly watcher: WatcherService,
   ) {}
 
   async listSkills(): Promise<SkillInfo[]> {
@@ -170,6 +175,68 @@ export class SkillsService {
     await fs.promises.rm(skillDir, { recursive: true, force: true });
   }
 
+  /**
+   * Emits a debounced "skills changed" event whenever anything inside the
+   * writable skill roots changes on disk (external editors, agent sessions,
+   * `touch` from a terminal, ...).
+   */
+  async *watchSkills(signal?: AbortSignal): AsyncGenerator<{ changed: true }> {
+    const userRoot = path.join(os.homedir(), ".claude", "skills");
+    // The user root is ours to create; repo roots are only watched if present.
+    await fs.promises.mkdir(userRoot, { recursive: true }).catch(() => {});
+    const folders = await this.folders.getFolders();
+    const dirs = [
+      userRoot,
+      ...folders.map((f) => path.join(f.path, ".claude", "skills")),
+    ].filter((dir) => fs.existsSync(dir));
+
+    yield* this.watchSkillDirs(dirs, signal);
+  }
+
+  /** Merges watchers over the given directories into one debounced stream. */
+  async *watchSkillDirs(
+    dirs: string[],
+    signal?: AbortSignal,
+  ): AsyncGenerator<{ changed: true }> {
+    if (dirs.length === 0) return;
+
+    let pending = false;
+    let finished = 0;
+    let notify: (() => void) | undefined;
+    const wake = () => notify?.();
+
+    for (const dir of dirs) {
+      void (async () => {
+        try {
+          for await (const _batch of this.watcher.watch(dir, {}, signal)) {
+            pending = true;
+            wake();
+          }
+        } catch {
+          // A failed watcher on one root must not break the others.
+        } finally {
+          finished++;
+          wake();
+        }
+      })();
+    }
+
+    while (finished < dirs.length && !signal?.aborted) {
+      if (!pending) {
+        await new Promise<void>((resolve) => {
+          notify = resolve;
+        });
+        notify = undefined;
+        continue;
+      }
+      // Collapse bursts of file events into a single notification.
+      await delay(SKILLS_WATCH_DEBOUNCE_MS, signal);
+      if (signal?.aborted) return;
+      pending = false;
+      yield { changed: true };
+    }
+  }
+
   private async getSkillRoots(): Promise<SkillRoot[]> {
     const pluginPath = this.plugin.getPluginPath();
     const folders = await this.folders.getFolders();
@@ -273,6 +340,18 @@ function validateSkillDirName(name: string): void {
   }
 }
 
+function delay(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(done, ms);
+    function done() {
+      signal?.removeEventListener("abort", done);
+      clearTimeout(timer);
+      resolve();
+    }
+    signal?.addEventListener("abort", done, { once: true });
+  });
+}
+
 function resolveSkillFilePath(skillDir: string, filePath: string): string {
   const resolved = path.resolve(skillDir, filePath);
   if (resolved === skillDir || !resolved.startsWith(skillDir + path.sep)) {