simple-skills-manager 1.0.1

package/docs/config.md

@@ -0,0 +1,117 @@
+# Configuration reference
+
+Everything lives in one file:
+
+```
+~/.pi/agent/simple-skills-manager.json
+```
+
+- The file is **JSONC**: `//` line comments and `/* */` block comments are
+  allowed when you edit by hand. Saving from `/skills-manager` rewrites the
+  file and strips comments.
+- On first run the extension creates a commented starter file, seeded with
+  the built-in **store** root, and creates the skill store directory
+  `~/.pi/agent/managed-skills`.
+- A file that exists but is unparseable or structurally invalid fails loudly:
+  no skills are registered and the reason is surfaced at startup and in
+  `/skills-manager`.
+- Each `registrar[]` entry is validated **independently**. A malformed entry
+  is kept in the file, flagged with issues (visible in the tree), and skipped
+  — it never prevents other entries from loading.
+- Every save is atomic (temp file + rename, mode 0600).
+
+**Vocabulary.** The *library* is the corpus of all skills known to the
+manager. The *registrar* is the corpus of directory roots the library is
+scanned from — in the TUI all roots sit flat next to each other. The
+*store* is the built-in root where skills added through the TUI
+accumulate. *Native* roots are pi's own discovery locations.
+
+## Top level
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `version` | number | `1` | Config format version. Only `1` is supported. |
+| `settings` | object | `{}` | Extension-level tunables (below). All optional. |
+| `registrar` | array | `[]` | Library roots. May be empty; the starter seeds the store root. |
+
+## `settings`
+
+| Field | Type | Default | Range | Description |
+|---|---|---|---|---|
+| `maxResultBytes` | int | `51200` | 1024–10485760 | Per-invocation skill text output cap, in bytes. |
+| `maxResultLines` | int | `2000` | 1–1000000 | Per-invocation skill text output line cap. |
+| `maxSkills` | int | `200` | 1–1000 | Max skills one root's approved manifest may hold. |
+| `toolNameLimit` | int | `64` | 16–128 | Max length of registered `skill_<root>__<skill>` tool names. |
+| `maxSkillBytes` | int | `131072` | 1024–1048576 | Max size of one skill instruction file. |
+| `maxScanFiles` | int | `4096` | 10–100000 | Max filesystem entries one scan may visit. |
+
+Invalid values fall back to their defaults and are reported as settings issues
+(they are tunables, not security boundaries — the hard bounds above always
+apply regardless of what is configured).
+
+## `registrar[]`
+
+Every entry requires `name`, `enabled`, `transport`, and `path`.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `name` | string | yes | 1–48 chars: lowercase letters, numbers, single hyphens. Must be unique. |
+| `enabled` | boolean | yes | Whether this root's approved skills may be invoked. |
+| `transport` | `"skills-dir"` \| `"single-skill"` | yes | `skills-dir` scans recursively for skill directories (and root-level `.md` skill files); `single-skill` expects exactly one `SKILL.md` at the root. |
+| `path` | string | yes | The directory to scan. `~`, `${workspace}`, and `${home}` are expanded; `${...}` variables resolve from the launching environment and fail closed when missing. Must be a regular directory (symlinked roots are rejected). |
+| `store` | boolean | — | Marks the built-in store root. At most one allowed; its path is pinned to `~/.pi/agent/managed-skills`. Set automatically by the starter. |
+| `native` | boolean | — | Marks a native pi discovery location (`~/.pi/agent/skills`, `~/.agents/skills`). Set automatically whenever the path matches. **Auto-adoption:** native locations that exist on disk but are not in the registrar are seeded automatically on load — disabled, unapproved, flagged "Auto-detected" in the tree; *Scan or refresh* adopts them. Persisted to the file only once a save blesses them. Native exposure is mirrored, not gated (see README). |
+| `connection` | `"lazy"` | — | Only `lazy` is supported; may be omitted. |
+| `skills` | object | — | `{ "mode": "all" \| "selected", "include": [names] }`. `include` must be empty when mode is `all`. |
+| `manifest` | object | — | Approved skill manifest (below). Written by *Scan or refresh* and the add/edit flows; never write it by hand. |
+
+### `manifest`
+
+The approved snapshot of a root's scan:
+
+| Field | Type | Description |
+|---|---|---|
+| `version` | number | `1`. |
+| `fingerprint` | string | SHA-256 over the root identity (`name`, `transport`, `path`). Changing any of those invalidates the manifest — this is what binds an approval to an exact directory. |
+| `scannedAt` | string | ISO timestamp of the inspection. |
+| `skills` | array | Approved skill snapshots (below). |
+| `rejected` | array | Skills found but rejected, with `dirPath` and `reason` — kept for TUI visibility. |
+
+### `manifest.skills[]`
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | string | Frontmatter name. 1–64 chars, lowercase letters, numbers, single hyphens (Agent Skills standard). Unique within the root. |
+| `description` | string | Frontmatter description. Required, ≤ 1024 chars, sanitized. |
+| `dirPath` | string | Skill directory relative to the root (`.` for single-skill roots and root-level `.md` files). No `..`, no absolute paths. |
+| `file` | string | Instruction file name inside the skill directory. Defaults to `SKILL.md`; set for root-level `.md` skill files. |
+| `contentHash` | string | SHA-256 of the instruction file's bytes. **The drift guarantee:** every invocation re-hashes the bytes it delivers against this. |
+| `fileCount` | number | Files in the skill directory (informational). |
+| `executableScripts` | array | Shebang files inside the skill directory — flagged because the model may be instructed to execute them. |
+| `hidden` | boolean | Frontmatter `disable-model-invocation: true`: no tool, only the `skill:<name>` command. |
+
+## Importing skills
+
+`/skills-manager` → *Add a skill to the store* offers three methods:
+
+- **Write in the editor** — guided name/group/description, scaffolded SKILL.md.
+- **Import an .md file** — copied into `store/[group/]<name>/SKILL.md`
+  (the original is untouched); frontmatter is derived or prompted.
+- **Import a directory** — the whole directory is copied wholesale. If it has
+  no `SKILL.md` at its root, the TUI prints its tree (all depths up to 4)
+  and asks you to type the full path of the intended `SKILL.md`.
+
+Copies enforce the same hygiene as scans: symlinks are skipped and
+reported, per-file size and total file-count bounds apply, destination
+collisions are refused. Writing through the manager is an approval act —
+the snapshot is refreshed automatically. Hand edits outside the manager
+change the content hash and fail closed at the next invocation until you
+*Scan or refresh*.
+
+## Migrating
+
+On-disk state is the one config file plus the plain-file store. To reset
+everything: delete the config file (a starter with an empty store root is
+recreated on the next run) and, if you like, the `managed-skills`
+directory. Skills are ordinary Markdown directories — they can be moved,
+copied, and version-controlled freely; re-scan after moving a root.

package/docs/discovery.md

@@ -0,0 +1,93 @@
+# The scan surface — what is read from disk
+
+The scanner is the filesystem equivalent of a protocol client: a small,
+auditable, fail-closed subset of what *could* be read. This page documents
+exactly what crosses the "wire".
+
+## Discovery rules
+
+- A root path must be a **regular directory** — symlinked roots are
+  rejected, and symlinks inside the tree are skipped with a warning, never
+  followed.
+- `skills-dir` transport: any directory containing `SKILL.md` is a skill;
+  group directories (no `SKILL.md`) are recursed into, up to depth 8.
+  Directories that are skills are **not** recursed further.
+- Root-level `*.md` files with valid skill frontmatter are skills too
+  (mirroring pi's own native discovery of `~/.pi/agent/skills`); `.md`
+  files without skill frontmatter are ignored silently.
+- `single-skill` transport: exactly one `SKILL.md` at the root.
+- One scan may visit at most `settings.maxScanFiles` filesystem entries and
+  hold at most `settings.maxSkills` skills — both fail closed with
+  readable errors.
+
+## Frontmatter subset
+
+A deliberately minimal YAML parser: `---` fences around `key: value`
+lines. Supported: quoted values, `#` comments, unknown keys (ignored).
+**Not** supported — they reject the skill with a readable reason:
+block scalars (`|`, `>`), nested structures, multi-line values, empty
+values. Required keys: `name` (1–64 chars, lowercase letters, numbers,
+single hyphens) and `description` (non-empty, ≤ 1024 chars).
+`disable-model-invocation: true` hides the skill from the model.
+
+## What is recorded per skill
+
+- `name`, `description` (sanitized of control characters),
+- `dirPath` (+ `file` for root-level `.md` skills),
+- `contentHash` — SHA-256 of the instruction file's bytes **at scan time**,
+- `fileCount` — the number of files in the skill directory,
+- `executableScripts` — files starting with a shebang (`#!`), flagged
+  because the model may be instructed to execute them,
+- `hidden` — from `disable-model-invocation`.
+
+Duplicate skill names within a root: the first wins, later ones are
+rejected with a reason (kept in the manifest's `rejected` list so the tree
+shows exactly where the manager's strictness disagrees with pi's leniency).
+
+## What is never done
+
+- No file is ever **executed**, parsed as code, or written during a scan —
+  scans only read.
+- Nothing outside the root path is read.
+- The manager never writes into roots that are not the store; external and
+  native roots are read-only to it.
+- Store skills are written only through the add/edit flows (atomic
+  temp-file writes), and removals are refused outside `managed-skills/`.
+
+## Trust model
+
+Skill text is **untrusted display data**: sanitized, size-bounded
+(`settings.maxResultBytes` / `maxResultLines`), and delivered with a
+content hash comparison on every invocation. The security boundary is your
+inspection during *Scan or refresh* (or your authorship through the
+add/edit flows), bound two ways:
+
+- the **manifest fingerprint** binds the approval to the exact root
+  (`name`, `transport`, `path`) — move or rename the root and the approval
+  is void;
+- the **content hash** binds it to the exact `SKILL.md` bytes — edit the
+  file outside the manager and every invocation fails closed until you
+  refresh.
+
+What is *not* bound: helper scripts and reference files are inventoried
+(and shebang files flagged) at scan time but not hash-checked. They may
+change after approval, exactly as an MCP server's code may change while
+only its schemas are bound. Re-scan before trusting; review executable
+scripts; use a container or VM when you need real isolation.
+
+## Native roots, precisely
+
+For roots marked `native` (pi's `~/.pi/agent/skills`, `~/.agents/skills`):
+
+- While pi's native discovery is **active**, every skill the scan approves
+  whose instruction file appears in the session's loaded-skills list is
+  exposed as a **mirror**: registered through the manager's drift-checked
+  surfaces (tool + shadowed `skill:<name>` command), shown red and locked
+  in the tree. The manager cannot revoke pi's own listing — that requires
+  removing the files or launching pi with `--no-skills`.
+- In **library-only mode** (`pi --no-skills`), nothing is natively
+  exposed, the mirror rule finds nothing, and the standard gate
+  (approved + selected + enabled) applies in full.
+- Skills pi is exposing that the manager rejected or has not yet scanned
+  are shown in the tree as unapproved-but-live (red), so the library view
+  is always the complete truth of what the model can see.

package/index.ts

@@ -0,0 +1,419 @@
+/**
+ * simple-skills-manager — a pi extension for exposing reviewed skills to
+ * the model and to the user.
+ *
+ * Everything lives in ONE config file, ~/.pi/agent/simple-skills-manager.json:
+ * extension settings, every library root (the registrar), and each root's
+ * approved skill manifest. Skills themselves are plain files: the built-in
+ * store accumulates them at ~/.pi/agent/managed-skills, external roots
+ * point at directories you already have, and native pi locations
+ * (~/.pi/agent/skills, ~/.agents/skills) are adopted as mirrors of the
+ * exposure pi itself already creates. The file is created with commented
+ * defaults on first run, is fully manageable from the /skills-manager TUI
+ * (see menu.ts), and may also be edited by hand (JSONC comments allowed;
+ * TUI saves strip them).
+ *
+ * Three decisions are kept separate on purpose:
+ *   1. Configuration — where a root is and how the library is scanned.
+ *   2. Manifest approval — which skill names, descriptions, and content
+ *      hashes a user inspected, fingerprinted to the exact root.
+ *   3. Invocation — whether the model may load a particular skill now.
+ *
+ * Loading is lazy: a root's directory is never scanned merely because pi
+ * starts. The first approved invocation opens the scan.
+ *
+ * Exposure surfaces, per approved skill:
+ *   - a namespaced tool `skill_<root>__<skill>` the model calls to load
+ *     the instructions (bounded, sanitized, drift-checked on delivery);
+ *   - a `skill:<skill>` command the user calls, shadowing pi's native
+ *     skill-command namespace (extension commands dispatch first), which
+ *     loads through the same drift-checked path and injects the content
+ *     as a user message, exactly like native /skill:name.
+ *
+ * This module is the core: output bounding, tool naming, the scan cache,
+ * the invocation loader, tool and command registration, and the extension
+ * entry point. The interactive library management lives in menu.ts.
+ */
+
+import { createHash } from "node:crypto";
+import { lstat, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { AgentToolResult, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import {
+    CONFIG_PATH,
+    DEFAULT_SETTINGS,
+    STORE_DIR,
+    computeExposedSkills,
+    fingerprint,
+    loadManagerConfig,
+    resolvedRootPath,
+    skillGroup,
+    type ManagedRoot,
+    type ManagerConfig,
+    type ManagerSettings,
+    type RootConfig,
+    type SkillSnapshot,
+} from "./config.ts";
+import { scanRoot } from "./scan.ts";
+import { runSkillsManagerMenu } from "./menu.ts";
+import { errText, sanitizeExternalText } from "./util.ts";
+
+// ─── Output bounding (settings-driven) ──────────────────────────────────────
+
+function truncateText(input: string, settings: ManagerSettings): string {
+    const lines = sanitizeExternalText(input).split("\n");
+    let output = lines.slice(0, settings.maxResultLines).join("\n");
+    const marker = "\n\n[Skill content truncated; omitted content was not persisted.]";
+    let truncated = lines.length > settings.maxResultLines;
+    // The marker must land inside the byte budget too, so the delivered text
+    // never exceeds maxResultBytes even when truncated.
+    while (output.length > 0 && Buffer.byteLength(output) + marker.length > settings.maxResultBytes) {
+        output = output.slice(0, Math.floor(output.length * 0.9));
+        truncated = true;
+    }
+    // Do not leave a split UTF-16 surrogate pair at the cut.
+    output = output.replace(/[\ud800-\udbff]$/, "");
+    return truncated ? `${output}${marker}` : output;
+}
+
+/** Assemble the bounded text a skill invocation delivers: the skill's
+ *  absolute directory (so relative script and reference paths resolve),
+ *  the sanitized instructions, and an optional user request. */
+export function skillLoadText(name: string, rootName: string, skillDir: string, content: string, request: string | undefined, settings: ManagerSettings): string {
+    const header = `Skill '${name}' from the '${rootName}' root of the skills library.\nSkill directory: ${skillDir}\n\n`;
+    const tail = request
+        ? `\n\nUser: ${sanitizeExternalText(request).slice(0, 4_096)}`
+        : `\n\n[Skill instructions end here. Use relative paths from the skill directory.]`;
+    return truncateText(`${header}${sanitizeExternalText(content)}${tail}`, settings);
+}
+
+// ─── Tool naming ────────────────────────────────────────────────────────────
+
+function skillSlug(value: string): string {
+    // Skill names are already lowercase a-z0-9 with single hyphens (validated
+    // at approval), so hyphens are preserved — the tool name mirrors the
+    // skill name. Anything else collapses to underscores.
+    return value.toLowerCase().replace(/[^a-z0-9_-]+/g, "_").replace(/^[\-_]+|[\-_]+$/g, "") || "skill";
+}
+
+/**
+ * Build the Pi tool name for a skill: `skill_<root>__<skill>`.
+ * The skill_ prefix, normalized root name, and normalized skill name prevent
+ * a skill called "read" from replacing Pi's built-in tools. The result never
+ * exceeds settings.toolNameLimit; truncation is disambiguated with a hash
+ * suffix whenever the remaining budget allows one.
+ */
+export function piSkillToolName(root: string, skill: string, nameLimit: number = DEFAULT_SETTINGS.toolNameLimit): string {
+    const hash = (seed: string, length: number): string => createHash("sha256").update(seed).digest("hex").slice(0, length);
+    /** Fit `part` into `budget`, suffixing a hash of `seed` for disambiguation
+     *  when the budget has room for one. */
+    const fit = (part: string, budget: number, seed: string, hashLength: number): string => {
+        if (part.length <= budget) return part;
+        if (budget <= hashLength) return part.slice(0, budget);
+        return `${part.slice(0, budget - hashLength - 1)}_${hash(seed, hashLength)}`;
+    };
+    const rootPart = fit(skillSlug(root), Math.max(4, Math.floor(nameLimit / 3)), root, 6);
+    const prefix = `skill_${rootPart}__`;
+    const suffix = fit(skillSlug(skill), Math.max(1, nameLimit - prefix.length), skill, 8);
+    return `${prefix}${suffix}`;
+}
+
+// ─── Scan cache ────────────────────────────────────────────────────────────
+
+type LiveSkill = { dirPath: string; file?: string; hidden: boolean };
+type ScanEntry = { rootPath: string; liveSkills: Map<string, LiveSkill> };
+
+/** Scan cache: one lazy directory scan per (root, fingerprint), reused
+ *  across invocations, evicted when a read fails, cleared on shutdown.
+ *  Exported so the exact production cache/invocation path is testable. */
+export function createScanCache(settings: ManagerSettings = DEFAULT_SETTINGS) {
+    const scans = new Map<string, Promise<ScanEntry>>();
+
+    function cacheKey(root: RootConfig): string {
+        return `${root.name}:${fingerprint(root)}`;
+    }
+
+    function evictScan(root: RootConfig): void {
+        scans.delete(cacheKey(root));
+    }
+
+    async function getScan(root: RootConfig, workspace: string, signal?: AbortSignal): Promise<ScanEntry> {
+        const key = cacheKey(root);
+        let pending = scans.get(key);
+        if (!pending) {
+            pending = (async () => {
+                const outcome = await scanRoot(root, workspace, settings, signal);
+                return {
+                    rootPath: resolvedRootPath(root, workspace),
+                    liveSkills: new Map(outcome.skills.map((skill) => [skill.name, {
+                        dirPath: skill.dirPath,
+                        file: skill.file,
+                        hidden: skill.hidden === true,
+                    } as LiveSkill])),
+                };
+            })();
+            scans.set(key, pending);
+            pending.catch(() => scans.delete(key));
+        }
+        return pending;
+    }
+
+    async function shutdown(): Promise<void> {
+        scans.clear();
+    }
+
+    return { getScan, evictScan, shutdown };
+}
+
+// ─── Invocation loader ──────────────────────────────────────────────────────
+
+/** Load one approved skill through the production path: lazily scan the
+ *  root (cached per session), then re-hash the bytes actually read against
+ *  the approved snapshot — drift fails closed, and the drift check runs on
+ *  the content being delivered, not on a stale copy. Exported for tests. */
+export async function loadSkillForInvocation(
+    root: RootConfig,
+    snapshot: SkillSnapshot,
+    settings: ManagerSettings,
+    getScan: (root: RootConfig, workspace: string, signal?: AbortSignal) => Promise<ScanEntry>,
+    evictScan: (root: RootConfig) => void,
+    workspace: string,
+    signal: AbortSignal | undefined,
+    notify: (message: string, level: "info" | "warning" | "error") => void,
+    request: string | undefined,
+): Promise<{ text: string; skillDir: string; skillPath: string }> {
+    const scan = await getScan(root, workspace, signal);
+    const live = scan.liveSkills.get(snapshot.name);
+    if (!live || live.hidden !== (snapshot.hidden === true)) {
+        // The directory changed since the scan; do not let the stale scan
+        // poison the cache — let the next call re-scan.
+        evictScan(root);
+        notify(`${root.name}/${snapshot.name} changed since approval. Refresh it through /skills-manager before use.`, "warning");
+        throw new Error("Skill manifest drift detected; refresh and approve the root before retrying.");
+    }
+    const skillPath = join(scan.rootPath, live.dirPath === "." ? "" : live.dirPath, live.file ?? "SKILL.md");
+    const skillDir = join(scan.rootPath, live.dirPath === "." ? "" : live.dirPath);
+    try {
+        const info = await lstat(skillPath);
+        if (info.isSymbolicLink() || !info.isFile()) throw new Error("The skill's instruction file must be a regular file, not a symbolic link.");
+        if (info.size > settings.maxSkillBytes) throw new Error(`The skill's instruction file exceeds settings.maxSkillBytes (${settings.maxSkillBytes} bytes).`);
+        const bytes = await readFile(skillPath);
+        const liveHash = createHash("sha256").update(bytes).digest("hex");
+        if (liveHash !== snapshot.contentHash) {
+            notify(`${root.name}/${snapshot.name} changed since approval. Refresh it through /skills-manager before use.`, "warning");
+            throw new Error("Skill content drift detected; refresh and approve the root before retrying.");
+        }
+        const text = skillLoadText(snapshot.name, root.name, skillDir, bytes.toString("utf8"), request, settings);
+        return { text, skillDir, skillPath };
+    } catch (error) {
+        // A changed directory must not poison the cache; let the next call re-scan.
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") evictScan(root);
+        throw error;
+    }
+}
+
+export type ManagedSkillExecutor = {
+    name: string;
+    execute: (
+        toolCallId: string,
+        params: Record<string, unknown>,
+        signal: AbortSignal | undefined,
+        onUpdate: ((partial: AgentToolResult<unknown>) => void) | undefined,
+        ctx: ExtensionContext,
+    ) => Promise<AgentToolResult<unknown>>;
+};
+
+/** Build the execute wrapper for one approved skill. Exported for tests. */
+export function buildManagedSkillExecutor(
+    root: RootConfig,
+    snapshot: SkillSnapshot,
+    settings: ManagerSettings,
+    getScan: (root: RootConfig, workspace: string, signal?: AbortSignal) => Promise<ScanEntry>,
+    evictScan: (root: RootConfig) => void,
+): ManagedSkillExecutor {
+    return {
+        name: piSkillToolName(root.name, snapshot.name, settings.toolNameLimit),
+        async execute(_toolCallId, params, signal, onUpdate, ctx) {
+            onUpdate?.({ content: [{ type: "text", text: `Scanning library root ${root.name}...` }], details: {} });
+            const { text, skillDir, skillPath } = await loadSkillForInvocation(
+                root, snapshot, settings, getScan, evictScan,
+                ctx.cwd, signal, ctx.ui.notify,
+                typeof params.request === "string" && params.request.trim() ? params.request.trim() : undefined,
+            );
+            onUpdate?.({ content: [{ type: "text", text: `Loading skill ${root.name}/${snapshot.name}...` }], details: {} });
+            return {
+                content: [{ type: "text", text }],
+                details: { root: root.name, skill: snapshot.name, skillDir, skillPath },
+            };
+        },
+    };
+}
+
+// ─── Registration ──────────────────────────────────────────────────────────
+
+function registerManagedSkill(
+    pi: ExtensionAPI,
+    root: RootConfig,
+    snapshot: SkillSnapshot,
+    settings: ManagerSettings,
+    guidelines: string[] | undefined,
+    getScan: (root: RootConfig, workspace: string, signal?: AbortSignal) => Promise<ScanEntry>,
+    evictScan: (root: RootConfig) => void,
+): void {
+    const group = skillGroup(snapshot.dirPath);
+    // The tool: how the model loads the skill. Hidden skills stay command-only,
+    // mirroring pi's native disable-model-invocation semantics.
+    if (!snapshot.hidden) {
+        const executor = buildManagedSkillExecutor(root, snapshot, settings, getScan, evictScan);
+        pi.registerTool({
+            name: executor.name,
+            label: `${root.name}: ${snapshot.name}`,
+            description: `[Skill library ${root.name}] ${(snapshot.description).slice(0, 8_192)}`,
+            promptSnippet: `[skill] library/${root.name}/${group}/${snapshot.name} — ${snapshot.description.replace(/\s+/g, " ").slice(0, 100)}`,
+            promptGuidelines: guidelines,
+            parameters: Type.Unsafe<{ request?: string }>({
+                type: "object",
+                properties: {
+                    request: { type: "string", description: "Optional user request, appended to the skill instructions" },
+                },
+                additionalProperties: false,
+            }),
+            execute: executor.execute,
+        });
+    }
+    // The command: how the user loads the skill. Extension commands dispatch
+    // before pi's native skill expansion, so `skill:<name>` is ours.
+    pi.registerCommand(`skill:${snapshot.name}`, {
+        description: `${group}/${snapshot.name} — ${snapshot.description.replace(/\s+/g, " ").slice(0, 120)}`,
+        handler: async (args, ctx) => {
+            try {
+                const { text } = await loadSkillForInvocation(
+                    root, snapshot, settings, getScan, evictScan,
+                    ctx.cwd, undefined, ctx.ui.notify,
+                    args?.trim() ? args.trim() : undefined,
+                );
+                pi.sendUserMessage(text, { deliverAs: "steer" });
+            } catch (error) {
+                ctx.ui.notify(`skill:${snapshot.name}: ${errText(error)}`, "error");
+            }
+        },
+    });
+}
+
+// ─── Extension entry point ─────────────────────────────────────────────────
+
+export default function skillsManagerExtension(pi: ExtensionAPI): void {
+    const registeredToolNames = new Map<string, string>();
+    const registeredCommandNames = new Map<string, string>();
+    let cache: ReturnType<typeof createScanCache> | undefined;
+    let config: ManagerConfig | undefined;
+    let nativeRegistered = false;
+
+    function registerRoots(roots: ManagedRoot[], nativeActivePaths: Set<string>, ctx: ExtensionContext): void {
+        if (!cache || !config) return;
+        const usableRoots = config.roots.filter((root) => root.normalized && !root.issues.length && root.config.enabled && root.config.manifest);
+        const registerable = roots.filter((root) => root.normalized && !root.issues.length && root.config.enabled && root.config.manifest);
+        // Harness-level self-awareness: these lines are merged into the
+        // Guidelines section of every chat's system prompt, so even a virgin
+        // chat knows where its skill machinery lives. They are attached to
+        // the FIRST registered skill tool only — pi appends promptGuidelines
+        // flat per tool, so repeating them on every tool would duplicate the
+        // lines once per exposed skill.
+        const awareness = [
+            "Managed skills: all library roots and approved skill manifests live in ~/.pi/agent/simple-skills-manager.json; manage them interactively with the /skills-manager command (add, import, scan, approve, expose, edit, remove).",
+            `Skills currently exposed: ${
+                usableRoots.map((root) => {
+                    const names = computeExposedSkills(root.config, ctx.cwd, nativeActivePaths).map((skill) => skill.name);
+                    const list = names.length
+                        ? names.slice(0, 60).join(", ") + (names.length > 60 ? ", …" : "")
+                        : "no skills exposed";
+                    return `${root.config.name} (${list})`;
+                }).join("; ")
+                || "(none configured — add one via /skills-manager)"
+            }. Hidden skills load via skill:<name> commands only.`,
+        ];
+        let awarenessAttached = false;
+        for (const root of registerable) {
+            for (const skill of computeExposedSkills(root.config, ctx.cwd, nativeActivePaths)) {
+                const toolName = piSkillToolName(root.config.name, skill.name, config.settings.toolNameLimit);
+                const owner = `${root.config.name}/${skill.name}`;
+                const priorTool = registeredToolNames.get(toolName);
+                if (priorTool && priorTool !== owner) {
+                    ctx.ui.notify(`Skill tool name collision: ${priorTool} and ${owner}; ${owner} was not registered as a tool.`, "error");
+                    continue;
+                }
+                const priorCommand = registeredCommandNames.get(`skill:${skill.name}`);
+                if (priorCommand && priorCommand !== owner) {
+                    ctx.ui.notify(`Skill command collision: skill:${skill.name} already serves ${priorCommand}; ${owner} was not registered as a command.`, "error");
+                    continue;
+                }
+                registeredToolNames.set(toolName, owner);
+                registeredCommandNames.set(`skill:${skill.name}`, owner);
+                const group = skillGroup(skill.dirPath);
+                // Per-tool guidelines always name their tool (pi renders them
+                // flat, with no tool prefix); the shared awareness lines ride
+                // along only on the first registered tool.
+                const perTool = [
+                    `Use ${toolName} to load the ${root.config.name}/${group}/${skill.name} skill instructions when that skill is relevant to the task.`,
+                ];
+                // Hidden skills register a command only; the shared awareness
+                // lines must ride on the first *tool*.
+                const guidelines = skill.hidden ? [] : awarenessAttached ? perTool : [...awareness, ...perTool];
+                if (!skill.hidden) awarenessAttached = true;
+                registerManagedSkill(pi, root.config, skill, config.settings, guidelines, cache.getScan, cache.evictScan);
+            }
+        }
+    }
+
+    pi.on("session_start", async (_event, ctx) => {
+        try {
+            config = await loadManagerConfig();
+        } catch (error) {
+            ctx.ui.notify(`simple-skills-manager: ${errText(error)}`, "error");
+            return;
+        }
+        cache = createScanCache(config.settings);
+        nativeRegistered = false;
+        if (config.created) {
+            ctx.ui.notify(
+                `simple-skills-manager: created a starter config at ${CONFIG_PATH} and a skill store at ${STORE_DIR}. Run /skills-manager to add your first skill.`,
+                "info",
+            );
+        }
+        if (config.settingsIssues.length) {
+            ctx.ui.notify(`simple-skills-manager settings issue(s): ${config.settingsIssues[0]}`, "warning");
+        }
+        // Standard roots register immediately; native roots wait for the
+        // first before_agent_start, where pi's own loaded-skills list is
+        // available for live mirror detection.
+        registerRoots((config?.roots ?? []).filter((root) => !root.config.native), new Set(), ctx);
+    });
+
+    pi.on("before_agent_start", async (event, ctx) => {
+        if (nativeRegistered || !config || !cache) return;
+        nativeRegistered = true;
+        const nativeRoots = config.roots.filter((root) => root.config.native);
+        if (!nativeRoots.length) return;
+        // Live native-exposure detection: whatever pi's own discovery loaded
+        // into this session is mirrored (never gated) for native roots.
+        const nativeActivePaths = new Set<string>(
+            ((event.systemPromptOptions?.skills ?? []) as { filePath?: string }[]).map((skill) => skill.filePath ?? ""),
+        );
+        registerRoots(nativeRoots, nativeActivePaths, ctx);
+    });
+
+    pi.on("session_shutdown", async () => {
+        await cache?.shutdown();
+        cache = undefined;
+        config = undefined;
+    });
+
+    pi.registerCommand("skills-manager", {
+        description: "Browse, add, import, scan, approve, expose, edit, or remove library skills and roots, or edit extension settings",
+        handler: async (_args, ctx) => {
+            if (ctx.mode !== "tui") return void ctx.ui.notify("/skills-manager requires TUI mode", "error");
+            await runSkillsManagerMenu(ctx);
+        },
+    });
+}