@pi-unipi/utility 2.14.0 → 2.14.2

package/README.md

@@ -68,6 +68,26 @@ Or edit `.unipi/config/util-settings.json` directly (migrated automatically from
 
 The badge is a persistent HUD overlay in the top-right corner showing the current session name. It auto-restores visibility on session restart.
 
+### Skill Startup Discovery
+
+Controls whether Unipi's built-in skills are cataloged in the agent's system prompt at startup (default: on). Your own skills — global, project, settings-mounted, and third-party packages — always stay cataloged.
+
+```
+/unipi:skills-settings        # Interactive toggle (or /unipi:skills-settings on|off)
+```
+
+Or edit `~/.pi/agent/settings.json` directly:
+
+```json
+{
+  "unipi": {
+    "skills": { "discovery": false }
+  }
+}
+```
+
+When off, Unipi's bundled skills are removed from the `<available_skills>` catalog, so their metadata never populates agent context. They remain invocable via `/skill:name` — pi expands those commands by reading the skill file directly, independent of the prompt catalog. The filter is applied consistently every turn, so provider prefix caching is unaffected.
+
 ## Programmatic API
 
 | Module | Path | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/utility",
-  "version": "2.14.0",
+  "version": "2.14.2",
   "description": "Utility commands and tools for Pi coding agent — lifecycle, diagnostics, cache, analytics, display, batch execution",
   "type": "module",
   "main": "src/index.ts",
@@ -36,7 +36,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.14.0"
+    "@pi-unipi/core": "2.14.2"
   },
   "devDependencies": {},
   "peerDependencies": {

package/src/commands.ts

@@ -22,6 +22,7 @@ import { runDiagnostics, formatDiagnosticsReport } from "./diagnostics/engine.js
 import { getEnvironmentInfo, formatEnvironmentInfo } from "./tools/env.js";
 import type { NameBadgeState } from "./tui/name-badge-state.js";
 import { readBadgeSettings, updateBadgeSetting, formatBadgeSettings } from "./settings.js";
+import { isSkillDiscoveryEnabled, saveSkillDiscoverySettings } from "./skill-discovery.js";
 import { UtilSettingsTui } from "./tui/util-settings-tui.js";
 
 /** Send a markdown response via pi.sendMessage */
@@ -134,6 +135,59 @@ export function registerNameBadgeCommands(
     },
   });
 
+  // ─── /unipi:skills-settings — skill startup discovery toggle ────────────
+  pi.registerCommand(`${UNIPI_PREFIX}${UTILITY_COMMANDS.SKILLS_SETTINGS}`, {
+    description: "Toggle skill startup discovery (skills catalog in system prompt; default on)",
+    handler: async (args: string, ctx: ExtensionContext) => {
+      const describe = (enabled: boolean) =>
+        enabled
+          ? "Skill discovery: ON — skills are cataloged in the system prompt at startup"
+          : "Skill discovery: OFF — skills are invoke-only via /skill:name (no startup catalog)";
+
+      const arg = args.trim().toLowerCase();
+      const current = isSkillDiscoveryEnabled();
+
+      let next: boolean | undefined;
+      if (arg === "on" || arg === "true" || arg === "1") {
+        next = true;
+      } else if (arg === "off" || arg === "false" || arg === "0") {
+        next = false;
+      } else if (arg === "" || arg === "toggle") {
+        if (arg === "" && ctx.hasUI) {
+          const choice = await ctx.ui.select(
+            "Skill startup discovery",
+            [
+              `On — catalog skills in the system prompt${current ? "  (current)" : ""}`,
+              `Off — invoke-only via /skill:name${current ? "" : "  (current)"}`,
+            ],
+          );
+          next = choice ? choice.startsWith("On") : undefined;
+        } else {
+          next = !current;
+        }
+      }
+
+      if (next === undefined) {
+        // Cancelled or invalid arg — show current state.
+        const status = describe(current);
+        if (ctx.hasUI) {
+          ctx.ui.notify(status, "info");
+        } else {
+          sendResponse(pi, status);
+        }
+        return;
+      }
+
+      const ok = saveSkillDiscoverySettings({ discovery: next });
+      const message = ok ? describe(next) : "Failed to save skill discovery setting.";
+      if (ctx.hasUI) {
+        ctx.ui.notify(message, ok ? "info" : "warning");
+      } else {
+        sendResponse(pi, message);
+      }
+    },
+  });
+
   // ─── /unipi:util-settings — unified settings TUI ──────────────────────
   pi.registerCommand(`${UNIPI_PREFIX}${UTILITY_COMMANDS.UTIL_SETTINGS}`, {
     description: "Configure badge and diff settings via unified TUI overlay",

package/src/index.ts

@@ -24,6 +24,7 @@ import {
   type UnipiBadgeGenerateRequestEvent,
 } from "@pi-unipi/core";
 import { registerUtilityCommands, registerNameBadgeCommands } from "./commands.js";
+import { isSkillDiscoveryEnabled, stripBundledSkills } from "./skill-discovery.js";
 import { NameBadgeState } from "./tui/name-badge-state.js";
 import { readBadgeSettings } from "./settings.js";
 import { getLifecycle } from "./lifecycle/process.js";
@@ -60,6 +61,7 @@ const ALL_COMMANDS = [
   UTILITY_COMMANDS.BADGE_SETTINGS,
   UTILITY_COMMANDS.UTIL_SETTINGS,
   UTILITY_COMMANDS.PREFIX_CACHE,
+  UTILITY_COMMANDS.SKILLS_SETTINGS,
 ].map((cmd) => `unipi:${cmd}`);
 
 /** All tools registered by this module */
@@ -128,6 +130,19 @@ export default function (pi: ExtensionAPI) {
 
   // Capture session context for cross-event use (not needed if BADGE_GENERATE_REQUEST removed)
 
+  // Skill startup discovery gate — when disabled (unipi.skills.discovery: false),
+  // Unipi's bundled skills are removed from the <available_skills> catalog so
+  // they never populate agent context; the user's own skills (global, project,
+  // settings-mounted, third-party packages) stay cataloged. /skill:name
+  // invocation is unaffected either way: pi expands those commands by reading
+  // SKILL.md directly. Applied consistently per turn, so the provider prefix
+  // cache stays intact.
+  pi.on("before_agent_start", (event) => {
+    if (isSkillDiscoveryEnabled()) return undefined;
+    const filtered = stripBundledSkills(event.systemPrompt);
+    return filtered ? { systemPrompt: filtered } : undefined;
+  });
+
   // Register commands
   registerUtilityCommands(pi);
   registerNameBadgeCommands(pi, nameBadgeState);

package/src/skill-discovery.ts

@@ -0,0 +1,178 @@
+/**
+ * @pi-unipi/utility — Skill Startup Discovery Gate
+ *
+ * Controls whether discovered skills are cataloged in the agent's system
+ * prompt at session start. Setting: `unipi.skills.discovery` in pi's
+ * settings.json (default: true).
+ *
+ * When off, the `<available_skills>` section is stripped from the system
+ * prompt every turn. Skills remain invocable via `/skill:name` — pi expands
+ * those commands by reading SKILL.md directly from disk, independent of the
+ * prompt catalog.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { UNIPI_SETTINGS_KEY } from "@pi-unipi/core";
+
+/** Skill discovery settings */
+export interface SkillDiscoverySettings {
+  /** Catalog skills in the system prompt at startup (default: true) */
+  discovery: boolean;
+}
+
+/** Default skill discovery settings */
+export const DEFAULT_SKILL_DISCOVERY_SETTINGS: SkillDiscoverySettings = {
+  discovery: true,
+};
+
+/** System-prompt markers for the skills catalog (agentskills.io tags). */
+const SKILLS_OPEN_TAG = "<available_skills>";
+const SKILLS_CLOSE_TAG = "</available_skills>";
+
+/**
+ * Get the path to pi's settings.json.
+ */
+function getSettingsPath(): string {
+  const agentDir = process.env.PI_AGENT_DIR || path.join(os.homedir(), ".pi", "agent");
+  return path.join(agentDir, "settings.json");
+}
+
+/**
+ * Read the raw settings.json file.
+ * Returns null if the file doesn't exist or is malformed.
+ */
+function readSettingsFile(): Record<string, unknown> | null {
+  try {
+    const settingsPath = getSettingsPath();
+    if (!fs.existsSync(settingsPath)) return null;
+    const raw = fs.readFileSync(settingsPath, "utf-8");
+    return JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    // Silently ignore — read failure falls back to defaults.
+    return null;
+  }
+}
+
+/**
+ * Write settings back to settings.json.
+ */
+function writeSettingsFile(settings: Record<string, unknown>): boolean {
+  try {
+    const settingsPath = getSettingsPath();
+    const dir = path.dirname(settingsPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+    return true;
+  } catch {
+    // Silently ignore — write failure is non-blocking.
+    return false;
+  }
+}
+
+/**
+ * Load skill discovery settings from settings.json.
+ * Falls back to defaults for any missing fields.
+ */
+export function loadSkillDiscoverySettings(): SkillDiscoverySettings {
+  const raw = readSettingsFile();
+  if (!raw) return { ...DEFAULT_SKILL_DISCOVERY_SETTINGS };
+
+  try {
+    const unipi = raw[UNIPI_SETTINGS_KEY] as Record<string, unknown> | undefined;
+    const skills = unipi?.skills as Record<string, unknown> | undefined;
+    if (!skills) return { ...DEFAULT_SKILL_DISCOVERY_SETTINGS };
+    return {
+      discovery: typeof skills.discovery === "boolean" ? skills.discovery : DEFAULT_SKILL_DISCOVERY_SETTINGS.discovery,
+    };
+  } catch {
+    return { ...DEFAULT_SKILL_DISCOVERY_SETTINGS };
+  }
+}
+
+/**
+ * Save skill discovery settings to settings.json.
+ * Merges with existing settings (preserves other keys).
+ */
+export function saveSkillDiscoverySettings(partial: Partial<SkillDiscoverySettings>): boolean {
+  const raw = readSettingsFile() ?? {};
+  const unipi = (raw[UNIPI_SETTINGS_KEY] as Record<string, unknown>) ?? {};
+  const existing = (unipi.skills as Record<string, unknown>) ?? {};
+
+  unipi.skills = { ...existing, ...partial };
+  raw[UNIPI_SETTINGS_KEY] = unipi;
+
+  return writeSettingsFile(raw);
+}
+
+/**
+ * Whether skills are cataloged in the system prompt at startup.
+ */
+export function isSkillDiscoveryEnabled(): boolean {
+  return loadSkillDiscoverySettings().discovery;
+}
+
+/**
+ * Match a skill location that belongs to Unipi's own bundled skills.
+ *
+ * - Installed via npm: `…/node_modules/@pi-unipi/<pkg>/skills/…`
+ * - Dev checkout (workspace/mise run): `…/unipi/packages/<pkg>/skills/…`
+ *
+ * Everything else (user global, project, settings-mounted, third-party
+ * packages) is NOT considered bundled and stays discoverable.
+ */
+export function isBundledSkillLocation(location: string): boolean {
+  return location.includes("/@pi-unipi/") || /\/unipi\/packages\//.test(location);
+}
+
+/**
+ * Remove Unipi's bundled skills from the `<available_skills>` catalog in a
+ * system prompt, keeping every other skill discoverable. When no non-bundled
+ * skills remain, the whole section (with its intro paragraph) is removed.
+ *
+ * Anchor-based: section tags are agentskills.io spec (stable), entry
+ * splitting follows pi's `formatSkillsForPrompt` layout (`  <skill>` entries
+ * with `<name>`/`<description>`/`<location>` children).
+ *
+ * Returns undefined when there is nothing to change (no section, or no
+ * bundled skills in it).
+ */
+export function stripBundledSkills(systemPrompt: string): string | undefined {
+  const open = systemPrompt.indexOf(SKILLS_OPEN_TAG);
+  if (open === -1) return undefined;
+  const close = systemPrompt.indexOf(SKILLS_CLOSE_TAG, open);
+  if (close === -1) return undefined;
+  const sectionStart = open + SKILLS_OPEN_TAG.length;
+
+  const inner = systemPrompt.slice(sectionStart, close);
+  const entries = inner.split(/(?=  <skill>)/g);
+  const kept: string[] = [];
+  let bundledCount = 0;
+  for (const entry of entries) {
+    if (!entry.includes("<skill>")) continue; // Whitespace between tags.
+    const locationMatch = entry.match(/<location>([^<]*)<\/location>/);
+    if (locationMatch && isBundledSkillLocation(locationMatch[1])) {
+      bundledCount++;
+      continue;
+    }
+    kept.push(entry);
+  }
+
+  if (bundledCount === 0) return undefined; // No bundled skills — no-op.
+
+  if (kept.length === 0) {
+    // Nothing left to catalog — remove the entire section (intro included).
+    // Layout: "<prev>\n\n<intro paragraph>\n\n<available_skills>…</available_skills>".
+    const p1 = systemPrompt.lastIndexOf("\n\n", open);
+    const prev = p1 === -1 ? -1 : systemPrompt.lastIndexOf("\n\n", p1 - 1);
+    const start = prev === -1 ? 0 : prev;
+    return systemPrompt.slice(0, start) + systemPrompt.slice(close + SKILLS_CLOSE_TAG.length);
+  }
+
+  // Rebuild the catalog with only the non-bundled entries.
+  const rebuiltInner = "\n" + kept.join("").replace(/\n+$/, "") + "\n";
+  return systemPrompt.slice(0, sectionStart) + rebuiltInner + systemPrompt.slice(close);
+}