@stigmer/runner 3.15.0 → 3.15.2-dev.20260913223433

package/src/shared/__tests__/skill-writer.test.ts

@@ -1,372 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { mkdtempSync, readFileSync, existsSync, rmSync } from "node:fs";
-import { join } from "node:path";
-import { tmpdir } from "node:os";
-import { ConnectError, Code } from "@connectrpc/connect";
-import {
-  mergeSkillRefs,
-  fetchSkillsByRefs,
-  mountSkills,
-  generatePromptSection,
-  generateAlsoAvailableSection,
-} from "../skill-writer.js";
-import type { Skill } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
-import type { ApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
-import { buildZip } from "@stigmer/zip-structure/testing";
-
-// ─── Helpers ─────────────────────────────────────────────────────────────
-
-function makeSkill(overrides: {
-  id?: string;
-  name?: string;
-  slug?: string;
-  org?: string;
-  description?: string;
-  skillMd?: string;
-  artifactStorageKey?: string;
-  versionHash?: string;
-} = {}): Skill {
-  return {
-    metadata: {
-      id: overrides.id ?? "skill-id-1",
-      name: overrides.name ?? overrides.slug ?? "test-skill",
-      slug: overrides.slug ?? "test-skill",
-      org: overrides.org ?? "test-org",
-    },
-    spec: {
-      name: overrides.name ?? "test-skill",
-      description: overrides.description ?? "A test skill",
-      skillMd: overrides.skillMd ?? "# Test Skill\n\nDoes testing.",
-      tag: "",
-    },
-    status: {
-      artifactStorageKey: overrides.artifactStorageKey ?? "",
-      versionHash: overrides.versionHash ?? "abc123",
-      state: "active",
-    },
-  } as any;
-}
-
-function makeRef(slug: string, org = "test-org"): ApiResourceReference {
-  return { slug, org, kind: 43 } as any;
-}
-
-/** A server that predates the transfer lane (#675) answers the mint RPC
- * with UNIMPLEMENTED, pinning these tests to the unary fallback. */
-function makeMockClient(overrides: Record<string, unknown> = {}) {
-  return {
-    getSkillByReference: vi.fn().mockImplementation((ref: any) =>
-      Promise.resolve(makeSkill({ slug: ref.slug, name: ref.slug })),
-    ),
-    getSkillArtifact: vi.fn().mockResolvedValue({ artifact: new Uint8Array(0) }),
-    getSkillArtifactDownloadUrl: vi.fn().mockRejectedValue(
-      new ConnectError("unimplemented", Code.Unimplemented),
-    ),
-    ...overrides,
-  } as any;
-}
-
-// ─── mergeSkillRefs ──────────────────────────────────────────────────────
-
-describe("mergeSkillRefs", () => {
-  it("returns empty for no refs", () => {
-    expect(mergeSkillRefs([], [])).toEqual([]);
-  });
-
-  it("returns agent refs when no session refs", () => {
-    const refs = [makeRef("skill-a"), makeRef("skill-b")];
-    const result = mergeSkillRefs(refs, []);
-    expect(result).toHaveLength(2);
-    expect(result.map(r => r.slug)).toEqual(["skill-a", "skill-b"]);
-  });
-
-  it("deduplicates by slug with session winning", () => {
-    const agentRefs = [makeRef("skill-a", "org1")];
-    const sessionRefs = [makeRef("skill-a", "org2")];
-    const result = mergeSkillRefs(agentRefs, sessionRefs);
-    expect(result).toHaveLength(1);
-    expect(result[0].org).toBe("org2");
-  });
-
-  it("unions unique skills from both sources", () => {
-    const agentRefs = [makeRef("skill-a")];
-    const sessionRefs = [makeRef("skill-b")];
-    const result = mergeSkillRefs(agentRefs, sessionRefs);
-    expect(result).toHaveLength(2);
-  });
-});
-
-// ─── fetchSkillsByRefs ───────────────────────────────────────────────────
-
-describe("fetchSkillsByRefs", () => {
-  it("returns empty for no refs", async () => {
-    const client = makeMockClient();
-    const result = await fetchSkillsByRefs(client, []);
-    expect(result).toEqual([]);
-    expect(client.getSkillByReference).not.toHaveBeenCalled();
-  });
-
-  it("fetches all skills by reference", async () => {
-    const client = makeMockClient();
-    const refs = [makeRef("skill-a"), makeRef("skill-b")];
-    const result = await fetchSkillsByRefs(client, refs);
-    expect(result).toHaveLength(2);
-    expect(client.getSkillByReference).toHaveBeenCalledTimes(2);
-  });
-
-  it("skips failed fetches gracefully", async () => {
-    const client = makeMockClient({
-      getSkillByReference: vi.fn()
-        .mockResolvedValueOnce(makeSkill({ name: "good", slug: "good" }))
-        .mockRejectedValueOnce(new Error("Not found")),
-    });
-    const refs = [makeRef("good"), makeRef("bad")];
-    const result = await fetchSkillsByRefs(client, refs);
-    expect(result).toHaveLength(1);
-    expect(result[0].spec!.name).toBe("good");
-  });
-});
-
-// ─── mountSkills ─────────────────────────────────────────────────────────
-
-describe("mountSkills", () => {
-  let platformDir: string;
-
-  beforeEach(() => {
-    platformDir = mkdtempSync(join(tmpdir(), "skill-writer-platform-"));
-  });
-
-  afterEach(() => {
-    rmSync(platformDir, { recursive: true, force: true });
-  });
-
-  it("writes SKILL.md and returns agent-visible paths keyed by skill id", async () => {
-    const client = makeMockClient();
-    const skills = [makeSkill({ name: "calculator", skillMd: "# Calculator\n\nAdds numbers." })];
-    const result = await mountSkills(client, skills, platformDir);
-
-    expect(result.paths.get("skill-id-1")).toBe(".stigmer/skills/calculator");
-    expect(readFileSync(join(platformDir, "skills", "calculator", "SKILL.md"), "utf-8"))
-      .toBe("# Calculator\n\nAdds numbers.");
-  });
-
-  it("extracts artifact files alongside SKILL.md", async () => {
-    const artifact = buildZip([
-      { name: "SKILL.md", content: "# Stale zip copy" },
-      { name: "references/schema.md", content: "schema" },
-    ]);
-    const client = makeMockClient({
-      getSkillArtifact: vi.fn().mockResolvedValue({ artifact }),
-    });
-    const skills = [makeSkill({
-      name: "db-skill",
-      skillMd: "# Authoritative",
-      artifactStorageKey: "artifacts/db.zip",
-    })];
-    await mountSkills(client, skills, platformDir);
-
-    const skillDir = join(platformDir, "skills", "db-skill");
-    expect(readFileSync(join(skillDir, "SKILL.md"), "utf-8")).toBe("# Authoritative");
-    expect(readFileSync(join(skillDir, "references", "schema.md"), "utf-8")).toBe("schema");
-  });
-
-  it("handles multiple skills", async () => {
-    const client = makeMockClient();
-    const skills = [
-      makeSkill({ id: "id-1", name: "skill-a", skillMd: "# A" }),
-      makeSkill({ id: "id-2", name: "skill-b", skillMd: "# B" }),
-    ];
-    const result = await mountSkills(client, skills, platformDir);
-    expect(result.paths.size).toBe(2);
-    expect(result.paths.get("id-1")).toBe(".stigmer/skills/skill-a");
-    expect(result.paths.get("id-2")).toBe(".stigmer/skills/skill-b");
-    expect(existsSync(join(platformDir, "skills", "skill-a", "SKILL.md"))).toBe(true);
-    expect(existsSync(join(platformDir, "skills", "skill-b", "SKILL.md"))).toBe(true);
-  });
-
-  it("skips the artifact download when the mounted hash matches (cache hit)", async () => {
-    const artifact = buildZip([{ name: "references/guide.md", content: "guide" }]);
-    const client = makeMockClient({
-      getSkillArtifact: vi.fn().mockResolvedValue({ artifact }),
-    });
-    const skill = makeSkill({
-      name: "cached-skill",
-      artifactStorageKey: "artifacts/cached.zip",
-      versionHash: "hash-v1",
-    });
-
-    await mountSkills(client, [skill], platformDir);
-    expect(client.getSkillArtifact).toHaveBeenCalledTimes(1);
-
-    // Second execution of the same session: same hash, no transfer.
-    const second = await mountSkills(client, [skill], platformDir);
-    expect(client.getSkillArtifact).toHaveBeenCalledTimes(1);
-    expect(second.paths.get("skill-id-1")).toBe(".stigmer/skills/cached-skill");
-    expect(readFileSync(
-      join(platformDir, "skills", "cached-skill", "references", "guide.md"), "utf-8",
-    )).toBe("guide");
-  });
-
-  it("remounts on version change and clears stale files from the old mount", async () => {
-    const artifactV1 = buildZip([{ name: "references/removed-in-v2.md", content: "old" }]);
-    const artifactV2 = buildZip([{ name: "references/new-in-v2.md", content: "new" }]);
-    const client = makeMockClient({
-      getSkillArtifact: vi.fn()
-        .mockResolvedValueOnce({ artifact: artifactV1 })
-        .mockResolvedValueOnce({ artifact: artifactV2 }),
-    });
-
-    await mountSkills(client, [makeSkill({
-      name: "evolving-skill",
-      skillMd: "# V1",
-      artifactStorageKey: "artifacts/v1.zip",
-      versionHash: "hash-v1",
-    })], platformDir);
-
-    await mountSkills(client, [makeSkill({
-      name: "evolving-skill",
-      skillMd: "# V2",
-      artifactStorageKey: "artifacts/v2.zip",
-      versionHash: "hash-v2",
-    })], platformDir);
-
-    const skillDir = join(platformDir, "skills", "evolving-skill");
-    expect(client.getSkillArtifact).toHaveBeenCalledTimes(2);
-    expect(readFileSync(join(skillDir, "SKILL.md"), "utf-8")).toBe("# V2");
-    expect(readFileSync(join(skillDir, "references", "new-in-v2.md"), "utf-8")).toBe("new");
-    // The v1-only file must not linger in the v2 mount (the stale-file leak).
-    expect(existsSync(join(skillDir, "references", "removed-in-v2.md"))).toBe(false);
-  });
-
-  it("does not cache a degraded SKILL.md-only mount — the next execution retries", async () => {
-    const artifact = buildZip([{ name: "references/late.md", content: "finally" }]);
-    const client = makeMockClient({
-      getSkillArtifact: vi.fn()
-        .mockRejectedValueOnce(new Error("Network timeout"))
-        .mockResolvedValueOnce({ artifact }),
-    });
-    const skill = makeSkill({
-      name: "retry-skill",
-      artifactStorageKey: "artifacts/retry.zip",
-      versionHash: "hash-v1",
-    });
-
-    // First pass degrades to SKILL.md only — never throws.
-    const first = await mountSkills(client, [skill], platformDir);
-    const skillDir = join(platformDir, "skills", "retry-skill");
-    expect(first.paths.get("skill-id-1")).toBe(".stigmer/skills/retry-skill");
-    expect(existsSync(join(skillDir, "SKILL.md"))).toBe(true);
-    expect(existsSync(join(skillDir, "references"))).toBe(false);
-
-    // Second pass retries and completes the mount.
-    await mountSkills(client, [skill], platformDir);
-    expect(client.getSkillArtifact).toHaveBeenCalledTimes(2);
-    expect(readFileSync(join(skillDir, "references", "late.md"), "utf-8")).toBe("finally");
-
-    // Third pass is a cache hit.
-    await mountSkills(client, [skill], platformDir);
-    expect(client.getSkillArtifact).toHaveBeenCalledTimes(2);
-  });
-
-  it("mounts only the first claimant when two skills resolve to the same directory", async () => {
-    const client = makeMockClient();
-    const skills = [
-      makeSkill({ id: "id-1", org: "org-a", slug: "shared-a", name: "shared-name", skillMd: "# First" }),
-      makeSkill({ id: "id-2", org: "org-b", slug: "shared-b", name: "shared-name", skillMd: "# Second" }),
-    ];
-    const result = await mountSkills(client, skills, platformDir);
-
-    // Both ids resolve to the (single) directory; the first claimant's content wins.
-    expect(result.paths.get("id-1")).toBe(".stigmer/skills/shared-name");
-    expect(result.paths.get("id-2")).toBe(".stigmer/skills/shared-name");
-    expect(readFileSync(join(platformDir, "skills", "shared-name", "SKILL.md"), "utf-8"))
-      .toBe("# First");
-  });
-
-  it("skips skills with no skillMd content", async () => {
-    const client = makeMockClient();
-    const skill = makeSkill({ name: "broken", skillMd: "" });
-    (skill as any).spec.skillMd = "";
-    const result = await mountSkills(client, [skill], platformDir);
-
-    // The path entry exists (naming is total) but nothing was mounted.
-    expect(result.paths.get("skill-id-1")).toBe(".stigmer/skills/broken");
-    expect(existsSync(join(platformDir, "skills", "broken"))).toBe(false);
-  });
-});
-
-// ─── generatePromptSection ───────────────────────────────────────────────
-
-describe("generatePromptSection", () => {
-  it("returns empty string for no skills", () => {
-    expect(generatePromptSection([], new Map())).toBe("");
-  });
-
-  it("generates progressive disclosure format", () => {
-    const skills = [makeSkill({ name: "calculator", description: "Arithmetic operations" })];
-    const paths = new Map([["skill-id-1", ".stigmer/skills/calculator"]]);
-    const section = generatePromptSection(skills, paths);
-
-    expect(section).toContain("## Skills");
-    expect(section).toContain("### calculator");
-    expect(section).toContain("**Description**: Arithmetic operations");
-    expect(section).toContain("**Location**: `.stigmer/skills/calculator/`");
-    expect(section).toContain("**Activate**: `read .stigmer/skills/calculator/SKILL.md`");
-  });
-
-  it("includes activation protocol instructions", () => {
-    const skills = [makeSkill()];
-    const paths = new Map([["skill-id-1", ".stigmer/skills/test-skill"]]);
-    const section = generatePromptSection(skills, paths);
-
-    expect(section).toContain("Activation protocol");
-    expect(section).toContain("read its SKILL.md");
-  });
-
-  it("handles multiple skills", () => {
-    const skills = [
-      makeSkill({ id: "id-1", name: "skill-a", description: "Desc A" }),
-      makeSkill({ id: "id-2", name: "skill-b", description: "Desc B" }),
-    ];
-    const paths = new Map([
-      ["id-1", ".stigmer/skills/skill-a"],
-      ["id-2", ".stigmer/skills/skill-b"],
-    ]);
-    const section = generatePromptSection(skills, paths);
-
-    expect(section).toContain("### skill-a");
-    expect(section).toContain("### skill-b");
-    expect(section).toContain("Desc A");
-    expect(section).toContain("Desc B");
-  });
-
-  it("falls back to (no description) when empty", () => {
-    const skills = [makeSkill({ description: "" })];
-    (skills[0] as any).spec.description = "";
-    const paths = new Map([["skill-id-1", ".stigmer/skills/test-skill"]]);
-    const section = generatePromptSection(skills, paths);
-    expect(section).toContain("(no description)");
-  });
-});
-
-// ─── generateAlsoAvailableSection ────────────────────────────────────────
-
-describe("generateAlsoAvailableSection", () => {
-  it("returns empty for no excluded names", () => {
-    expect(generateAlsoAvailableSection([])).toBe("");
-  });
-
-  it("lists excluded skills with backtick formatting", () => {
-    const section = generateAlsoAvailableSection(["alpha", "beta", "gamma"]);
-    expect(section).toContain("### Also Available");
-    expect(section).toContain("`alpha`");
-    expect(section).toContain("`beta`");
-    expect(section).toContain("`gamma`");
-  });
-
-  it("includes activation instructions", () => {
-    const section = generateAlsoAvailableSection(["some-skill"]);
-    expect(section).toContain(".stigmer/skills/<name>/SKILL.md");
-    expect(section).toContain("relevant to your task");
-  });
-});

package/src/shared/skill-writer.ts

@@ -1,266 +0,0 @@
-/**
- * Skill mounting and prompt generation for the deep-agent execution path.
- *
- * Follows the Agent Skills specification progressive disclosure model:
- *
- * 1. Metadata (startup) — skill name + description injected into
- *    the system prompt so the agent knows which skills are available.
- * 2. Instructions (activation) — the agent reads SKILL.md from the
- *    filesystem when it decides to activate a skill.
- * 3. Resources (on demand) — scripts, references, and assets are
- *    loaded by the agent only when required.
- *
- * Skills physically live in the session's platform directory
- * (`{platformDir}/skills/{name}/` — the SAME location the Cursor harness
- * mounts into), and the agent sees them as `.stigmer/skills/{name}/`
- * through the per-turn workspace symlink (see workspace/stigmer-link.ts).
- * Returned paths are the agent-visible `.stigmer/…` form.
- *
- * Mounts are cached by the skill's content-addressed version hash via the
- * shared skill-mount mechanics (issue #337, mirroring the Cursor harness's
- * #672 fix): metadata is fetched every execution — a pushed skill update
- * still lands on the very next message — but an unchanged skill skips the
- * artifact download and rewrite entirely.
- */
-
-import { join } from "node:path";
-import type { Skill } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
-import type { ApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
-import type { StigmerClient } from "../client/stigmer-client.js";
-import {
-  SKILLS_SUBDIR,
-  mountIsFresh,
-  downloadArtifact,
-  writeSkillMount,
-} from "./skill-mount.js";
-import { STIGMER_LOCAL_STATE_DIR } from "./workspace/stigmer-link.js";
-
-/** Agent-visible base of the skills tree (via the workspace `.stigmer` symlink). */
-const SKILLS_RELATIVE_BASE = `${STIGMER_LOCAL_STATE_DIR}/${SKILLS_SUBDIR}`;
-
-// ─── Types ───────────────────────────────────────────────────────────────
-
-export interface SkillPathMap {
-  /** Map from skill metadata ID to workspace-relative directory path. */
-  readonly paths: ReadonlyMap<string, string>;
-}
-
-// ─── Fetch ───────────────────────────────────────────────────────────────
-
-/**
- * Merge skill refs from agent and session specs (union, dedup by slug,
- * session wins on collision).
- */
-export function mergeSkillRefs(
-  agentRefs: readonly ApiResourceReference[],
-  sessionRefs: readonly ApiResourceReference[],
-): ApiResourceReference[] {
-  const bySlug = new Map<string, ApiResourceReference>();
-  for (const ref of agentRefs) {
-    if (ref.slug) bySlug.set(ref.slug, ref);
-  }
-  for (const ref of sessionRefs) {
-    if (ref.slug) bySlug.set(ref.slug, ref);
-  }
-  return [...bySlug.values()];
-}
-
-/**
- * Fetch all skills by their ApiResourceReference. Failures for individual
- * skills are logged and skipped (non-fatal).
- */
-export async function fetchSkillsByRefs(
-  client: StigmerClient,
-  refs: readonly ApiResourceReference[],
-): Promise<Skill[]> {
-  if (refs.length === 0) return [];
-
-  const results: Skill[] = [];
-  const fetches = refs.map(async (ref) => {
-    try {
-      return await client.getSkillByReference(ref);
-    } catch (err) {
-      console.warn(
-        `[skill-writer] Failed to fetch skill ${ref.org}/${ref.slug}: ` +
-        `${err instanceof Error ? err.message : String(err)}`,
-      );
-      return null;
-    }
-  });
-
-  const settled = await Promise.all(fetches);
-  for (const skill of settled) {
-    if (skill) results.push(skill);
-  }
-  return results;
-}
-
-// ─── Mount ───────────────────────────────────────────────────────────────
-
-/**
- * Mount skills into the session's platform directory, downloading each
- * skill's artifact only on a version-hash cache miss (see skill-mount.ts
- * for the marker mechanics). Returns a map of skill-id -> agent-visible
- * directory path.
- *
- * The returned map is a NAMING function, not a success record: every skill
- * gets its path entry so prompt generation stays total, while mount
- * failures degrade that one skill (loud log, no throw) — one broken skill
- * must never kill the run.
- *
- * Skills mount in parallel (each owns an independent directory), EXCEPT
- * when two skills resolve to the same directory name (same `spec.name`
- * from different orgs): concurrent remove-and-rewrite passes on one
- * directory would corrupt the mount, so only the first claimant mounts and
- * the collision is logged loudly. (The sequential code this replaced
- * silently let the last writer win — no better, just quieter.)
- */
-export async function mountSkills(
-  client: StigmerClient,
-  skills: readonly Skill[],
-  platformDir: string,
-): Promise<SkillPathMap> {
-  const paths = new Map<string, string>();
-  const claims = new Map<string, Skill>();
-
-  for (const skill of skills) {
-    const name = skill.spec?.name || skill.metadata?.slug || "unknown";
-    const skillId = skill.metadata?.id ?? name;
-    paths.set(skillId, `${SKILLS_RELATIVE_BASE}/${name}`);
-
-    // Impossible through the push pipeline (push.go hard-fails a ZIP
-    // without an extractable SKILL.md and always populates spec.skill_md),
-    // so an empty skillMd means a broken resource — skip, same as Cursor.
-    if (!skill.spec?.skillMd) {
-      console.warn(
-        `[skill-writer] skill ${name} (${skillId}) has no skillMd content — skipping mount`,
-      );
-      continue;
-    }
-
-    const prev = claims.get(name);
-    if (prev) {
-      console.warn(
-        `[skill-writer] mount directory collision on '${name}': ` +
-        `${prev.metadata?.org}/${prev.metadata?.slug} already claims it, ` +
-        `skipping ${skill.metadata?.org}/${skill.metadata?.slug}`,
-      );
-      continue;
-    }
-    claims.set(name, skill);
-  }
-
-  await Promise.all([...claims.entries()].map(async ([name, skill]) => {
-    const skillDir = join(platformDir, SKILLS_SUBDIR, name);
-    try {
-      const versionHash = skill.status?.versionHash ?? "";
-      const wantsArtifact = Boolean(skill.status?.artifactStorageKey);
-
-      if (versionHash !== "" && (await mountIsFresh(skillDir, versionHash, wantsArtifact))) {
-        console.log(
-          `[skill-writer] mount cache hit: ${name} (version ${versionHash.slice(0, 12)}) — skipping artifact transfer`,
-        );
-        return;
-      }
-
-      let artifactBytes: Uint8Array | undefined;
-      if (wantsArtifact) {
-        try {
-          artifactBytes = await downloadArtifact(client, skill.status!.artifactStorageKey);
-        } catch (err) {
-          // Deliberate degradation, but LOUD (#675): the run still gets
-          // SKILL.md, and the marker records artifactMounted=false so the
-          // next execution retries the download.
-          console.error(
-            `[skill-writer] artifact download FAILED for ${name} ` +
-            `(key=${skill.status!.artifactStorageKey}) — mounting SKILL.md WITHOUT the skill's ` +
-            `supporting files (scripts/references will be missing): ${err instanceof Error ? err.message : err}`,
-          );
-        }
-      }
-
-      await writeSkillMount(skill, skillDir, artifactBytes);
-      console.log(`[skill-writer] wrote skill mount: ${name}`);
-    } catch (err) {
-      console.warn(
-        `[skill-writer] failed to mount skill ${name}: ${err instanceof Error ? err.message : err}`,
-      );
-    }
-  }));
-
-  return { paths };
-}
-
-// ─── Prompt generation ───────────────────────────────────────────────────
-
-/**
- * Generate the system prompt section following the Agent Skills spec
- * progressive disclosure model.
- *
- * Only metadata (name + description + location) is injected. The agent
- * reads SKILL.md on demand via filesystem tools.
- */
-export function generatePromptSection(
-  skills: readonly Skill[],
-  skillPaths: ReadonlyMap<string, string>,
-): string {
-  if (skills.length === 0) return "";
-
-  const lines: string[] = [
-    "",
-    "",
-    "## Skills",
-    "",
-    "You have access to the following skills. Each skill provides specialized " +
-    "knowledge or capabilities.",
-    "",
-    "**Activation protocol**: To use a skill, read its SKILL.md file " +
-    "using the `read` tool. The SKILL.md contains detailed instructions, " +
-    "available tools, and usage examples.",
-    "",
-    "**Usage pattern**:",
-    "",
-    "1. Review the skill description below to determine relevance",
-    "2. Read `{location}/SKILL.md` for full instructions",
-    "3. Follow the skill's documented operations:",
-    "",
-    "`read {location}/references/schema.md`",
-    '`execute("python3 {location}/scripts/run.py")`',
-    "",
-  ];
-
-  for (const skill of skills) {
-    const name = skill.spec?.name || skill.metadata?.slug || "unknown";
-    const skillId = skill.metadata?.id ?? name;
-    const skillDir = skillPaths.get(skillId) ?? `${SKILLS_RELATIVE_BASE}/${name}`;
-    const description = skill.spec?.description || "(no description)";
-
-    lines.push(`### ${name}`);
-    lines.push(`**Description**: ${description}`);
-    lines.push(`**Location**: \`${skillDir}/\``);
-    lines.push(`**Activate**: \`read ${skillDir}/SKILL.md\``);
-    lines.push("");
-  }
-
-  return lines.join("\n");
-}
-
-/**
- * Generate a brief note listing skills excluded by relevance filtering.
- *
- * The agent can still request these skills by name if it determines
- * they are needed mid-conversation.
- */
-export function generateAlsoAvailableSection(
-  excludedNames: readonly string[],
-): string {
-  if (excludedNames.length === 0) return "";
-
-  const namesStr = excludedNames.map(n => `\`${n}\``).join(", ");
-  return (
-    "\n### Also Available\n\n" +
-    `These skills are installed but were not highlighted above: ${namesStr}. ` +
-    "If you determine one of them is relevant to your task, " +
-    "read its SKILL.md at `.stigmer/skills/<name>/SKILL.md` to activate it.\n"
-  );
-}