feat(server): add skill activation handling for read calls and update related components

Author: TKassis

server/src/agent/events.ts

@@ -4,12 +4,25 @@
  * Pi-internal lifecycle noise so the client contract stays small.
  */
 import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import { skillLabelForRead } from "./skill-label.ts";
 
 export interface ClientFrame {
   type: string;
   [k: string]: unknown;
 }
 
+/** Frontmatter skill name when a `read` call is a skill activation. */
+export function skillFieldFor(
+  toolName: string,
+  args: unknown,
+  sandboxRoot: string,
+): { skill: string } | undefined {
+  if (toolName !== "read") return undefined;
+  const p = (args as { path?: unknown } | null | undefined)?.path;
+  const skill = skillLabelForRead(p, sandboxRoot);
+  return skill ? { skill } : undefined;
+}
+
 /**
  * Rewrite absolute sandbox paths to sandbox-relative ones for display.
  *
@@ -190,6 +203,7 @@ export function toClientFrame(
         toolCallId: ev.toolCallId,
         toolName: ev.toolName,
         args: relativizeSandboxPaths(ev.args, sandboxRoot),
+        ...skillFieldFor(ev.toolName, ev.args, sandboxRoot),
       };
     case "tool_execution_update":
       return { type: "tool_update", toolCallId: ev.toolCallId, toolName: ev.toolName };

server/src/agent/session-history.ts

@@ -6,7 +6,7 @@
  * a reopened transcript renders exactly like it did while streaming — prose,
  * reasoning blocks, and tool activity rows with args and capped results.
  */
-import { relativizeSandboxPaths, type ClientFrame } from "./events.ts";
+import { relativizeSandboxPaths, skillFieldFor, type ClientFrame } from "./events.ts";
 import {
   readRows,
   textOf,
@@ -88,6 +88,7 @@ export function toHistory(file: string, sandboxRoot = ""): HistoryMessage[] {
             toolCallId: call.id,
             toolName: call.name,
             args: relativizeSandboxPaths(call.arguments ?? {}, sandboxRoot),
+            ...skillFieldFor(call.name, call.arguments, sandboxRoot),
           },
           m.timestamp,
         );

server/src/agent/skill-label.ts

@@ -0,0 +1,68 @@
+/**
+ * Resolve a skill's display name from a `read` tool call.
+ *
+ * Pi has no "skill invoked" event: skills are advertised in the system prompt
+ * and the agent activates one by reading its `SKILL.md` (or, for single-file
+ * skills, the `.md` directly under a skills root). When a read targets such a
+ * file, the emitters attach the skill's name to the `tool_start` client frame
+ * (`skill` field) so the chat UI can label the row as a skill activation.
+ *
+ * The authoritative name is the frontmatter `name:` — parsed with Pi's own
+ * skill loader so the label always matches what the system prompt advertises
+ * to the model. The directory (or file) basename is the fallback when the
+ * file is gone or its frontmatter carries no usable name.
+ */
+import path from "node:path";
+import { loadSkillsFromDir } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Path-shape detection + fallback name. Mirrored client-side in
+ * `web/src/lib/skill-invocation.ts` (which acts as the display fallback when
+ * a frame carries no `skill` field).
+ */
+function skillPathName(p: string): string | null {
+  const norm = p.replaceAll("\\", "/");
+  // Directory skill: any <dir>/SKILL.md — the Agent Skills standard names the
+  // skill after the directory holding SKILL.md, wherever it lives.
+  const segments = norm.split("/").filter((s) => s && s !== ".");
+  if (segments.length >= 2 && segments[segments.length - 1] === "SKILL.md") {
+    return segments[segments.length - 2];
+  }
+  // Single-file skill: a .md directly under a Pi skills root (project
+  // `.pi/skills/` or global `~/.pi/agent/skills/`).
+  const single = norm.match(/(?:^|\/)\.pi\/(?:agent\/)?skills\/([^/]+)\.md$/);
+  return single ? single[1] : null;
+}
+
+/** Frontmatter `name:` of the skill file, via Pi's loader; null when the file
+ *  is unreadable or the loader rejects it. */
+function frontmatterName(absFile: string): string | null {
+  try {
+    const { skills } = loadSkillsFromDir({
+      dir: path.dirname(absFile),
+      source: "read",
+    });
+    const target = path.resolve(absFile);
+    const hit = skills.find((s) => path.resolve(s.filePath) === target);
+    return hit?.name || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Skill name for a `read` tool path, or null when the read is not a skill
+ * activation. Relative paths resolve against `sandboxRoot` (the agent cwd).
+ */
+export function skillLabelForRead(
+  rawPath: unknown,
+  sandboxRoot: string,
+): string | null {
+  if (typeof rawPath !== "string") return null;
+  const fallback = skillPathName(rawPath);
+  if (!fallback) return null;
+  const abs = path.isAbsolute(rawPath)
+    ? rawPath
+    : path.join(sandboxRoot, rawPath);
+  return frontmatterName(abs) ?? fallback;
+}

server/test/skill-label.test.ts

@@ -0,0 +1,74 @@
+import fs from "node:fs";
+import path from "node:path";
+import { afterAll, beforeEach, describe, expect, it } from "vitest";
+import { PROJECTS_ROOT } from "../src/config.ts";
+import { ensureProjectExists, resolvePaths } from "../src/projects.ts";
+import { skillLabelForRead } from "../src/agent/skill-label.ts";
+import { skillFieldFor } from "../src/agent/events.ts";
+
+function reset(): void {
+  fs.rmSync(PROJECTS_ROOT, { recursive: true, force: true });
+  fs.mkdirSync(PROJECTS_ROOT, { recursive: true });
+}
+function makeSkill(dir: string, dirName: string, fmName: string): string {
+  const d = path.join(dir, dirName);
+  fs.mkdirSync(d, { recursive: true });
+  const file = path.join(d, "SKILL.md");
+  fs.writeFileSync(
+    file,
+    `---\nname: ${fmName}\ndescription: test skill\n---\n\nBody.\n`,
+    "utf-8",
+  );
+  return file;
+}
+beforeEach(reset);
+afterAll(() => fs.rmSync(PROJECTS_ROOT, { recursive: true, force: true }));
+
+describe("skillLabelForRead", () => {
+  it("returns the frontmatter name, not the directory name", () => {
+    ensureProjectExists("p1");
+    const paths = resolvePaths("p1");
+    makeSkill(paths.skillsDir, "scrnaseq-qc-dir", "single-cell-qc");
+    expect(skillLabelForRead(".pi/skills/scrnaseq-qc-dir/SKILL.md", paths.sandbox)).toBe(
+      "single-cell-qc",
+    );
+  });
+
+  it("resolves absolute paths too", () => {
+    ensureProjectExists("p2");
+    const paths = resolvePaths("p2");
+    const file = makeSkill(paths.skillsDir, "foo", "fancy-foo");
+    expect(skillLabelForRead(file, paths.sandbox)).toBe("fancy-foo");
+  });
+
+  it("falls back to the directory name when the file is gone", () => {
+    ensureProjectExists("p3");
+    const paths = resolvePaths("p3");
+    expect(skillLabelForRead(".pi/skills/vanished/SKILL.md", paths.sandbox)).toBe(
+      "vanished",
+    );
+  });
+
+  it("ignores non-skill reads", () => {
+    ensureProjectExists("p4");
+    const paths = resolvePaths("p4");
+    expect(skillLabelForRead("analysis/results.md", paths.sandbox)).toBeNull();
+    expect(skillLabelForRead(".pi/skills/foo/references/api.md", paths.sandbox)).toBeNull();
+    expect(skillLabelForRead(undefined, paths.sandbox)).toBeNull();
+  });
+});
+
+describe("skillFieldFor", () => {
+  it("attaches the skill field only for read calls on skill files", () => {
+    ensureProjectExists("p5");
+    const paths = resolvePaths("p5");
+    makeSkill(paths.skillsDir, "bar", "better-bar");
+    expect(
+      skillFieldFor("read", { path: ".pi/skills/bar/SKILL.md" }, paths.sandbox),
+    ).toEqual({ skill: "better-bar" });
+    expect(skillFieldFor("read", { path: "notes.md" }, paths.sandbox)).toBeUndefined();
+    expect(
+      skillFieldFor("bash", { command: "cat .pi/skills/bar/SKILL.md" }, paths.sandbox),
+    ).toBeUndefined();
+  });
+});

web/src/components/tool-activity.tsx

@@ -11,6 +11,7 @@ import {
   SearchIcon,
   TerminalIcon,
   UsersIcon,
+  WandSparklesIcon,
   WrenchIcon,
   XIcon,
 } from "lucide-react";
@@ -22,6 +23,7 @@ import {
   CollapsibleTrigger,
 } from "@/components/ui/collapsible";
 import { Spinner } from "@/components/ui/spinner";
+import { skillNameFromRead } from "@/lib/skill-invocation";
 import type { ActivityItem } from "@/lib/use-agent";
 import { cn } from "@/lib/utils";
 
@@ -92,9 +94,13 @@ function fullArgs(args: unknown): string {
 
 function ToolCard({ item }: { item: ActivityItem }) {
   const [open, setOpen] = useState(false);
-  const Icon = iconFor(item.toolName);
-  const name = item.toolName ?? item.label;
-  const summary = summarize(item.toolName, item.args);
+  // A read of a SKILL.md is Pi's skill activation — surface the skill's name
+  // instead of a generic file read (the path stays visible under Input). The
+  // server resolves the frontmatter name; the path-derived name is a fallback.
+  const skill = item.skillName ?? skillNameFromRead(item.toolName, item.args);
+  const Icon = skill ? WandSparklesIcon : iconFor(item.toolName);
+  const name = skill ? "skill" : (item.toolName ?? item.label);
+  const summary = skill ?? summarize(item.toolName, item.args);
   const args = fullArgs(item.args);
   const hasDetail = Boolean(args || item.result);
 

web/src/lib/skill-invocation.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+
+import { skillNameFromRead } from "./skill-invocation";
+
+describe("skillNameFromRead", () => {
+  it("names a project skill read by its directory", () => {
+    expect(skillNameFromRead("read", { path: ".pi/skills/scrnaseq-qc/SKILL.md" })).toBe(
+      "scrnaseq-qc",
+    );
+  });
+
+  it("uses the innermost directory for nested skills", () => {
+    expect(
+      skillNameFromRead("read", { path: ".pi/skills/genomics/variant-calling/SKILL.md" }),
+    ).toBe("variant-calling");
+  });
+
+  it("recognizes SKILL.md outside the .pi tree (e.g. .agents/skills, absolute)", () => {
+    expect(skillNameFromRead("read", { path: ".agents/skills/foo/SKILL.md" })).toBe("foo");
+    expect(
+      skillNameFromRead("read", { path: "/Users/x/.pi/agent/skills/bar/SKILL.md" }),
+    ).toBe("bar");
+  });
+
+  it("recognizes single-file skills directly under a skills root", () => {
+    expect(skillNameFromRead("read", { path: ".pi/skills/quick-notes.md" })).toBe(
+      "quick-notes",
+    );
+    expect(
+      skillNameFromRead("read", { path: "/Users/x/.pi/agent/skills/quick-notes.md" }),
+    ).toBe("quick-notes");
+  });
+
+  it("normalizes Windows separators", () => {
+    expect(skillNameFromRead("read", { path: ".pi\\skills\\foo\\SKILL.md" })).toBe("foo");
+  });
+
+  it("ignores ordinary reads and other tools", () => {
+    expect(skillNameFromRead("read", { path: "analysis/results.md" })).toBeNull();
+    expect(skillNameFromRead("read", { path: ".pi/skills/foo/references/api.md" })).toBeNull();
+    expect(skillNameFromRead("bash", { command: "cat .pi/skills/foo/SKILL.md" })).toBeNull();
+    expect(skillNameFromRead("read", {})).toBeNull();
+    expect(skillNameFromRead(undefined, { path: "x/SKILL.md" })).toBeNull();
+  });
+
+  it("does not treat a bare root SKILL.md as a skill", () => {
+    expect(skillNameFromRead("read", { path: "SKILL.md" })).toBeNull();
+    expect(skillNameFromRead("read", { path: "./SKILL.md" })).toBeNull();
+  });
+});

web/src/lib/skill-invocation.ts

@@ -0,0 +1,34 @@
+/**
+ * Detect a skill activation from a `read` tool call.
+ *
+ * Pi has no dedicated "skill invoked" event: available skills are listed in
+ * the system prompt and the agent activates one by reading its `SKILL.md`
+ * (or, for single-file skills, the `.md` directly under a skills root).
+ * Recognizing those reads lets the chat UI label the row with the skill's
+ * name instead of a generic file read.
+ *
+ * The authoritative name is the frontmatter `name:`, which the server
+ * resolves and attaches to the frame (`skill` field / ActivityItem.skillName
+ * — see server/src/agent/skill-label.ts). This helper is the display
+ * fallback for frames without it, deriving a name from the path (directory
+ * containing `SKILL.md`, or the file's basename for single-file skills).
+ */
+export function skillNameFromRead(
+  toolName: string | undefined,
+  args: unknown,
+): string | null {
+  if (toolName !== "read" || !args || typeof args !== "object") return null;
+  const raw = (args as Record<string, unknown>).path;
+  if (typeof raw !== "string") return null;
+  const path = raw.replaceAll("\\", "/");
+  // Directory skill: any <dir>/SKILL.md — the Agent Skills standard names the
+  // skill after the directory holding SKILL.md, wherever it lives.
+  const segments = path.split("/").filter((s) => s && s !== ".");
+  if (segments.length >= 2 && segments[segments.length - 1] === "SKILL.md") {
+    return segments[segments.length - 2];
+  }
+  // Single-file skill: a .md directly under a Pi skills root (project
+  // `.pi/skills/` or global `~/.pi/agent/skills/`).
+  const single = path.match(/(?:^|\/)\.pi\/(?:agent\/)?skills\/([^/]+)\.md$/);
+  return single ? single[1] : null;
+}

web/src/lib/use-agent.ts

@@ -18,6 +18,8 @@ export interface ActivityItem {
   timestamp: number;
   /** Raw tool name (e.g. "bash", "write") for icon + summary rendering. */
   toolName?: string;
+  /** Frontmatter skill name when this read is a skill activation (server-resolved). */
+  skillName?: string;
   /** Tool arguments captured from tool_start (e.g. the bash command). */
   args?: unknown;
   /** Tool result text captured from tool_end (truncated server-side). */
@@ -70,6 +72,8 @@ export interface AgentFrame {
   type: string;
   delta?: string;
   toolName?: string;
+  /** Frontmatter skill name attached to tool_start when the read is a skill activation. */
+  skill?: string;
   toolCallId?: string;
   isError?: boolean;
   message?: string;
@@ -123,6 +127,7 @@ export function applyFrameToMessage(
             status: "running" as const,
             timestamp: now,
             toolName: frame.toolName ? String(frame.toolName) : undefined,
+            skillName: typeof frame.skill === "string" ? frame.skill : undefined,
             args: frame.args,
           },
         ].slice(-MAX_ACTIVITY_ITEMS),