pi-skill-router 0.2.1 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # pi-skill-router
 
-`pi-skill-router` routes to **externally hosted skill collections**. It clones skill repositories into a user-level managed directory, wraps the skills you select as hidden leaves behind a visible gateway, exposes them to Pi, and provides focused routing suggestions.
+`pi-skill-router` routes to **externally hosted skill collections**. It clones skill repositories into a user-level managed directory, wraps the skills you select as hidden leaves behind a visible gateway, exposes them to Pi, and registers every routed skill as a codemode tool the model searches and calls.
 
 **Package version:** see [`package.json`](package.json).
 
@@ -30,7 +30,10 @@ pi install npm:pi-skill-router
 1. **Add**: `/skill-router` → *Add collection* → enter `owner/repo[@ref]`, a GitHub URL, or a local path. The repo is shallow-cloned into `cache/`, scanned for `SKILL.md` files, and you choose which skills to route (or all). No prefix is required.
 2. **Describe and materialize**: after selecting skills, the active AI model synthesizes the selected skills' descriptions into a whole-collection capability summary and the router saves it directly, without manual editing or confirmation. If no authenticated model is available or generation fails or returns invalid output, Add collection reports an installation error and leaves the collection uninstalled; it never substitutes a skill-name-based summary. The summary becomes the gateway's frontmatter description. Selected skills are saved into `exposed/collections/<collection>/leaves/<name>/`, while the single visible gateway is created in `exposed/collections/<collection>/gateway/SKILL.md`. Keeping the gateway and leaves in one atomic collection tree prevents partial materialization. Its body indexes the selected workflows with descriptions and exact relative leaf paths. Sub-skills remain clean without synthetic name prefixes.
 3. **Expose**: on session start and `/reload`, the extension answers Pi's `resources_discover` event with only the gateway directory, so only `/skill:<gateway>` appears in Pi's slash-command menu. Sub-skills do not clutter `/`.
-4. **Route**: when a prompt matches a route, `before_agent_start` appends a focused suggestion naming the exact sub-skill `SKILL.md` path for the agent to read. Your message is never rewritten. The gateway is the sole slash command; sub-skills are never slash commands.
+4. **Search and call**: each routed skill is registered as one codemode tool, named `skill_router__<collection>__<skill>` with every character outside `[A-Za-z0-9_]` replaced by `_`, as MCP tool names are. All of a collection's skill tools share one namespace named `skill_router__<collection>`, aliased to the collection id. The model searches codemode's tools and calls the matched one, which returns that skill's instructions together with the directory its references and scripts resolve against. The collection's capability summary is the namespace description and the gateway body is its `instructions`, so one lookup answers what a collection contains. Codemode is inactive by default and the router never activates it.
+5. **Fall back without codemode**: while codemode is not active — or while an allowlist has removed the skill tools, or the registered `codemode` declares that it reaches no tool — `before_agent_start` appends a focused suggestion naming the exact sub-skill `SKILL.md` path for the agent to read instead. Your message is never rewritten. The gateway is the sole slash command; sub-skills are never slash commands.
+
+To run the tools channel without an MCP server, declare codemode in your settings with `"defaultTools": ["+codemode"]`. Passing `--tools` names an allowlist that also removes extension tools: `--tools 'read,codemode'` hides every skill tool and leaves only the fallback, while `--tools 'read,codemode,skill_router__*'` keeps them callable from a script. An allowlist match cannot declare a `codemode`-exposure tool, so a direct call needs `tool_search` to load it first. The router decides per skill, so an allowlist that kept one skill's tool and removed another still falls back for the removed one.
 
 ## Managing Collections
 
@@ -38,7 +41,7 @@ Registry changes wait asynchronously for competing operations, for up to 10 seco
 
 Everything runs through the `/skill-router` menu:
 
-- **Add collection** — clone a repo, pick skills, install.
+- **Add collection** — clone a repo, pick skills, install. Every menu change — add, update, routed skills, capability summary, remove, enable/disable — refreshes the skill tools in place, so the tools channel follows the registry in the same session and a removed or disabled collection has its tools withdrawn. `/reload` is needed only to refresh the gateway command and the prompt's skill list. A collection installed by another process, or a hand-edited registry, stays on the routing suggestion until then.
 - **Update collection** — pull upstream and re-materialize the preserved selection. New upstream skills are reported but stay unrouted until you explicitly select them.
 - **Change routed skills** — add currently available upstream skills to an installed collection's explicit selection.
 - **Edit capability summary** — revise the gateway description for an installed collection, then re-materialize its gateway.
@@ -52,9 +55,17 @@ Routing terms are derived from skill names and stored in `~/.pi/agent/skill-rout
 
 - Gateway names are unique across collections; duplicate upstream skill names inside one collection fail the install instead of colliding.
 - Materialization is atomic (temporary directory + rename); a failed install leaves no partial exposed directory.
-- Invalid registry entries fail closed: they are ignored for both exposure and routing.
-- Only skills you selected are ever exposed.
+- Invalid registry entries fail closed: they are ignored for exposure, routing, and tool registration.
+- Only skills you selected are ever exposed, and a disabled collection registers no tools.
+- A skill tool re-resolves its collection on every call and reads only a regular file inside `exposed/collections`. A removed collection, a tampered leaf, or a symlinked instruction file is refused instead of served.
+- A call returns at most 20000 characters of instructions, followed by a note naming the file that holds the rest.
+- A registered skill tool can be filtered out of the session entirely by a `--tools` or `--exclude-tools` allowlist. The router detects that for the matched skill, and the routing suggestion takes over for it.
+- Removing or disabling a collection while the session is live withdraws its skill tools: Pi cannot unregister a tool, so they are re-registered hidden and stay unreachable.
 
 ## Security
 
 Skills are instructions the model follows and may bundle scripts. Review a repository's skills before adding it — installing a collection means trusting its content at user level across all projects.
+
+## License
+
+MIT

package/index.ts

@@ -1,29 +1,52 @@
 import type { BeforeAgentStartEvent, ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { routerRoot } from "./src/paths";
+import { routerRoot, skillToolName } from "./src/paths";
 import { loadCollections } from "./src/registry";
 import { isExplicitSkillInvocation, routePrompt, routingGuidance } from "./src/router";
+import { codemodeReachesSkillTool, refreshSkillTools } from "./src/skills";
 import { exposedSkillPaths } from "./src/sync";
 import { showSkillRouterMenu } from "./src/menu";
 
+/**
+ * Two channels reach a leaf skill.
+ *
+ * The tools channel registers one codemode tool per routed leaf skill, so the
+ * model searches codemode's tools and calls the matched one. The fallback
+ * channel keeps the routing suggestion whenever that skill's own tool cannot be
+ * called: a session that does not declare codemode, an allowlist that removed
+ * the tool, or a collection added after this extension loaded. The gateway stays
+ * exposed either way, as the human `/skill:<gateway>` entry point.
+ */
 export default function skillRouter(pi: ExtensionAPI): void {
+  refreshSkillTools(pi, routerRoot());
+
   pi.on("resources_discover", () => ({
     skillPaths: exposedSkillPaths(routerRoot()),
   }));
 
   pi.on("before_agent_start", (event: BeforeAgentStartEvent) => {
-    if (isExplicitSkillInvocation(event.prompt)) return;
+    const options = event.systemPromptOptions;
+    if (!("sections" in options) || !options.sections || typeof options.sections !== "object" || Array.isArray(options.sections)) {
+      throw new Error("This extension requires Pi structured prompt sections.");
+    }
+    const sections = options.sections;
+    Reflect.deleteProperty(sections, "skill_router");
+    if (!("prompt" in event) || typeof event.prompt !== "string" || isExplicitSkillInvocation(event.prompt)) return;
 
     const skills = event.systemPromptOptions.skills ?? [];
     const match = routePrompt(event.prompt, loadCollections(routerRoot()), new Map(skills.map((skill) => [skill.name, skill])));
     if (!match) return;
+    // The tools channel wins only for this skill's own tool. A surviving sibling
+    // tool, or a collection that registered nothing before the next reload, must
+    // not suppress the suggestion that is the only working path to this skill.
+    if (codemodeReachesSkillTool(pi, skillToolName(match.collectionId, match.skillName))) return;
 
-    return { systemPrompt: `${event.systemPrompt}\n\n${routingGuidance(match)}` };
+    Object.assign(sections, { skill_router: routingGuidance(match) });
   });
 
   pi.registerCommand("skill-router", {
     description: "Manage externally hosted skill collections (add, update, remove, toggle, list)",
     handler: async (_args, ctx) => {
-      await showSkillRouterMenu(ctx);
+      await showSkillRouterMenu(ctx, { refreshTools: () => refreshSkillTools(pi, routerRoot()) });
     },
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-skill-router",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Route to externally hosted skill collections: clone GitHub skill repos, wrap them as hidden leaves behind visible gateways, and get focused suggestions",
   "keywords": [
     "pi-package",
@@ -10,6 +10,7 @@
   ],
   "author": "Frad LEE <fradser@gmail.com>",
   "license": "MIT",
+  "type": "module",
   "repository": {
     "type": "git",
     "url": "https://github.com/FradSer/pi-packages.git"
@@ -26,7 +27,8 @@
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
   },
   "pi": {
     "extensions": [
@@ -34,6 +36,6 @@
     ]
   },
   "dependencies": {
-    "@fradser/pi-kit": "0.5.0"
+    "@fradser/pi-kit": "0.6.0"
   }
-}
+}

package/src/menu.ts

@@ -19,7 +19,15 @@ import {
   type UpstreamSkill,
 } from "./sync";
 
-const RELOAD_HINT = "Run /reload (or restart pi) to apply skill changes.";
+/** Collection changes apply to the tools channel at once; the gateway command and
+ * the prompt's skill list come from Pi's resource discovery, which only runs on
+ * startup and reload. */
+const RELOAD_HINT = "Skill tools updated; run /reload (or restart pi) to refresh the gateway command.";
+
+/** What the menu needs from the extension to keep the tools channel current. */
+export interface SkillRouterHooks {
+  refreshTools: () => void;
+}
 
 function reportOperationError(ctx: ExtensionCommandContext, label: string, error: unknown): void {
   if (error instanceof Error && error.name === "AbortError") {
@@ -114,7 +122,7 @@ async function pickSkills(ctx: ExtensionCommandContext, skills: UpstreamSkill[])
   return selected.length > 0 ? selected : undefined;
 }
 
-async function addFlow(ctx: ExtensionCommandContext): Promise<void> {
+async function addFlow(ctx: ExtensionCommandContext, hooks: SkillRouterHooks): Promise<void> {
   const root = routerRoot();
   const repo = await ctx.ui.input("Add collection", "owner/repo[@ref], GitHub URL, or local path");
   if (!repo) return;
@@ -166,6 +174,7 @@ async function addFlow(ctx: ExtensionCommandContext): Promise<void> {
       `Installing ${repo}...`,
       (signal) => addCollection(root, { repo, id, description, skills: selection, summaries }, signal),
     );
+    hooks.refreshTools();
     notifyPi(ctx.ui, `Installed "${result.id}" with ${result.skills.length} skills. ${RELOAD_HINT}`, "info");
   } catch (error) {
     reportOperationError(ctx, "Failed to install collection", error);
@@ -186,7 +195,7 @@ async function pickCollection(ctx: ExtensionCommandContext, action: string) {
   return collections.find((collection) => choice.startsWith(`${collection.id} (`));
 }
 
-async function selectionFlow(ctx: ExtensionCommandContext): Promise<void> {
+async function selectionFlow(ctx: ExtensionCommandContext, hooks: SkillRouterHooks): Promise<void> {
   const collection = await pickCollection(ctx, "Change routed skills");
   if (!collection) return;
   try {
@@ -209,13 +218,14 @@ async function selectionFlow(ctx: ExtensionCommandContext): Promise<void> {
     if (selected.size === collection.routes.length) return;
     const result = await runWithLoading(ctx, `Changing ${collection.id} skills...`,
       (signal) => updateCollectionSelection(routerRoot(), collection.id, [...selected], signal));
+    hooks.refreshTools();
     notifyPi(ctx.ui, `Updated "${result.id}" with ${result.selected.length} routed skills. ${RELOAD_HINT}`, "info");
   } catch (error) {
     reportOperationError(ctx, "Selection update failed", error);
   }
 }
 
-async function descriptionFlow(ctx: ExtensionCommandContext): Promise<void> {
+async function descriptionFlow(ctx: ExtensionCommandContext, hooks: SkillRouterHooks): Promise<void> {
   const collection = await pickCollection(ctx, "Edit capability summary");
   if (!collection) return;
   const description = await ctx.ui.input("Collection capability summary", collection.description);
@@ -223,13 +233,14 @@ async function descriptionFlow(ctx: ExtensionCommandContext): Promise<void> {
   try {
     await runWithLoading(ctx, `Updating ${collection.id} summary...`,
       (signal) => updateCollectionDescription(routerRoot(), collection.id, description, signal));
+    hooks.refreshTools();
     notifyPi(ctx.ui, `Updated "${collection.id}" capability summary. ${RELOAD_HINT}`, "info");
   } catch (error) {
     reportOperationError(ctx, "Capability summary update failed", error);
   }
 }
 
-async function updateFlow(ctx: ExtensionCommandContext): Promise<void> {
+async function updateFlow(ctx: ExtensionCommandContext, hooks: SkillRouterHooks): Promise<void> {
   const collection = await pickCollection(ctx, "Update collection");
   if (!collection) return;
   try {
@@ -238,6 +249,7 @@ async function updateFlow(ctx: ExtensionCommandContext): Promise<void> {
       `Updating ${collection.id}...`,
       (signal) => updateCollection(routerRoot(), collection.id, signal),
     );
+    hooks.refreshTools();
     const notes = [`Updated "${result.id}": ${result.kept.length} skills re-materialized.`];
     if (result.dropped.length > 0) notes.push(`Removed upstream: ${result.dropped.join(", ")}.`);
     if (result.newUpstream.length > 0) notes.push(`New upstream skills not routed: ${result.newUpstream.join(", ")}.`);
@@ -247,7 +259,7 @@ async function updateFlow(ctx: ExtensionCommandContext): Promise<void> {
   }
 }
 
-async function removeFlow(ctx: ExtensionCommandContext): Promise<void> {
+async function removeFlow(ctx: ExtensionCommandContext, hooks: SkillRouterHooks): Promise<void> {
   const collection = await pickCollection(ctx, "Remove collection");
   if (!collection) return;
   const confirmed = await ctx.ui.confirm("Remove collection", `Remove "${collection.id}" and its exposed skills? The cached clone is kept.`);
@@ -255,18 +267,20 @@ async function removeFlow(ctx: ExtensionCommandContext): Promise<void> {
   try {
     await runWithLoading(ctx, `Removing ${collection.id}...`,
       (signal) => removeCollection(routerRoot(), collection.id, signal));
+    hooks.refreshTools();
     notifyPi(ctx.ui, `Removed "${collection.id}". ${RELOAD_HINT}`, "info");
   } catch (error) {
     reportOperationError(ctx, "Remove failed", error);
   }
 }
 
-async function toggleFlow(ctx: ExtensionCommandContext): Promise<void> {
+async function toggleFlow(ctx: ExtensionCommandContext, hooks: SkillRouterHooks): Promise<void> {
   const collection = await pickCollection(ctx, "Enable/disable collection");
   if (!collection) return;
   try {
     const updated = await runWithLoading(ctx, `Updating ${collection.id}...`,
       (signal) => setCollectionEnabled(routerRoot(), collection.id, !collection.enabled, signal));
+    hooks.refreshTools();
     notifyPi(ctx.ui, `"${updated.id}" is now ${updated.enabled ? "enabled" : "disabled"}. ${RELOAD_HINT}`, "info");
   } catch (error) {
     reportOperationError(ctx, "Enable/disable failed", error);
@@ -288,7 +302,7 @@ async function listFlow(ctx: ExtensionCommandContext): Promise<void> {
   );
 }
 
-export async function showSkillRouterMenu(ctx: ExtensionCommandContext): Promise<void> {
+export async function showSkillRouterMenu(ctx: ExtensionCommandContext, hooks: SkillRouterHooks): Promise<void> {
   for (;;) {
     const action = await ctx.ui.select("Skill Router", [
       "Add collection",
@@ -300,12 +314,12 @@ export async function showSkillRouterMenu(ctx: ExtensionCommandContext): Promise
       "List collections",
     ]);
     if (action === undefined) return;
-    if (action === "Add collection") await addFlow(ctx);
-    else if (action === "Update collection") await updateFlow(ctx);
-    else if (action === "Change routed skills") await selectionFlow(ctx);
-    else if (action === "Edit capability summary") await descriptionFlow(ctx);
-    else if (action === "Remove collection") await removeFlow(ctx);
-    else if (action === "Enable/disable collection") await toggleFlow(ctx);
+    if (action === "Add collection") await addFlow(ctx, hooks);
+    else if (action === "Update collection") await updateFlow(ctx, hooks);
+    else if (action === "Change routed skills") await selectionFlow(ctx, hooks);
+    else if (action === "Edit capability summary") await descriptionFlow(ctx, hooks);
+    else if (action === "Remove collection") await removeFlow(ctx, hooks);
+    else if (action === "Enable/disable collection") await toggleFlow(ctx, hooks);
     else await listFlow(ctx);
   }
 }

package/src/paths.ts

@@ -17,8 +17,12 @@ export function cacheDir(root: string, cacheKey: string): string {
   return join(root, "cache", cacheKey);
 }
 
+export function exposedCollectionsDir(root: string): string {
+  return join(root, "exposed", "collections");
+}
+
 export function exposedDir(root: string, collectionId: string): string {
-  return join(root, "exposed", "collections", collectionId);
+  return join(exposedCollectionsDir(root), collectionId);
 }
 
 export function legacyExposedDir(root: string, collectionId: string): string {
@@ -40,3 +44,19 @@ export function leafSkillDir(root: string, collectionId: string, skillName: stri
 export function leafSkillFile(root: string, collectionId: string, skillName: string): string {
   return join(leafSkillDir(root, collectionId, skillName), "SKILL.md");
 }
+
+/** Every character a codemode script identifier cannot carry becomes `_`, as it
+ * does for MCP tool names, so the registered name and the script identifier agree. */
+export function codemodeIdentifier(value: string): string {
+  return value.replace(/[^A-Za-z0-9_]/g, "_");
+}
+
+/** The search namespace of one collection: the router prefix and the collection. */
+export function collectionNamespaceName(collectionId: string): string {
+  return `skill_router__${codemodeIdentifier(collectionId)}`;
+}
+
+/** The tool name standing for one leaf skill: the namespace and the skill. */
+export function skillToolName(collectionId: string, skillName: string): string {
+  return `${collectionNamespaceName(collectionId)}__${codemodeIdentifier(skillName)}`;
+}

package/src/skills.ts

@@ -0,0 +1,360 @@
+/**
+ * The tools channel: one codemode-callable tool per routed leaf skill.
+ *
+ * A leaf skill is prose, so the tool exists to be found and called: its name and
+ * description are the skill's searchable identity, its namespace is the
+ * collection, and its call returns the wrapped instructions with the directory
+ * that resolves the skill's references and scripts.
+ *
+ * Registration reads the registry once, at extension load. A call re-resolves the
+ * collection, so a tool whose collection was removed fails instead of serving a
+ * path captured at registration. Nothing here activates codemode: a session that
+ * does not declare it keeps the routing-suggestion fallback.
+ */
+
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, realpathSync, type Stats } from "node:fs";
+import { join, sep } from "node:path";
+import { Type, type Static } from "typebox";
+import { defineTool, keyHint, type AgentToolResult, type ExtensionAPI, type ToolNamespace } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { bindLifecycleRenderers, emptyToolCall } from "@fradser/pi-kit";
+import { cacheDir, collectionNamespaceName, exposedCollectionsDir, gatewayDir, leafSkillDir, leafSkillFile, skillToolName } from "./paths";
+import { loadCollections, type RegistryCollection, type RegistryRoute } from "./registry";
+import { scanSkills } from "./sync";
+
+/** Instructions one call returns. A longer file is cut at this bound, and the
+ * returned body names the file that keeps all of it. */
+const MAX_SKILL_BODY_CHARS = 20000;
+
+const TOOL_TAG = "skill-router";
+const CODEMODE_TOOL_NAME = "codemode";
+/** `O_NOFOLLOW` is absent on platforms that cannot express it, where it contributes nothing. */
+const NO_FOLLOW = constants.O_NOFOLLOW ?? 0;
+
+const SKILL_TOOL_PARAMS = Type.Object({}, { additionalProperties: false });
+
+const SKILL_TOOL_OUTPUT = Type.Object({
+  ok: Type.Boolean(),
+  collection: Type.String(),
+  skill: Type.String(),
+  tool: Type.String(),
+  directory: Type.Optional(Type.String()),
+  skillFile: Type.Optional(Type.String()),
+  body: Type.Optional(Type.String()),
+  truncated: Type.Optional(Type.Boolean()),
+  error: Type.Optional(Type.String()),
+}, { additionalProperties: false });
+
+type SkillToolOutput = Static<typeof SKILL_TOOL_OUTPUT>;
+
+/** What the transcript row reads back from a completed call. */
+interface SkillToolDetails {
+  subject?: string;
+  summary?: string;
+  label?: string;
+  details?: readonly string[];
+  tone?: "success" | "warning" | "error";
+}
+
+type SkillToolResult = AgentToolResult<SkillToolDetails> & { structuredContent: SkillToolOutput };
+
+/** A script that searches: `reachesTools` must answer it for every tool a script
+ * can call, so what it names is what the session can actually reach. */
+const DISCOVERY_SCRIPT = { code: "await searchTools('')" };
+
+/** Whether one skill's tool is reachable from a codemode script: codemode is
+ * active, answers a discovery script by naming that exact tool, and the tool
+ * survived the session's tool allowlist. A session allowlist (`--tools`,
+ * `--exclude-tools`) filters an extension tool out of the registry entirely, so
+ * codemode can be active while every call fails. The check is per skill, not per
+ * collection: a surviving sibling tool must not stand in for the one the prompt
+ * matched, and a collection added after load has no tool at all until a refresh.
+ *
+ * A `codemode` that declares `reachesTools` but names nothing keeps the fallback:
+ * Pi's contract lets it answer per script, and the suggestion is then the only
+ * working path. */
+export function codemodeReachesSkillTool(
+  pi: Pick<ExtensionAPI, "getActiveTools" | "getAllTools">,
+  toolName: string,
+): boolean {
+  if (!pi.getActiveTools().includes(CODEMODE_TOOL_NAME)) return false;
+  const tools = pi.getAllTools();
+  const codemode = tools.find((tool) => tool.name === CODEMODE_TOOL_NAME);
+  if (typeof codemode?.reachesTools !== "function") return false;
+  if (!tools.some((tool) => tool.name === toolName)) return false;
+  // A word refers to every tool or namespace whose name contains it.
+  let reach: "all" | readonly string[] | undefined;
+  try {
+    reach = codemode.reachesTools(DISCOVERY_SCRIPT);
+  } catch {
+    // A `codemode` that cannot answer keeps the fallback: this is the conservative
+    // direction, and an exception must not cost the turn its only working path.
+    return false;
+  }
+  return reach === "all" || (Array.isArray(reach) && reach.some((word) => typeof word === "string" && toolName.includes(word)));
+}
+
+/** Skill tools one loaded extension instance has registered. Pi cannot
+ * unregister a tool, so a refresh withdraws the names a registry change removed
+ * by re-registering them hidden. */
+const registeredSkillTools = new WeakMap<ExtensionAPI, string[]>();
+
+/** Register every routed leaf skill of every enabled collection, and withdraw the
+ * tools of a collection that is gone or disabled since the last refresh. The
+ * extension calls this when it loads and after every `/skill-router` mutation, so
+ * the tools channel follows the registry without a reload. */
+export function refreshSkillTools(pi: ExtensionAPI, root: string): void {
+  const names = new Set<string>();
+  const definitions = loadCollections(root)
+    .filter((collection) => collection.enabled)
+    .flatMap((collection) => {
+      const namespace = collectionNamespace(root, collection);
+      const upstream = upstreamDescriptions(root, collection);
+      return collection.routes.map((route) => {
+        const tool = skillTool(root, collection, route, searchableSkillText(route, upstream.get(route.skill) ?? ""), namespace);
+        names.add(tool.name);
+        return tool;
+      });
+    });
+
+  for (const tool of definitions) pi.registerTool(tool);
+  for (const name of registeredSkillTools.get(pi) ?? []) {
+    if (!names.has(name)) pi.registerTool(withdrawnSkillTool(name));
+  }
+  registeredSkillTools.set(pi, [...names]);
+}
+
+/** A withdrawn skill tool: unreachable, and kept only because Pi cannot
+ * unregister a name. */
+function withdrawnSkillTool(name: string) {
+  return defineTool<typeof SKILL_TOOL_PARAMS, SkillToolDetails>({
+    name,
+    label: name,
+    description: "Withdrawn skill tool.",
+    parameters: SKILL_TOOL_PARAMS,
+    outputSchema: SKILL_TOOL_OUTPUT,
+    exposure: "hidden",
+    renderShell: "self",
+    renderCall: () => emptyToolCall(),
+    renderResult: skillResultBand,
+    async execute(): Promise<SkillToolResult> {
+      return refuse(name, "", "", `Skill tool "${name}" is withdrawn: its collection is no longer routed.`);
+    },
+  });
+}
+
+/** Read a regular file, refusing a symlink that appears after the caller's own
+ * checks and before this open. */
+function readRegularFile(path: string, validated: Stats): string {
+  const descriptor = openSync(path, constants.O_RDONLY | NO_FOLLOW);
+  try {
+    const opened = fstatSync(descriptor);
+    if (!opened.isFile()) throw new Error(`Not a regular file: ${path}`);
+    // The descriptor must be the very file that was validated: a directory swapped
+    // between the checks and this open would otherwise redirect the read.
+    if (opened.dev !== validated.dev || opened.ino !== validated.ino) {
+      throw new Error(`File changed between validation and read: ${path}`);
+    }
+    return readFileSync(descriptor, "utf8");
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+/** The searchable text of one route: the workflow summary and the skill author's
+ * own description, without repeating one inside the other. The summary judges
+ * relevance; the upstream description carries the words a request uses. */
+function searchableSkillText(route: RegistryRoute, upstreamDescription: string): string {
+  const oneLine = (value: string) => value.replace(/\s+/g, " ").trim();
+  const summary = oneLine(route.summary ?? "");
+  const upstream = oneLine(upstreamDescription);
+  if (!upstream || upstream.startsWith(summary.replace(/\.$/, ""))) return upstream || summary;
+  return summary ? `${summary} ${upstream}` : upstream;
+}
+
+/** One namespace per collection: its capability summary and gateway index answer
+ * "what is in this collection" through one lookup. */
+function collectionNamespace(root: string, collection: RegistryCollection): ToolNamespace {
+  const gateway = managedFile(root, join(gatewayDir(root, collection.id, collection.gateway), "SKILL.md"));
+  return {
+    name: collectionNamespaceName(collection.id),
+    aliases: [collection.id],
+    description: collection.description,
+    ...(gateway === undefined ? {} : { instructions: gateway }),
+  };
+}
+
+/** Upstream descriptions by skill name, from the collection's clone. A missing or
+ * unreadable clone leaves the workflow summaries as the searchable text. */
+function upstreamDescriptions(root: string, collection: RegistryCollection): Map<string, string> {
+  try {
+    const skills = scanSkills(cacheDir(root, collection.source.cacheKey));
+    return new Map(skills.map((skill) => [skill.name, skill.description]));
+  } catch {
+    return new Map();
+  }
+}
+
+function skillTool(
+  root: string,
+  collection: RegistryCollection,
+  route: RegistryRoute,
+  searchable: string,
+  namespace: ToolNamespace,
+) {
+  const name = skillToolName(collection.id, route.skill);
+  const subject = `${collection.id}/${route.skill}`;
+  return defineTool<typeof SKILL_TOOL_PARAMS, SkillToolDetails>({
+    name,
+    label: route.skill,
+    description: searchable,
+    promptGuidelines: [
+      `Loads the \`${route.skill}\` workflow of the \`${collection.id}\` skill collection. Follow the returned instructions and use the returned directory for its files.`,
+      "Call the workflow these instructions load; do not act on the collection's other workflows.",
+    ],
+    parameters: SKILL_TOOL_PARAMS,
+    outputSchema: SKILL_TOOL_OUTPUT,
+    exposure: "codemode",
+    namespace,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    renderShell: "self",
+    renderCall: () => emptyToolCall(),
+    renderResult: skillResultBand,
+    async execute(_toolCallId, _params, signal): Promise<SkillToolResult> {
+      signal?.throwIfAborted();
+      const current = loadCollections(root).find((entry) => entry.id === collection.id && entry.enabled);
+      const currentRoute = current?.routes.find((candidate) => candidate.skill === route.skill);
+      if (!current || !currentRoute) {
+        return refuse(
+          name,
+          collection.id,
+          route.skill,
+          `Collection "${collection.id}" is no longer installed and enabled, so "${route.skill}" is unavailable. Run /reload after changing collections.`,
+        );
+      }
+      try {
+        const leaf = readLeafSkill(root, current, currentRoute);
+        const { body, truncated } = boundSkillBody(leaf.content, leaf.skillFile);
+        return {
+          content: [{ type: "text", text: body }],
+          details: {
+            subject,
+            label: "loaded",
+            details: [leaf.skillFile],
+            ...(truncated ? { summary: `The body is cut at ${MAX_SKILL_BODY_CHARS} characters; the file above holds all of it.` } : {}),
+          },
+          structuredContent: {
+            ok: true,
+            collection: collection.id,
+            skill: route.skill,
+            tool: name,
+            directory: leaf.directory,
+            skillFile: leaf.skillFile,
+            body,
+            truncated,
+          },
+        };
+      } catch (error) {
+        return refuse(name, collection.id, route.skill, error instanceof Error ? error.message : String(error));
+      }
+    },
+  });
+}
+
+function refuse(tool: string, collection: string, skill: string, error: string): SkillToolResult {
+  return {
+    content: [{ type: "text", text: `REFUSED · ${error}` }],
+    details: { subject: `${collection}/${skill}`, label: "refused", summary: error, tone: "error" },
+    structuredContent: { ok: false, collection, skill, tool, error },
+    isError: true,
+  };
+}
+
+interface LeafSkill {
+  directory: string;
+  skillFile: string;
+  content: string;
+}
+
+/** Read one materialized leaf skill, refusing anything that is not a regular file
+ * inside the router's exposed collection tree. Containment is anchored on the
+ * router root, because a symlinked `exposed` would otherwise move the base that
+ * the leaf's own resolution is compared against. */
+function readLeafSkill(root: string, collection: RegistryCollection, route: RegistryRoute): LeafSkill {
+  const exposedTree = join(root, "exposed");
+  const exposed = exposedCollectionsDir(root);
+  if (!isRealDirectory(exposedTree) || !isRealDirectory(exposed)) {
+    throw new Error(`Skill Router's exposed collections are unavailable at ${exposed}`);
+  }
+  const directory = leafSkillDir(root, collection.id, route.skill);
+  if (!isRealDirectory(directory)) {
+    throw new Error(`Skill "${route.skill}" of collection "${collection.id}" is not materialized at ${directory}`);
+  }
+  const skillFile = leafSkillFile(root, collection.id, route.skill);
+  let stats: Stats;
+  try {
+    stats = lstatSync(skillFile);
+  } catch {
+    throw new Error(`Skill "${route.skill}" of collection "${collection.id}" has no instruction file at ${skillFile}`);
+  }
+  if (!stats.isFile()) {
+    throw new Error(`Skill "${route.skill}" of collection "${collection.id}" has an unusable instruction file at ${skillFile}`);
+  }
+  const resolved = realpathSync(skillFile);
+  if (!resolved.startsWith(realpathSync(exposed) + sep) || !resolved.startsWith(realpathSync(root) + sep)) {
+    throw new Error(`Skill "${route.skill}" of collection "${collection.id}" resolves outside the exposed collections`);
+  }
+  return { directory, skillFile, content: readRegularFile(skillFile, stats) };
+}
+
+/** Cut a body at the bound and name the file that keeps the rest. */
+function boundSkillBody(content: string, skillFile: string): { body: string; truncated: boolean } {
+  if (content.length <= MAX_SKILL_BODY_CHARS) return { body: content, truncated: false };
+  let end = MAX_SKILL_BODY_CHARS;
+  // Never split a UTF-16 surrogate pair at the cut.
+  if (/[\uD800-\uDBFF]/.test(content[end - 1] ?? "")) end -= 1;
+  const omitted = content.length - end;
+  return { body: `${content.slice(0, end)}\n\n…${omitted} chars truncated…\nComplete instructions: ${skillFile}`, truncated: true };
+}
+
+function isRealDirectory(path: string): boolean {
+  try {
+    const stats = lstatSync(path);
+    return stats.isDirectory() && !stats.isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/** Read a managed file only when it is a regular file inside the router root. */
+function managedFile(root: string, path: string): string | undefined {
+  try {
+    const stats = lstatSync(path);
+    if (!stats.isFile()) return undefined;
+    if (!realpathSync(path).startsWith(realpathSync(root) + sep)) return undefined;
+    return readRegularFile(path, stats);
+  } catch {
+    return undefined;
+  }
+}
+
+/** One lifecycle geometry for every skill row, owned by pi-kit. */
+const rows = bindLifecycleRenderers({
+  fit: truncateToWidth,
+  visibleWidth,
+  wrapDetail: (line, width) => wrapTextWithAnsi(line, Math.max(1, width)),
+  expandHint: () => keyHint("app.tools.expand", "to expand"),
+});
+
+const skillResultBand = rows.result<AgentToolResult<SkillToolDetails>>((value) => {
+  const details = (value.details ?? {}) as SkillToolDetails;
+  return {
+    tool: TOOL_TAG,
+    kind: "event" as const,
+    label: details.label,
+    subject: details.subject ?? "",
+    ...(details.summary ? { summary: [details.summary] } : {}),
+    ...(details.details ? { details: details.details } : {}),
+    ...(details.tone ? { tone: details.tone } : {}),
+  };
+});

package/src/sync.ts

@@ -17,7 +17,7 @@ import {
 } from "node:fs";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
-import { cacheDir, exposedDir, gatewayDir, leafSkillFile, legacyExposedDir } from "./paths";
+import { cacheDir, exposedDir, gatewayDir, leafSkillFile, legacyExposedDir, skillToolName } from "./paths";
 import { isCollectionId, isSafeGitRef, isSlug, loadCollections, saveCollections, type RegistryCollection, type RegistryRoute } from "./registry";
 
 export interface RepoSpec {
@@ -343,7 +343,7 @@ function gatewayContent(root: string, collection: RegistryCollection, leaves: Up
   const gateway = gatewayDir(root, collection.id, collection.gateway);
   const workflows = leaves.map((skill) => [
     `- \`${skill.name}\` — ${collection.routes.find((route) => route.skill === skill.name)?.summary ?? fallbackWorkflowSummary(skill.description)}`,
-    `  Read \`${relative(gateway, leafSkillFile(root, collection.id, skill.name))}\` before applying this workflow.`,
+    `  Tool \`${skillToolName(collection.id, skill.name)}\`, file \`${relative(gateway, leafSkillFile(root, collection.id, skill.name))}\`.`,
   ]).flat();
 
   return [
@@ -354,7 +354,7 @@ function gatewayContent(root: string, collection: RegistryCollection, leaves: Up
     "",
     "## Available workflows",
     "",
-    "Select the one workflow that best fits the user's request, then read its SKILL.md before proceeding.",
+    "Select the one workflow that best fits the user's request, call its tool, and follow the returned instructions. The listed file holds the same instructions and resolves the workflow's own files.",
     "",
     ...workflows,
     "",