pi-session-mcp 0.7.1 → 0.8.0

package/.pi-session-mcp-cli/config.js

@@ -4,16 +4,20 @@ import { dirname, resolve } from "node:path";
 import { z } from "zod";
 import { MAX_PROFILE_EXTENSIONS, parseExtensionSpec } from "./extension-spec.js";
 import { isMcpServers, snapshotMcpServers } from "./mcp-config.js";
+import { builtinSkillName, isSkillCatalogPath, MAX_PROFILE_SKILLS, MAX_SKILL_CATALOG_ENTRIES } from "./skill-catalog.js";
 import { ALIAS_PATTERN, ImmutableMap, } from "./execution-profile.js";
+import { builtinSkillPath, skillOverrideDirectory } from "./skill-library.js";
 const alias = z.string().regex(ALIAS_PATTERN);
 const permissionProfile = z.enum(["read-only", "coding"]);
 const thinkingLevel = z.enum(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
 const extensionSpec = z.string().refine((value) => parseExtensionSpec(value) !== undefined);
+const skillCatalogPath = z.string().refine(isSkillCatalogPath);
 const profileSchema = z.object({
     default: z.boolean(), permissionProfile, provider: z.string().trim().min(1).max(256),
     model: z.string().trim().min(1).max(256), thinkingLevel,
     mcpServers: z.custom((value) => isMcpServers(value)).optional(),
     extensions: z.array(extensionSpec).max(MAX_PROFILE_EXTENSIONS).optional(),
+    skills: z.array(alias).max(MAX_PROFILE_SKILLS).optional(),
 }).strict().superRefine((profile, context) => {
     if (profile.mcpServers !== undefined && !isMcpServers(profile.mcpServers, profile.permissionProfile)) {
         context.addIssue({ code: "custom", path: ["mcpServers"], message: "MCP tool grants do not match the permission profile" });
@@ -24,6 +28,9 @@ const profileSchema = z.object({
             context.addIssue({ code: "custom", path: ["extensions"], message: "An extension package may appear only once per profile" });
         }
     }
+    if (profile.skills !== undefined && new Set(profile.skills).size !== profile.skills.length) {
+        context.addIssue({ code: "custom", path: ["skills"], message: "A skill alias may appear only once per profile" });
+    }
 });
 const CONFIG_ERROR_MESSAGES = {
     config_path_required: "Configuration path is required",
@@ -40,6 +47,7 @@ export class ConfigError extends Error {
 }
 export const configSchema = z.object({
     workspaces: z.record(alias, z.string().min(1)),
+    skillCatalog: z.record(alias, skillCatalogPath).refine((catalog) => Object.keys(catalog).length <= MAX_SKILL_CATALOG_ENTRIES).optional(),
     executionProfiles: z.record(alias, profileSchema).superRefine((profiles, context) => {
         const entries = Object.entries(profiles);
         if (entries.length === 0)
@@ -50,13 +58,39 @@ export const configSchema = z.object({
         if (defaults.length === 1 && defaults[0][1].permissionProfile !== "read-only")
             context.addIssue({ code: "custom", message: "The default execution profile must be read-only" });
     }),
-}).strict();
+}).strict().superRefine((config, context) => {
+    // A profile may select only cataloged skills; there is no implicit or default skill.
+    const catalog = config.skillCatalog ?? {};
+    for (const [profileAlias, profile] of Object.entries(config.executionProfiles)) {
+        if ((profile.skills ?? []).some((skill) => !Object.hasOwn(catalog, skill))) {
+            context.addIssue({ code: "custom", path: ["executionProfiles", profileAlias, "skills"], message: "A selected skill must be a skillCatalog alias" });
+        }
+    }
+});
 /** The only supported reload behavior: a running controller keeps the snapshot it loaded at startup. */
 export const RELOAD_POLICY = "restart-required";
 export const CONFIGURATION_FINGERPRINT_PATTERN = /^sha256:[0-9a-f]{64}$/;
 function configurationFingerprint(bytes) {
     return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
 }
+/**
+ * Resolves a profile's selection against the catalog. Catalog paths resolve like workspaces,
+ * against the configuration file's directory. Two selected aliases on the same path would
+ * load one skill twice under different public names, so they invalidate the configuration.
+ * A `builtin:<name>` value resolves to the library skill: the operator's override, else the shipped one.
+ */
+function resolveSkillSelection(selected, catalog, base, overrideDirectory) {
+    if (selected === undefined || selected.length === 0)
+        return undefined;
+    const resolveEntry = (value) => {
+        const builtin = builtinSkillName(value);
+        return builtin === undefined ? resolve(base, value) : builtinSkillPath(builtin, { overrideDirectory });
+    };
+    const skills = selected.map((skill) => Object.freeze({ alias: skill, path: resolveEntry(catalog[skill]) }));
+    if (new Set(skills.map((skill) => skill.path)).size !== skills.length)
+        throw new ConfigError("invalid_execution_profile_config");
+    return Object.freeze(skills);
+}
 /**
  * The configuration path comes only from the caller or from `PI_SESSION_MCP_CONFIG`.
  * There is no default file: a server's working directory is the client's project,
@@ -85,14 +119,20 @@ export async function loadConfig(path = process.env.PI_SESSION_MCP_CONFIG) {
         throw error;
     }
     const base = dirname(absoluteConfig);
+    const overrideDirectory = skillOverrideDirectory(absoluteConfig);
     const workspaces = new ImmutableMap(Object.entries(parsed.workspaces).map(([key, value]) => [key, resolve(base, value)]));
-    const executionProfiles = new ImmutableMap(Object.entries(parsed.executionProfiles).map(([key, { mcpServers, extensions, ...value }]) => [key, Object.freeze({
-            alias: key, ...value,
-            ...(mcpServers === undefined ? {} : { mcpServers: snapshotMcpServers(mcpServers) }),
-            ...(extensions === undefined ? {} : { extensions: Object.freeze(extensions.map((spec) => parseExtensionSpec(spec))) }),
-        })]));
+    const catalog = parsed.skillCatalog ?? {};
+    const executionProfiles = new ImmutableMap(Object.entries(parsed.executionProfiles).map(([key, { mcpServers, extensions, skills, ...value }]) => {
+        const selection = resolveSkillSelection(skills, catalog, base, overrideDirectory);
+        return [key, Object.freeze({
+                alias: key, ...value,
+                ...(mcpServers === undefined ? {} : { mcpServers: snapshotMcpServers(mcpServers) }),
+                ...(extensions === undefined ? {} : { extensions: Object.freeze(extensions.map((spec) => parseExtensionSpec(spec))) }),
+                ...(selection === undefined ? {} : { skills: selection }),
+            })];
+    }));
     const defaultEntry = [...executionProfiles].find(([, profile]) => profile.default);
     if (!defaultEntry)
         throw new Error("Execution profile configuration is invalid");
-    return { workspaces, executionProfiles, defaultExecutionProfile: defaultEntry[0], configuration };
+    return { workspaces, executionProfiles, defaultExecutionProfile: defaultEntry[0], configuration, skillOverrideDirectory: overrideDirectory };
 }

package/.pi-session-mcp-cli/doctor.js

@@ -1,11 +1,14 @@
-import { access, readFile, readdir, stat } from "node:fs/promises";
+import { access, readFile, readdir, realpath, stat } from "node:fs/promises";
 import { constants } from "node:fs";
 import { join } from "node:path";
 import { loadConfig } from "./config.js";
 import { PiExtensionError } from "./extension-spec.js";
 import { readPackageMetadata } from "./package-metadata.js";
+import { MAX_SKILL_FILE_BYTES } from "./skill-catalog.js";
+import { readSkillBases, SkillBasesError } from "./skill-customize.js";
+import { readSkillTree, shippedSkillsDirectory } from "./skill-library.js";
 const defaultFileSystem = { readFile, stat, access };
-const CHECK_ORDER = ["node_version_unsupported", "package_metadata_unreadable", "build_missing", "build_stale", "version_mismatch", "config_missing", "config_unreadable", "config_invalid", "workspace_missing", "workspace_not_directory", "workspace_unreadable", "workspace_not_writable", "extension_missing", "extension_version_mismatch"];
+const CHECK_ORDER = ["node_version_unsupported", "package_metadata_unreadable", "build_missing", "build_stale", "version_mismatch", "config_missing", "config_unreadable", "config_invalid", "workspace_missing", "workspace_not_directory", "workspace_unreadable", "workspace_not_writable", "extension_missing", "extension_version_mismatch", "skill_missing", "skill_unreadable", "skill_duplicate", "skill_override_outdated"];
 function failure(id, subject, remediation) { return Object.freeze({ id, severity: "error", subject, remediation }); }
 function warning(id, subject, remediation) { return Object.freeze({ id, severity: "warning", subject, remediation }); }
 function ok(id, subject) { return Object.freeze({ id, severity: "ok", subject }); }
@@ -62,6 +65,37 @@ async function productionBuildInputMtimes(root) {
     }
     return mtimes;
 }
+/**
+ * Compares the shipped skills with the fingerprints recorded when the operator copied them.
+ * Reads only the bases file and the shipped files; nothing is executed or changed.
+ */
+async function skillOverrideChecks(overrideDirectory, shippedDirectory) {
+    if (overrideDirectory === undefined)
+        return [];
+    let bases;
+    try {
+        bases = await readSkillBases(overrideDirectory);
+    }
+    catch (error) {
+        if (error instanceof SkillBasesError)
+            return [warning("skill_override_outdated", "skill:bases", "repair or remove the skill bases file")];
+        throw error;
+    }
+    const checks = [];
+    for (const [name, base] of Object.entries(bases).sort(([a], [b]) => a.localeCompare(b))) {
+        let fingerprint;
+        try {
+            fingerprint = (await readSkillTree(join(shippedDirectory, name))).fingerprint;
+        }
+        catch {
+            continue;
+        }
+        checks.push(fingerprint === base
+            ? ok("skill_override_outdated", `skill:${name}`)
+            : warning("skill_override_outdated", `skill:${name}`, `review the changed shipped skill, then run pi-session-mcp-setup --apply --customize-skill ${name}`));
+    }
+    return checks;
+}
 export async function runDoctor(dependencies = {}) {
     const fs = dependencies.fileSystem ?? defaultFileSystem;
     const root = dependencies.packageRoot ?? process.cwd();
@@ -195,6 +229,38 @@ export async function runDoctor(dependencies = {}) {
             }
         }
     }
+    if (config) {
+        for (const [alias, profile] of [...config.executionProfiles].sort(([a], [b]) => a.localeCompare(b))) {
+            const canonical = new Set();
+            for (const skill of profile.skills ?? []) {
+                const subject = `${alias}:${skill.alias}`;
+                let real;
+                try {
+                    const info = await fs.stat(skill.path);
+                    if (!info.isFile() || (info.size ?? 0) > MAX_SKILL_FILE_BYTES)
+                        throw new Error("unusable skill file");
+                    await fs.access(skill.path, constants.R_OK);
+                    real = await (fs.realpath ?? realpath)(skill.path);
+                }
+                catch (error) {
+                    if (isMissing(error))
+                        checks.push(failure("skill_missing", subject, "create the skill file or fix its skillCatalog entry"));
+                    else
+                        checks.push(ok("skill_missing", subject), failure("skill_unreadable", subject, "point the skillCatalog entry to a readable SKILL.md within the size limit"));
+                    continue;
+                }
+                checks.push(ok("skill_missing", subject), ok("skill_unreadable", subject));
+                if (canonical.has(real))
+                    checks.push(failure("skill_duplicate", subject, "select each skill file only once per profile"));
+                else {
+                    canonical.add(real);
+                    checks.push(ok("skill_duplicate", subject));
+                }
+            }
+        }
+    }
+    if (config)
+        checks.push(...await skillOverrideChecks(config.skillOverrideDirectory, shippedSkillsDirectory(dependencies.packageRoot)));
     const rank = new Map(CHECK_ORDER.map((id, index) => [id, index]));
     checks.sort((a, b) => (rank.get(a.id) ?? 999) - (rank.get(b.id) ?? 999) || a.subject.localeCompare(b.subject));
     const hasError = checks.some((check) => check.severity === "error");

package/.pi-session-mcp-cli/execution-profile.js

@@ -9,6 +9,7 @@ export function toResolvedExecutionProfile(profile) {
         thinkingLevel: profile.thinkingLevel,
         ...(profile.mcpServers === undefined ? {} : { mcpServers: snapshotMcpServers(profile.mcpServers) }),
         ...(profile.extensions === undefined ? {} : { extensions: profile.extensions }),
+        ...(profile.skills === undefined ? {} : { skills: profile.skills }),
     });
 }
 /** A small read-only map implementation which has no mutating methods at runtime. */

package/.pi-session-mcp-cli/setup-result.js

@@ -0,0 +1,8 @@
+export function result(operation, findings, status = findings.some((finding) => finding.status === "failed" || finding.status === "divergent" || finding.status === "unsupported") ? "failed" : "ok", exitCode = status === "failed" ? 1 : 0) {
+    const normalized = findings.map((finding) => Object.freeze({
+        target: Object.freeze({ ...finding.target }),
+        status: finding.status,
+        code: /^[a-z][a-z0-9_]{0,63}$/.test(finding.code) ? finding.code : "operation_failed",
+    }));
+    return Object.freeze({ schemaVersion: 1, operation, status, findings: Object.freeze(normalized), exitCode });
+}

package/.pi-session-mcp-cli/skill-catalog.js

@@ -0,0 +1,35 @@
+import { BUILTIN_SKILL_PREFIX, SKILL_NAME_PATTERN } from "./skill-library.js";
+export const MAX_SKILL_CATALOG_ENTRIES = 64;
+export const MAX_PROFILE_SKILLS = 16;
+export const MAX_SKILL_PATH_LENGTH = 4096;
+/** Upper bound for one selected `SKILL.md`, checked before the Pi SDK reads it. */
+export const MAX_SKILL_FILE_BYTES = 256 * 1024;
+export const SKILL_FILE_NAME = "SKILL.md";
+/** `npm:`, `git+ssh:`, `https:`, `file:` and any other scheme-prefixed source. */
+const SCHEME_PREFIX = /^[A-Za-z][A-Za-z0-9+.-]*:/;
+const GLOB_CHARACTERS = /[*?[\]{}]/;
+/** The library skill name of a `builtin:<name>` catalog value; undefined for every other value. */
+export function builtinSkillName(value) {
+    if (!value.startsWith(BUILTIN_SKILL_PREFIX))
+        return undefined;
+    const name = value.slice(BUILTIN_SKILL_PREFIX.length);
+    return SKILL_NAME_PATTERN.test(name) ? name : undefined;
+}
+/**
+ * Whether a configured catalog value names exactly one local `SKILL.md`: its last path segment
+ * is `SKILL.md`, and it is no URL or other scheme-prefixed source, no `~` home shorthand, no
+ * glob and no Windows-style path. So it can never stand for a directory, a pattern or a
+ * remote source. Relative values are resolved later against the configuration file's directory.
+ * The one scheme-prefixed form accepted is `builtin:<name>`, which names a library skill.
+ */
+export function isSkillCatalogPath(value) {
+    if (value.length === 0 || value.length > MAX_SKILL_PATH_LENGTH)
+        return false;
+    if (value.includes("\0") || value.includes("\\") || value.startsWith("~"))
+        return false;
+    if (builtinSkillName(value) !== undefined)
+        return true;
+    if (SCHEME_PREFIX.test(value) || GLOB_CHARACTERS.test(value))
+        return false;
+    return value.split("/").at(-1) === SKILL_FILE_NAME;
+}

package/.pi-session-mcp-cli/skill-customize.js

@@ -0,0 +1,183 @@
+import { randomBytes } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, readFile, rename, rm, unlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { result } from "./setup-result.js";
+import { readSkillTree, shippedSkillsDirectory, SKILL_NAME_PATTERN, SkillTreeError, skillOverrideDirectory } from "./skill-library.js";
+/**
+ * `--customize-skill <name>`: copies a shipped skill into the operator's override directory as a
+ * starting point, and records the shipped fingerprint it was based on. The operator's files are
+ * never overwritten or edited; a changed original is only reported and acknowledged by moving
+ * the recorded base. Reports carry the skill name and a code, never a path or file content.
+ */
+export const SKILL_BASES_FILE = ".pi-session-mcp-bases.json";
+export const MAX_SKILL_BASES_BYTES = 64 * 1024;
+const FINGERPRINT_PATTERN = /^[0-9a-f]{64}$/;
+export class SkillBasesError extends Error {
+    constructor() {
+        super("Skill bases file is not usable");
+        this.name = "SkillBasesError";
+    }
+}
+/** Strictly validated contents of the bases file; an absent file or override directory is an empty record. */
+export async function readSkillBases(overrideDirectory) {
+    const path = join(overrideDirectory, SKILL_BASES_FILE);
+    let text;
+    try {
+        const info = await lstat(path);
+        if (!info.isFile() || info.size > MAX_SKILL_BASES_BYTES)
+            throw new SkillBasesError();
+        const bytes = await readFile(path);
+        if (bytes.length > MAX_SKILL_BASES_BYTES)
+            throw new SkillBasesError();
+        text = bytes.toString("utf8");
+    }
+    catch (error) {
+        if (error instanceof SkillBasesError)
+            throw error;
+        if (typeof error === "object" && error !== null && error.code === "ENOENT")
+            return Object.freeze({});
+        throw new SkillBasesError();
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new SkillBasesError();
+    }
+    if (!isPlainObject(parsed) || Object.keys(parsed).sort().join() !== "bases,schemaVersion" || parsed.schemaVersion !== 1)
+        throw new SkillBasesError();
+    const bases = parsed.bases;
+    if (!isPlainObject(bases))
+        throw new SkillBasesError();
+    const entries = Object.entries(bases);
+    if (!entries.every(([name, value]) => SKILL_NAME_PATTERN.test(name) && typeof value === "string" && FINGERPRINT_PATTERN.test(value)))
+        throw new SkillBasesError();
+    return Object.freeze(Object.fromEntries(entries));
+}
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/** Atomic replacement: a private temporary file in the same directory, then a rename. */
+async function writeSkillBases(overrideDirectory, bases) {
+    const sorted = Object.fromEntries(Object.entries(bases).sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0)));
+    const content = Buffer.from(`${JSON.stringify({ schemaVersion: 1, bases: sorted })}\n`, "utf8");
+    if (content.length > MAX_SKILL_BASES_BYTES)
+        throw new SkillBasesError();
+    const temporary = join(overrideDirectory, `.${SKILL_BASES_FILE.slice(1)}.${randomBytes(6).toString("hex")}.tmp`);
+    const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+    try {
+        try {
+            await handle.writeFile(content);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(temporary, join(overrideDirectory, SKILL_BASES_FILE));
+    }
+    catch (error) {
+        await unlink(temporary).catch(() => undefined);
+        throw error;
+    }
+}
+function isMissing(error) {
+    return typeof error === "object" && error !== null && error.code === "ENOENT";
+}
+function report(request, status, code) {
+    // The name is echoed only when it is a valid skill name, so arbitrary input never reaches a report.
+    const alias = SKILL_NAME_PATTERN.test(request.name) ? request.name : "invalid";
+    const target = { client: "skills", scope: "override", alias };
+    const finding = { target, status, code };
+    // A planned change reports `planned` overall, like a registration dry-run.
+    return result(request.apply ? "apply" : "dry-run", [finding], status === "planned" ? "planned" : undefined);
+}
+export async function customizeSkill(request) {
+    const done = (status, code) => report(request, status, code);
+    if (!SKILL_NAME_PATTERN.test(request.name))
+        return done("failed", "skill_not_shipped");
+    try {
+        const shippedDirectory = join(shippedSkillsDirectory(request.packageRoot), request.name);
+        let shipped;
+        try {
+            shipped = await readSkillTree(shippedDirectory);
+        }
+        catch (error) {
+            if (error instanceof SkillTreeError && error.code === "skill_tree_missing")
+                return done("failed", "skill_not_shipped");
+            return done("failed", "skill_customize_failed");
+        }
+        const overrideDirectory = skillOverrideDirectory(request.configPath);
+        let bases;
+        try {
+            bases = await readSkillBases(overrideDirectory);
+        }
+        catch (error) {
+            if (error instanceof SkillBasesError)
+                return done("failed", "skill_bases_corrupt");
+            throw error;
+        }
+        const overridePath = join(overrideDirectory, request.name);
+        let exists = true;
+        try {
+            const info = await lstat(overridePath);
+            if (!info.isDirectory())
+                return done("failed", "skill_override_invalid");
+        }
+        catch (error) {
+            if (!isMissing(error))
+                throw error;
+            exists = false;
+        }
+        if (!exists) {
+            if (!request.apply)
+                return done("planned", "skill_customize_planned");
+            await copyShippedSkill(shipped.files, overrideDirectory, overridePath, request.name);
+            await writeSkillBases(overrideDirectory, { ...bases, [request.name]: shipped.fingerprint });
+            return done("ok", "skill_customized");
+        }
+        try {
+            await readSkillTree(overridePath);
+        }
+        catch (error) {
+            if (error instanceof SkillTreeError)
+                return done("failed", "skill_override_invalid");
+            throw error;
+        }
+        if (bases[request.name] === shipped.fingerprint)
+            return done("unchanged", "skill_override_current");
+        if (!request.apply)
+            return done("planned", "skill_override_outdated");
+        // Only the recorded base moves: it acknowledges that the operator reviewed the changed original.
+        await writeSkillBases(overrideDirectory, { ...bases, [request.name]: shipped.fingerprint });
+        return done("ok", "skill_base_updated");
+    }
+    catch {
+        return done("failed", "skill_customize_failed");
+    }
+}
+async function copyShippedSkill(files, overrideDirectory, overridePath, name) {
+    await mkdir(overrideDirectory, { recursive: true, mode: 0o700 });
+    const temporary = join(overrideDirectory, `.${name}.${randomBytes(6).toString("hex")}.tmp`);
+    try {
+        await mkdir(temporary, { mode: 0o755 });
+        for (const file of files) {
+            const destination = join(temporary, ...file.path.split("/"));
+            await mkdir(dirname(destination), { recursive: true });
+            await writeFile(destination, file.bytes, { flag: "wx", mode: 0o644 });
+        }
+        // The override must not appear while the copy runs, and an operator's directory is never replaced.
+        if (await lstat(overridePath).then(() => true, (error) => { if (isMissing(error))
+            return false; throw error; }))
+            throw new Error("override appeared");
+        await rename(temporary, overridePath);
+    }
+    catch (error) {
+        await rm(temporary, { recursive: true, force: true }).catch(() => undefined);
+        throw error;
+    }
+}

package/.pi-session-mcp-cli/skill-library.js

@@ -0,0 +1,120 @@
+import { createHash } from "node:crypto";
+import { statSync } from "node:fs";
+import { lstat, readdir, readFile, realpath } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * The skill library: skills shipped in the package's `skills/` directory, and the operator's
+ * override directory `skills/` next to the configuration file. An override with the same name
+ * replaces the shipped skill; a new name adds a skill. Nothing else is searched.
+ */
+/** Agent Skills name rule: lowercase letters and digits in hyphen-separated groups, 1 to 64 characters. */
+export const SKILL_NAME_PATTERN = /^(?=.{1,64}$)[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** A `skillCatalog` value `builtin:<name>` names a library skill instead of a path. */
+export const BUILTIN_SKILL_PREFIX = "builtin:";
+/** Skills for the controlling agent, which setup installs into Claude Code and Codex. */
+export const CONTROLLER_SKILLS = Object.freeze(["pi-session-orchestration"]);
+export const MAX_SKILL_TREE_FILES = 32;
+export const MAX_SKILL_TREE_BYTES = 1024 * 1024;
+const MAX_SKILL_TREE_DEPTH = 8;
+/** `dist/`, `.pi-session-mcp-cli/` and `src/` all sit one level below the package root. */
+export const PACKAGE_ROOT = fileURLToPath(new URL("..", import.meta.url));
+export function shippedSkillsDirectory(packageRoot = PACKAGE_ROOT) {
+    return join(packageRoot, "skills");
+}
+/** The override directory belongs to the configuration, never to a workspace or the shell's directory. */
+export function skillOverrideDirectory(configPath) {
+    return join(dirname(resolve(configPath)), "skills");
+}
+function isRegularFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** The override wins over the shipped skill of the same name; undefined when neither exists. */
+export function resolveLibrarySkill(name, roots) {
+    if (!SKILL_NAME_PATTERN.test(name))
+        return undefined;
+    const override = join(roots.overrideDirectory, name);
+    if (isRegularFile(join(override, "SKILL.md")))
+        return Object.freeze({ name, source: "override", directory: override });
+    const shipped = join(shippedSkillsDirectory(roots.packageRoot), name);
+    if (isRegularFile(join(shipped, "SKILL.md")))
+        return Object.freeze({ name, source: "shipped", directory: shipped });
+    return undefined;
+}
+/** The `SKILL.md` a `builtin:<name>` catalog value stands for; a missing skill keeps the shipped location. */
+export function builtinSkillPath(name, roots) {
+    const skill = resolveLibrarySkill(name, roots);
+    return join(skill?.directory ?? join(shippedSkillsDirectory(roots.packageRoot), name), "SKILL.md");
+}
+export class SkillTreeError extends Error {
+    code;
+    constructor(code) {
+        super("Skill directory is not usable");
+        this.code = code;
+        this.name = "SkillTreeError";
+    }
+}
+/**
+ * Reads the regular files below a skill directory in a stable order. Entries whose name starts
+ * with `.` are skipped or rejected (see options). A symbolic link or special file inside the
+ * tree, a missing `SKILL.md`, or more than the file and byte limits fail, so the tree can be
+ * copied and compared exactly.
+ */
+export async function readSkillTree(directory, options = {}) {
+    let root;
+    try {
+        root = await realpath(directory);
+    }
+    catch {
+        throw new SkillTreeError("skill_tree_missing");
+    }
+    const files = [];
+    let bytes = 0;
+    const visit = async (current, prefix, depth) => {
+        if (depth > MAX_SKILL_TREE_DEPTH)
+            throw new SkillTreeError("skill_tree_invalid");
+        let entries;
+        try {
+            entries = await readdir(current, { withFileTypes: true });
+        }
+        catch {
+            throw new SkillTreeError("skill_tree_invalid");
+        }
+        for (const entry of entries.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0))) {
+            if (entry.name.startsWith(".")) {
+                if (options.hidden === "reject")
+                    throw new SkillTreeError("skill_tree_invalid");
+                continue;
+            }
+            const path = join(current, entry.name);
+            const relativePath = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+            const info = await lstat(path);
+            if (info.isDirectory()) {
+                await visit(path, relativePath, depth + 1);
+                continue;
+            }
+            if (!info.isFile())
+                throw new SkillTreeError("skill_tree_invalid");
+            if (files.length + 1 > MAX_SKILL_TREE_FILES || bytes + info.size > MAX_SKILL_TREE_BYTES)
+                throw new SkillTreeError("skill_tree_too_large");
+            const content = await readFile(path);
+            // Counted as read, so a file that grew after lstat cannot pass the limit.
+            bytes += content.length;
+            if (bytes > MAX_SKILL_TREE_BYTES)
+                throw new SkillTreeError("skill_tree_too_large");
+            files.push(Object.freeze({ path: relativePath, bytes: content }));
+        }
+    };
+    await visit(root, "", 0);
+    if (!files.some((file) => file.path === "SKILL.md"))
+        throw new SkillTreeError("skill_tree_missing");
+    const hash = createHash("sha256");
+    for (const file of files)
+        hash.update(file.path).update("\0").update(file.bytes).update("\0");
+    return Object.freeze({ files: Object.freeze(files), fingerprint: hash.digest("hex") });
+}

package/CHANGELOG.md

@@ -2,6 +2,91 @@
 
 ## Unreleased
 
+## 0.8.0 — 2026-10-12
+
+This is a minor release because the public contract changes, as ADR 0003
+requires: the `skills` field of each execution profile in
+`pi_capabilities_get` and the new error code `skill_load_failed`.
+
+- Execution profiles can select Pi skills. An optional top-level
+  `skillCatalog` maps a skill alias to the path of one `SKILL.md` file (or to
+  `builtin:<name>`, see below), and an
+  optional `skills` list in a profile selects catalog aliases. MCP callers still
+  choose only workspace and profile aliases; no tool takes a skill. A session
+  loads exactly the selected skills and validates them at start; a missing,
+  unreadable, oversized or invalid skill, a duplicate Pi skill name, two aliases
+  on one file, or an explicit-only skill (`disable-model-invocation: true`)
+  fails the start with the new error `skill_load_failed`. Every execution
+  profile in `pi_capabilities_get` gains `skills`, the selected catalog aliases
+  (`[]` when none). Doctor gains `skill_missing`, `skill_unreadable` and
+  `skill_duplicate`. Skill file contents are not snapshotted; do not change
+  them while sessions that use them are active. See [Pi
+  skills](docs/skills.md) and [ADR 0007](docs/adr/0007-profile-skill-selection.md).
+  Issue #46.
+- Compatibility change: with Pi SDK 1.1.0, skills that an allowlisted
+  extension package bundles reached a session although `noSkills` was set. An
+  extension allowlist alone now makes none of its skills available. A profile
+  that relied on them needs a catalog entry with the absolute path of the
+  package's `SKILL.md` and a `skills` selection; see the migration section of
+  [Pi skills](docs/skills.md).
+- Prompt templates and themes that extension packages ship are now closed
+  through the SDK's public overrides as well. They were already never expanded
+  for MCP prompts.
+- The package ships three skills under `skills/`: `pi-session-orchestration`
+  for the controlling Claude Code or Codex agent, and `pi-session-implementation`
+  and `pi-session-review` for Pi workers. The example configuration registers
+  the two worker skills with `builtin:` references, so a copied example needs
+  no path edits for skills.
+- Skill library and `builtin:`. A `skillCatalog` value `builtin:<name>` names a
+  skill of the library: the operator's override
+  `<configuration directory>/skills/<name>/SKILL.md` if it exists, else the
+  skill shipped in the package. Resolution happens when the configuration
+  loads, so adding or removing an override needs a restart. A name that matches
+  neither keeps the shipped location, so Doctor reports `skill_missing` and a
+  session start fails with `skill_load_failed`. A malformed `builtin:` name makes
+  the configuration invalid.
+- `pi-session-mcp-setup --customize-skill <name>` (a dry-run; `--apply` writes)
+  copies a shipped skill into the override directory as a starting point and
+  records the shipped fingerprint in `.pi-session-mcp-bases.json`. It never
+  overwrites an existing override. Findings use the target
+  `skills/override/<name>` and the new codes `skill_customize_planned`,
+  `skill_customized`, `skill_override_current`, `skill_override_outdated`,
+  `skill_base_updated`, `skill_not_shipped`, `skill_bases_corrupt`,
+  `skill_override_invalid` and `skill_customize_failed`. After a package
+  update changed a shipped skill, `--apply --customize-skill <name>` moves only
+  the recorded base once you reviewed the change; it never touches your files.
+  A new skill needs no command: create `<override dir>/<name>/SKILL.md` and
+  reference it as `builtin:<name>`.
+- `pi-session-mcp-setup --apply` now also installs the controller skill
+  `pi-session-orchestration` for each target, after the registration, as a real
+  copy of the effective skill (override, else shipped): Codex `~/.agents/skills/`,
+  Claude Code `user` and `local` `~/.claude/skills/` (one shared directory),
+  Claude Code `project` `<project>/.claude/skills/`. The ownership record holds
+  only a content fingerprint. Setup never replaces or deletes a modified copy, a
+  foreign skill of the same name, hidden operator files inside the copy, or a
+  linked or non-directory entry (`skill_divergent`); a link to exactly the
+  effective skill is accepted as the operator's own (`skill_linked`). Inside a
+  project setup never follows a link, and a project copy is bound to its
+  project. A setup result has a second finding per target with the alias
+  `pi-session-orchestration` whenever the skill step runs (not for an apply
+  that the plan refuses or a registration that failed); the new codes are `skill_absent`,
+  `skill_equivalent`, `skill_linked`, `skill_update_planned`, `skill_source_invalid`,
+  `skill_installed`, `skill_already_equivalent`, `skill_updated`,
+  `skill_install_failed`, `skill_verified`, `skill_missing`,
+  `skill_not_equivalent`, `skill_removed`, `skill_kept_shared`,
+  `skill_not_owned` and `skill_divergent`. A divergent skill does not block the
+  registration but makes the overall status `failed`. `--remove` and
+  `--rollback` remove an unmodified copy, and a retry still cleans up a skill
+  that setup owns after the registration is gone. Manual symlinking of the
+  skill is no longer needed.
+- Doctor gains the warning `skill_override_outdated` (subject `skill:<name>`,
+  or `skill:bases` for a corrupt bases file) when a shipped skill changed since
+  the operator copied it.
+- Maintainers get `scripts/multi-session-acceptance.mjs`, a live check in which
+  a real Claude Code or Codex controller drives two concurrent Pi sessions
+  with selected skills, including a targeted abort. It is not part of the npm
+  package; see [acceptance](docs/acceptance.md#multi-session-skill-acceptance).
+
 ## 0.7.1 — 2026-10-11
 
 The public MCP contract is unchanged.