simple-skills-manager 1.0.1

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "simple-skills-manager",
+  "version": "1.0.1",
+  "description": "A pi extension for exposing reviewed skills to the model: a single JSONC config file holds every library root (the registrar) and approved skill manifest, /skills-manager manages everything interactively in a tree navigator, skills are hash-bound and fail closed on drift, and native pi skill locations are adopted as honest mirrors.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "skills",
+    "agent-skills"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "files": ["*"],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bash tests/smoke.sh"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "pi": {
+    "extensions": ["./index.ts"]
+  }
+}

package/scan.ts

@@ -0,0 +1,397 @@
+/**
+ * The scanner — the filesystem equivalent of an MCP protocol client. It is
+ * the ONLY code that reads skill content from disk, behind a small,
+ * auditable, fail-closed surface (see docs/discovery.md):
+ *
+ *   - one bounded recursive walk per root (settings.maxScanFiles entries,
+ *     depth capped at 8, symlinks skipped with an issue — never followed);
+ *   - one bounded read per SKILL.md (settings.maxSkillBytes, hashed with
+ *     SHA-256 the moment it is read);
+ *   - a minimal frontmatter parser (key: value lines only);
+ *   - a file inventory per skill, flagging executable scripts (shebang
+ *     files the model may be instructed to run);
+ *   - root-level *.md files with valid skill frontmatter are recognized as
+ *     skills, mirroring pi's native discovery of ~/.pi/agent/skills;
+ *   - rejected skills are reported (not silently dropped) so the TUI can
+ *     show exactly where the manager's strictness disagrees with pi's
+ *     leniency.
+ *
+ * Also home to the copy helpers the import flows use, with the same bounds.
+ */
+
+import { createHash } from "node:crypto";
+import { lstat, mkdir, open, readFile, readdir, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, sep } from "node:path";
+import {
+    MAX_SKILL_DESC_CHARS,
+    MAX_SKILL_NAME_CHARS,
+    SKILL_NAME_RE,
+    resolvedRootPath,
+    type ManagerSettings,
+    type RejectedSkill,
+    type RootConfig,
+    type SkillSnapshot,
+} from "./config.ts";
+
+export const MAX_SCAN_DEPTH = 8;
+export const MAX_EXECUTABLE_SHOWN = 32;
+export const MAX_COPY_FILE_BYTES = 10 * 1024 * 1024;
+
+/** Read the first `count` bytes of a file without loading it whole — the
+ *  shebang check must not read entire files (skill directories can contain
+ *  large assets). Unreadable files yield undefined, like a failed read. */
+async function readFirstBytes(path: string, count: number): Promise<Buffer | undefined> {
+    const handle = await open(path, "r").catch(() => undefined);
+    if (!handle) return undefined;
+    try {
+        const buffer = Buffer.alloc(count);
+        const { bytesRead } = await handle.read(buffer, 0, count, 0);
+        return bytesRead > 0 ? buffer.subarray(0, bytesRead) : undefined;
+    } finally {
+        await handle.close();
+    }
+}
+
+export type ScanOutcome = {
+    skills: SkillSnapshot[];
+    rejected: RejectedSkill[];
+    /** Non-fatal warnings (e.g. skipped symlinks). */
+    issues: string[];
+    scannedAt: string;
+};
+
+// ─── Frontmatter (the deliberately small protocol subset) ───────────────────
+
+/** Parse a minimal YAML frontmatter block: `---` fences around `key: value`
+ *  lines. Quoted values, `#` comments, and unknown keys are tolerated;
+ *  block scalars, nested structures, and multi-line values are not — they
+ *  fail closed with a readable error. */
+export function parseFrontmatter(text: string): { data: Record<string, string> | null; error?: string } {
+    const src = text.replace(/^\uFEFF/, "");
+    if (!src.startsWith("---")) return { data: null, error: "the file does not start with a YAML frontmatter block (a '---' line)." };
+    const lines = src.split("\n");
+    if (lines[0]!.trim() !== "---") return { data: null, error: "the frontmatter opening fence must be a '---' line." };
+    const data: Record<string, string> = {};
+    let i = 1;
+    while (i < lines.length && lines[i]!.trim() !== "---") {
+        const trimmed = lines[i]!.trim();
+        i++;
+        if (!trimmed || trimmed.startsWith("#")) continue;
+        const sep = trimmed.indexOf(":");
+        if (sep <= 0) return { data: null, error: `frontmatter line is not 'key: value': ${trimmed.slice(0, 80)}` };
+        const key = trimmed.slice(0, sep).trim();
+        let value = trimmed.slice(sep + 1).trim();
+        if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(key)) return { data: null, error: `invalid frontmatter key: ${key}` };
+        if (!value) return { data: null, error: `frontmatter key '${key}' has an empty value (block or multi-line values are not supported).` };
+        if (value === "|" || value === ">" || value.endsWith("|") || value.endsWith(">")) {
+            return { data: null, error: `frontmatter key '${key}' uses a block scalar (| or >); block or multi-line values are not supported.` };
+        }
+        if (value.startsWith('"') || value.startsWith("'")) {
+            const quote = value[0]!;
+            const end = value.indexOf(quote, 1);
+            if (end < 1) return { data: null, error: `frontmatter key '${key}' has an unterminated quoted value.` };
+            value = value.slice(1, end); // a trailing comment after the quote is ignored
+        }
+        data[key] = value;
+    }
+    if (i >= lines.length) return { data: null, error: "the frontmatter block is not closed by a '---' line." };
+    return { data };
+}
+
+// ─── Scanning ──────────────────────────────────────────────────────────────
+
+/** Scan one library root. Throws on fatal conditions (root missing or a
+ * symlink, scan budget exceeded, more skills than settings.maxSkills);
+ * returns rejected skills and symlink warnings otherwise. */
+export async function scanRoot(
+    config: RootConfig,
+    workspace: string,
+    settings: ManagerSettings,
+    signal?: AbortSignal,
+): Promise<ScanOutcome> {
+    const rootPath = resolvedRootPath(config, workspace);
+    const issues: string[] = [];
+    const rejected: RejectedSkill[] = [];
+    const skills: SkillSnapshot[] = [];
+    const seen = new Set<string>();
+    let budget = settings.maxScanFiles;
+    let overBudget = false;
+
+    const info = await lstat(rootPath).catch(() => undefined);
+    if (!info) throw new Error(`The root path does not exist: ${rootPath}`);
+    if (info.isSymbolicLink()) throw new Error(`The root path must be a regular directory, not a symbolic link: ${rootPath}`);
+    if (!info.isDirectory()) throw new Error(`The root path must be a directory: ${rootPath}`);
+
+    const spend = (): boolean => {
+        if (budget-- <= 0) {
+            overBudget = true;
+            return false;
+        }
+        return true;
+    };
+
+    /** Read and hash one skill instruction file; reject (never throw) on
+     *  per-skill problems so one bad skill never hides the others. */
+    const readSkill = async (dirRel: string, fileName: string, fileCount: number, executableScripts: string[]): Promise<void> => {
+        const skillPath = join(rootPath, dirRel === "." ? "" : dirRel, fileName);
+        const skillInfo = await lstat(skillPath).catch(() => undefined);
+        if (!skillInfo) {
+            rejected.push({ dirPath: dirRel, reason: `instruction file '${fileName}' not found` });
+            return;
+        }
+        if (skillInfo.isSymbolicLink() || !skillInfo.isFile()) {
+            rejected.push({ dirPath: dirRel, reason: `instruction file '${fileName}' must be a regular file, not a symbolic link` });
+            return;
+        }
+        if (skillInfo.size > settings.maxSkillBytes) {
+            rejected.push({ dirPath: dirRel, reason: `instruction file '${fileName}' exceeds settings.maxSkillBytes (${settings.maxSkillBytes} bytes)` });
+            return;
+        }
+        if (signal?.aborted) throw new Error("Skill scan cancelled.");
+        const bytes = await readFile(skillPath);
+        const parsed = parseFrontmatter(bytes.toString("utf8"));
+        if (!parsed.data) {
+            rejected.push({ dirPath: dirRel, reason: `invalid frontmatter: ${parsed.error}` });
+            return;
+        }
+        const name = parsed.data["name"] ?? "";
+        const description = parsed.data["description"] ?? "";
+        if (!SKILL_NAME_RE.test(name) || !name || name.length > MAX_SKILL_NAME_CHARS) {
+            rejected.push({ dirPath: dirRel, reason: `invalid skill name '${name.slice(0, 80) || "(missing)"}' (1-64 chars, lowercase letters, numbers, single hyphens)` });
+            return;
+        }
+        if (!description.trim() || description.length > MAX_SKILL_DESC_CHARS) {
+            rejected.push({ dirPath: dirRel, reason: `skill '${name}' must have a non-empty description of at most ${MAX_SKILL_DESC_CHARS} characters` });
+            return;
+        }
+        if (seen.has(name)) {
+            rejected.push({ dirPath: dirRel, reason: `duplicate skill name: ${name} (first occurrence wins)` });
+            return;
+        }
+        seen.add(name);
+        skills.push({
+            name,
+            description: description.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, " ").slice(0, MAX_SKILL_DESC_CHARS),
+            dirPath: dirRel,
+            file: fileName === "SKILL.md" ? undefined : fileName,
+            contentHash: createHash("sha256").update(bytes).digest("hex"),
+            fileCount,
+            executableScripts,
+            hidden: parsed.data["disable-model-invocation"] === "true" ? true : undefined,
+        });
+    };
+
+    /** Inventory one skill directory: count files, flag shebang executables. */
+    const inventory = async (dirRel: string): Promise<{ fileCount: number; executableScripts: string[] }> => {
+        const files: { absolute: string; relative: string }[] = [];
+        await collectFiles(join(rootPath, dirRel === "." ? "" : dirRel), dirRel === "." ? "" : dirRel, files);
+        let executable = 0;
+        const executableScripts: string[] = [];
+        for (const file of files) {
+            if (executableScripts.length >= MAX_EXECUTABLE_SHOWN) break;
+            const first = await readFirstBytes(file.absolute, 2);
+            if (first && first[0] === 0x23 && first[1] === 0x21) {
+                executable++;
+                executableScripts.push(file.relative);
+            }
+        }
+        if (executable > executableScripts.length) executableScripts.push(`… (+${executable - executableScripts.length} more)`);
+        return { fileCount: files.length, executableScripts };
+    };
+
+    const collectFiles = async (absolute: string, rel: string, files: { absolute: string; relative: string }[]): Promise<void> => {
+        const entries = await readdir(absolute, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            if (!spend()) return;
+            if (entry.isSymbolicLink()) continue; // fail closed: symlinks are skipped
+            const childAbs = join(absolute, entry.name);
+            const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) await collectFiles(childAbs, childRel, files);
+            else if (entry.isFile()) files.push({ absolute: childAbs, relative: childRel });
+        }
+    };
+
+    if (config.transport === "single-skill") {
+        const { fileCount, executableScripts } = await inventory(".");
+        await readSkill(".", "SKILL.md", fileCount, executableScripts);
+    } else {
+        // Root-level *.md files with skill frontmatter are skills (pi native
+        // discovery does the same in its own locations). The shared root-level
+        // inventory is computed once, lazily: it walks the whole root and
+        // spends scan budget, so it must not run once per candidate file.
+        const entries = await readdir(rootPath, { withFileTypes: true });
+        let rootLevel: { fileCount: number; executableScripts: string[] } | undefined;
+        for (const entry of entries) {
+            if (!spend()) break;
+            if (!entry.isFile() || entry.isSymbolicLink() || !entry.name.toLowerCase().endsWith(".md")) continue;
+            const entryInfo = await lstat(join(rootPath, entry.name)).catch(() => undefined);
+            if (!entryInfo) continue; // vanished mid-scan
+            if (entryInfo.size > settings.maxSkillBytes) {
+                rejected.push({ dirPath: ".", reason: `root-level file '${entry.name}' exceeds settings.maxSkillBytes` });
+                continue;
+            }
+            const bytes = await readFile(join(rootPath, entry.name));
+            const parsed = parseFrontmatter(bytes.toString("utf8"));
+            if (!parsed.data) continue; // not a skill file; ignored silently, like pi
+            rootLevel ??= await inventory(".");
+            await readSkill(".", entry.name, rootLevel.fileCount, rootLevel.executableScripts);
+        }
+        // Directories containing SKILL.md are skills; group directories are recursed.
+        const walk = async (dirRel: string, depth: number): Promise<void> => {
+            if (depth > MAX_SCAN_DEPTH) {
+                issues.push(`Scan stopped descending below depth ${MAX_SCAN_DEPTH} at ${dirRel || "."}.`);
+                return;
+            }
+            const absolute = join(rootPath, dirRel);
+            const entries = await readdir(absolute, { withFileTypes: true }).catch(() => []);
+            for (const entry of entries) {
+                if (!spend()) return;
+                if (entry.isSymbolicLink()) {
+                    issues.push(`Symlink skipped (fail closed): ${dirRel ? `${dirRel}/` : ""}${entry.name}`);
+                    continue;
+                }
+                if (!entry.isDirectory()) continue;
+                const childRel = dirRel ? `${dirRel}/${entry.name}` : entry.name;
+                const skillPath = join(rootPath, childRel, "SKILL.md");
+                const skillInfo = await lstat(skillPath).catch(() => undefined);
+                if (skillInfo?.isFile()) {
+                    const { fileCount, executableScripts } = await inventory(childRel);
+                    await readSkill(childRel, "SKILL.md", fileCount, executableScripts);
+                } else {
+                    await walk(childRel, depth + 1);
+                }
+            }
+        };
+        await walk("", 0);
+    }
+
+    if (overBudget) throw new Error(`The root contains more than ${settings.maxScanFiles} filesystem entries; refusing to scan further.`);
+    if (skills.length > settings.maxSkills) {
+        throw new Error(`The root contains more than ${settings.maxSkills} skills (found ${skills.length}); adjust settings.maxSkills or split the root.`);
+    }
+    skills.sort((a, b) => a.name.localeCompare(b.name));
+    return { skills, rejected, issues, scannedAt: new Date().toISOString() };
+}
+
+// ─── Copy helpers (import flows) ────────────────────────────────────────────
+
+/** Snapshot a single skill's instruction file without a full root scan:
+ *  used by the TUI's add/edit flows, where the user just authored or
+ *  approved the content by acting through the manager. Pass `file` for
+ *  root-level .md skills so the snapshot keeps the instruction file's
+ *  name instead of defaulting to SKILL.md. */
+export async function snapshotSkillFile(
+    skillFilePath: string,
+    dirPath: string,
+    settings: ManagerSettings,
+    file?: string,
+): Promise<SkillSnapshot> {
+    const info = await lstat(skillFilePath).catch(() => undefined);
+    if (!info) throw new Error(`Skill file not found: ${skillFilePath}`);
+    if (info.isSymbolicLink() || !info.isFile()) throw new Error(`Skill file must be a regular file, not a symbolic link: ${skillFilePath}`);
+    if (info.size > settings.maxSkillBytes) {
+        throw new Error(`Skill file exceeds settings.maxSkillBytes (${settings.maxSkillBytes} bytes): ${skillFilePath}`);
+    }
+    const bytes = await readFile(skillFilePath);
+    const parsed = parseFrontmatter(bytes.toString("utf8"));
+    if (!parsed.data) throw new Error(`Invalid skill file (${skillFilePath}): ${parsed.error}`);
+    const name = parsed.data["name"] ?? "";
+    const description = parsed.data["description"] ?? "";
+    if (!SKILL_NAME_RE.test(name) || !name || name.length > MAX_SKILL_NAME_CHARS) {
+        throw new Error(`Invalid skill name '${name.slice(0, 80) || "(missing)"}' (1-64 chars, lowercase letters, numbers, single hyphens).`);
+    }
+    if (!description.trim() || description.length > MAX_SKILL_DESC_CHARS) {
+        throw new Error(`Skill '${name}' must have a non-empty description of at most ${MAX_SKILL_DESC_CHARS} characters.`);
+    }
+    return {
+        name,
+        description: description.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, " ").slice(0, MAX_SKILL_DESC_CHARS),
+        dirPath,
+        file: file && file !== "SKILL.md" ? file : undefined,
+        contentHash: createHash("sha256").update(bytes).digest("hex"),
+        fileCount: 1,
+        executableScripts: [],
+        hidden: parsed.data["disable-model-invocation"] === "true" ? true : undefined,
+    };
+}
+
+/** Copy a directory tree wholesale (import flows). Symlinks are skipped and
+ *  reported; per-file size and total file-count bounds are enforced. The
+ *  destination must not exist yet. */
+export async function copyTreeInto(
+    source: string,
+    destination: string,
+    settings: ManagerSettings,
+): Promise<{ copied: number; skipped: string[] }> {
+    const info = await lstat(source).catch(() => undefined);
+    if (!info) throw new Error(`The source does not exist: ${source}`);
+    if (info.isSymbolicLink() || !info.isDirectory()) throw new Error(`The source must be a regular directory, not a symbolic link: ${source}`);
+    const destInfo = await lstat(destination).catch(() => undefined);
+    if (destInfo) throw new Error(`The destination already exists: ${destination}`);
+    const skipped: string[] = [];
+    let copied = 0;
+    let budget = settings.maxScanFiles;
+    const walk = async (absolute: string, rel: string): Promise<void> => {
+        if (rel) await mkdir(join(destination, rel), { recursive: true });
+        const entries = await readdir(absolute, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isSymbolicLink()) {
+                skipped.push(`symlink skipped: ${rel ? `${rel}/` : ""}${entry.name}`);
+                continue;
+            }
+            // Every filesystem entry (file or directory) spends budget, the
+            // same accounting a scan uses.
+            if (budget-- <= 0) throw new Error(`The source contains more than ${settings.maxScanFiles} filesystem entries; refusing to copy further.`);
+            const childAbs = join(absolute, entry.name);
+            const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) await walk(childAbs, childRel);
+            else if (entry.isFile()) {
+                const childInfo = await lstat(childAbs);
+                if (childInfo.size > MAX_COPY_FILE_BYTES) {
+                    skipped.push(`file skipped (over ${MAX_COPY_FILE_BYTES} bytes): ${childRel}`);
+                    continue;
+                }
+                await mkdir(dirname(join(destination, childRel)), { recursive: true });
+                await writeFile(join(destination, childRel), await readFile(childAbs), { mode: 0o644 });
+                copied++;
+            }
+        }
+    };
+    await walk(source, "");
+    return { copied, skipped };
+}
+
+/** Render a directory tree for display (the import flow prints it and asks
+ *  which SKILL.md is the skill). Bounded to maxDepth levels and 500 entries. */
+export async function renderDirTree(source: string, maxDepth = 4): Promise<string> {
+    const lines: string[] = [source.endsWith("/") ? source.slice(0, -1) : source];
+    let budget = 500;
+    const walk = async (absolute: string, rel: string, depth: number, prefix: string): Promise<void> => {
+        if (depth >= maxDepth || budget <= 0) return;
+        const entries = await readdir(absolute, { withFileTypes: true }).catch(() => []);
+        const visible = entries.filter((entry) => !entry.isSymbolicLink());
+        for (let index = 0; index < visible.length && budget > 0; index++) {
+            const entry = visible[index]!;
+            budget--;
+            const last = index === visible.length - 1;
+            const connector = last ? "└── " : "├── ";
+            const marker = entry.isFile() && entry.name.toLowerCase() === "skill.md" ? " ◄ SKILL.md" : entry.isFile() && entry.name.toLowerCase().endsWith(".md") ? " (.md)" : "";
+            lines.push(`${prefix}${connector}${entry.name}${marker}`);
+            if (entry.isDirectory()) {
+                await walk(join(absolute, entry.name), rel ? `${rel}/${entry.name}` : entry.name, depth + 1, `${prefix}${last ? "    " : "│   "}`);
+            }
+        }
+        if (budget <= 0) lines.push(`${prefix}… (tree truncated)`);
+    };
+    await walk(source, "", 0, "");
+    return lines.join("\n");
+}
+
+/** The relative path of `target` under `base`, or undefined when it is not
+ *  inside (..-escaping or absolute elsewhere). Used to validate the import
+ *  flow's hand-typed SKILL.md answer. */
+export function relativeInside(base: string, target: string): string | undefined {
+    const rel = relative(base, target);
+    if (!rel || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return undefined;
+    return rel;
+}

package/simple-skills-manager.example.json

@@ -0,0 +1,114 @@
+{
+  // Template for ~/.pi/agent/simple-skills-manager.json — the extension creates
+  // a commented starter automatically on first run; this file is the fully
+  // documented reference. Copy it over the starter if you prefer:
+  //   cp ~/.pi/agent/extensions/simple-skills-manager/simple-skills-manager.example.json \
+  //      ~/.pi/agent/simple-skills-manager.json
+  //
+  // JSONC comments are allowed when you edit by hand; saving from
+  // /skills-manager rewrites the file and strips them. Full field reference:
+  // docs/config.md.
+
+  "version": 1,
+
+  // ── Extension settings (all optional; defaults shown) ────────────────────
+  "settings": {
+    // Per-invocation skill text output cap, in bytes (default 50 KiB).
+    "maxResultBytes": 51200,
+    // Per-invocation skill text output line cap (default 2,000 lines).
+    "maxResultLines": 2000,
+    // Maximum skills one root's approved manifest may hold (default 200).
+    "maxSkills": 200,
+    // Maximum length of registered skill_<root>__<skill> tool names (default 64).
+    "toolNameLimit": 64,
+    // Maximum size of one skill instruction file (default 128 KiB).
+    "maxSkillBytes": 131072,
+    // Maximum filesystem entries one scan may visit (default 4096).
+    "maxScanFiles": 4096
+  },
+
+  // ── The registrar: every library root sits flat here ──────────────────────
+  // Each non-store root needs one "Scan or refresh" pass (in /skills-manager)
+  // to record its approved skill manifest before it can be enabled.
+  "registrar": [
+    // The built-in store — seeded automatically on first run. Skills added
+    // through /skills-manager accumulate here; group skills by nesting their
+    // directories in subdirectories of the store (groups are the first path
+    // segment and display as groups in the tree navigator).
+    {
+      "name": "store",
+      "store": true,
+      "enabled": true,
+      "transport": "skills-dir",
+      "path": "~/.pi/agent/managed-skills",
+      "connection": "lazy",
+      "skills": {
+        "mode": "selected",
+        "include": ["pdf-tools"]
+      },
+
+      // The approved manifest, written by /skills-manager's scans and by the
+      // add/edit flows. Bound to the root identity (name, transport, path)
+      // via a SHA-256 fingerprint, and every skill is bound to the exact
+      // content that was inspected via a SHA-256 contentHash. Change the
+      // path and the manifest is invalidated until you refresh; change a
+      // SKILL.md outside the manager and invocations fail closed until you
+      // refresh. Never write this section by hand.
+      "manifest": {
+        "version": 1,
+        "fingerprint": "sha256-of-root-identity",
+        "scannedAt": "2026-09-13T00:00:00.000Z",
+        "skills": [
+          {
+            "name": "pdf-tools",
+            "description": "Extracts text and tables from PDF files, fills PDF forms, and merges PDFs. Use when working with PDF documents.",
+            "dirPath": "docs/pdf-tools",
+            "contentHash": "sha256-of-the-skill-md-bytes",
+            "fileCount": 5,
+            "executableScripts": ["docs/pdf-tools/scripts/process.sh"],
+            "hidden": false
+          }
+        ]
+      }
+    },
+
+    // A native pi location — auto-detected. Native locations that exist on
+    // disk appear in the registrar automatically on the next load: disabled,
+    // unapproved, flagged "Auto-detected". The entry below shows what one
+    // looks like after its "Scan or refresh" adoption. The manager mirrors
+    // pi's own exposure (red, locked in the tree) instead of pretending to
+    // gate it; in library-only mode (pi --no-skills) the normal gate applies.
+    {
+      "name": "agents-skills",
+      "native": true,
+      "enabled": true,
+      "transport": "skills-dir",
+      "path": "~/.agents/skills",
+      "connection": "lazy",
+      "skills": { "mode": "selected", "include": [] },
+      "manifest": { "version": 1, "fingerprint": "…", "scannedAt": "…", "skills": [] }
+    },
+
+    // An external skills directory — read-only to the manager (browse,
+    // inspect, expose; never edited or deleted). Registering it here gives
+    // its skills the drift-checked /skill:<name> command and tool surfaces.
+    {
+      "name": "claude-import",
+      "enabled": false,
+      "transport": "skills-dir",
+      "path": "~/.claude/skills",
+      "connection": "lazy",
+      "skills": { "mode": "selected", "include": [] }
+    },
+
+    // A single skill (one directory with one SKILL.md).
+    {
+      "name": "one-off",
+      "enabled": false,
+      "transport": "single-skill",
+      "path": "~/skills/their-skill",
+      "connection": "lazy",
+      "skills": { "mode": "selected", "include": [] }
+    }
+  ]
+}

package/tests/fixtures/bad/malformed/SKILL.md

@@ -0,0 +1,5 @@
+---
+name: malformed-skill
+---
+
+Missing description; must be rejected.

package/tests/fixtures/bad/unparseable/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: block-scalar
+description: |
+  A multi-line block value that the minimal parser must reject.
+---
+
+Body.

package/tests/fixtures/single-skill/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: solo-skill
+description: A single-skill fixture root with one SKILL.md and a reference file.
+---
+
+# Solo skill
+
+See references/notes.md.

package/tests/fixtures/single-skill/references/notes.md

@@ -0,0 +1 @@
+Reference notes for solo-skill.

package/tests/fixtures/skills-dir/dupe-a/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: dupe
+description: First duplicate-named fixture skill. The first occurrence wins.
+---
+
+First.

package/tests/fixtures/skills-dir/dupe-b/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: dupe
+description: Second duplicate-named fixture skill. This one must be rejected.
+---
+
+Second.

package/tests/fixtures/skills-dir/grouped/doc/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: doc-skill
+description: A fixture skill nested in a group directory. Use when testing group display.
+---
+
+# Doc skill
+
+Grouped under "grouped".

package/tests/fixtures/skills-dir/grouped/scripted/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: scripted-skill
+description: A fixture skill that ships an executable script. Use when testing script flagging.
+---
+
+# Scripted skill
+
+Run ./scripts/run.sh to do the thing.

package/tests/fixtures/skills-dir/grouped/scripted/scripts/run.sh

@@ -0,0 +1,2 @@
+#!/bin/sh
+echo "fixture script"

package/tests/fixtures/skills-dir/hidden/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: hidden-skill
+description: A fixture skill hidden from the model via disable-model-invocation.
+disable-model-invocation: true
+---
+
+# Hidden skill
+
+Command-only.

package/tests/fixtures/skills-dir/plain/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: plain-skill
+description: A plain fixture skill with no extras. Use when testing skill scanning.
+---
+
+# Plain skill
+
+Follow these instructions when the plain-skill tool is invoked.