pi-session-mcp 0.7.1 → 0.8.0

package/dist/setup-skills.js

@@ -0,0 +1,353 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, mkdir, open, realpath, rename, rm } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { CONTROLLER_SKILLS, readSkillTree, resolveLibrarySkill, skillOverrideDirectory } from "./skill-library.js";
+/** Whether a fingerprint is setup's own copy: the owned one, or the one a pending update replaces. */
+function ownsFingerprint(record, fingerprint) {
+    return fingerprint === record.fingerprint || (record.phase === "pending" && record.replaces === fingerprint);
+}
+/** Paths remain internal. Ownership identifies a client slot, never its location. */
+export class FileSetupSkillInstaller {
+    roots;
+    constructor(roots) {
+        this.roots = roots;
+    }
+    async run(operation, target, ownership) {
+        const findings = [];
+        for (const name of CONTROLLER_SKILLS)
+            findings.push(await this.skill(operation, target, name, ownership));
+        return findings;
+    }
+    async owns(target, ownership) {
+        // Claude Code user and local share one slot: while the other registration exists, its skill
+        // is not this target's to clean up.
+        if (target.client === "claude-code" && target.scope !== "project"
+            && await ownership.get({ ...target, scope: target.scope === "local" ? "user" : "local" }))
+            return false;
+        for (const name of CONTROLLER_SKILLS)
+            if (await ownership.get((await this.location(target, name)).owned))
+                return true;
+        return false;
+    }
+    /**
+     * The slot path and its ownership key. A project may be untrusted: only its root is
+     * canonicalized, and a link below it (for example `.claude` pointing elsewhere) makes the
+     * slot divergent, so setup never writes outside the project. In the operator's home the
+     * client's skills directory may be the operator's own link, for example into a dotfiles
+     * checkout, so it is followed. The skill entry itself is never followed in either place.
+     * A project slot's ownership is bound to an opaque, path-free identity of the project, so a
+     * remove in another project never touches this project's copy.
+     */
+    async location(target, name) {
+        const client = target.client === "codex" ? ".agents" : ".claude";
+        if (target.scope === "project") {
+            const project = await realpath(this.roots.cwd);
+            const identity = createHash("sha256").update(project).digest("hex").slice(0, 16);
+            return { path: join(project, client, "skills", name), owned: { client: target.client, scope: "project", alias: `skill:${name}@${identity}` } };
+        }
+        return { path: join(await canonicalExisting(join(this.roots.home, client, "skills")), name), owned: { client: target.client, scope: "user", alias: `skill:${name}` } };
+    }
+    library(name) {
+        return resolveLibrarySkill(name, { overrideDirectory: skillOverrideDirectory(this.roots.configPath), packageRoot: this.roots.packageRoot });
+    }
+    async skill(operation, target, name, ownership) {
+        const finding = (code, status) => ({ target: { ...target, alias: name }, code, status });
+        let location;
+        try {
+            location = await this.location(target, name);
+        }
+        catch {
+            return finding(operation === "verify" ? "skill_missing" :
+                operation === "dry-run" ? "skill_source_invalid" :
+                    operation === "apply" ? "skill_install_failed" : "skill_divergent", operation === "remove" || operation === "rollback" ? "divergent" : "failed");
+        }
+        const { path, owned: ownedTarget } = location;
+        const library = this.library(name);
+        // Only a usable library skill can stand behind an accepted link; otherwise verify and apply would disagree.
+        const usable = library ? await readSkillTree(library.directory).then(() => true, () => false) : false;
+        const linkTarget = usable ? await realpath(library.directory).catch(() => undefined) : undefined;
+        if (operation === "remove" || operation === "rollback") {
+            try {
+                const owned = await ownership.get(ownedTarget);
+                if (!owned)
+                    return finding("skill_not_owned", "unchanged");
+                if (target.client === "claude-code" && target.scope !== "project") {
+                    const other = await ownership.get({ ...target, scope: target.scope === "local" ? "user" : "local" });
+                    if (other?.phase === "owned")
+                        return finding("skill_kept_shared", "unchanged");
+                }
+                const current = await inspectSlot(path, linkTarget);
+                if (current.state === "absent") {
+                    healthy(ownership);
+                    await ownership.delete(ownedTarget);
+                    healthy(ownership);
+                    return finding("skill_absent", "ok");
+                }
+                if (current.state === "linked") {
+                    // The operator replaced setup's copy with their own link: the record is stale, the link stays.
+                    healthy(ownership);
+                    await ownership.delete(ownedTarget);
+                    healthy(ownership);
+                    return finding("skill_not_owned", "unchanged");
+                }
+                if (current.state !== "tree" || !ownsFingerprint(owned, current.fingerprint))
+                    return finding("skill_divergent", "divergent");
+                healthy(ownership);
+                if (!await sameSlot(path, current, linkTarget))
+                    return finding("skill_divergent", "divergent");
+                healthy(ownership);
+                await rm(path, { recursive: true });
+                healthy(ownership);
+                await syncDirectory(dirname(path));
+                healthy(ownership);
+                await ownership.delete(ownedTarget);
+                healthy(ownership);
+                return finding("skill_removed", "ok");
+            }
+            catch {
+                return finding("skill_divergent", "divergent");
+            }
+        }
+        if (operation === "verify") {
+            const current = await inspectSlot(path, linkTarget);
+            if (current.state === "absent")
+                return finding("skill_missing", "failed");
+            if (current.state === "linked")
+                return finding("skill_verified", "ok");
+            try {
+                if (!library)
+                    throw new Error("skill_source_invalid");
+                const desired = await readSkillTree(library.directory);
+                return current.state === "tree" && current.fingerprint === desired.fingerprint
+                    ? finding("skill_verified", "ok") : finding("skill_not_equivalent", "failed");
+            }
+            catch {
+                return finding("skill_not_equivalent", "failed");
+            }
+        }
+        let desired;
+        try {
+            if (!library)
+                throw new Error("skill_source_invalid");
+            desired = await readSkillTree(library.directory);
+        }
+        catch {
+            return finding("skill_source_invalid", "failed");
+        }
+        try {
+            const current = await inspectSlot(path, linkTarget);
+            const owned = await ownership.get(ownedTarget);
+            if (current.state === "linked") {
+                if (operation === "apply" && owned) {
+                    healthy(ownership);
+                    await ownership.delete(ownedTarget);
+                    healthy(ownership);
+                }
+                return finding("skill_linked", "unchanged");
+            }
+            if (current.state === "divergent")
+                return finding("skill_divergent", "divergent");
+            // A copy setup did not write, or its own copy modified since, is never replaced.
+            if (current.state === "tree" && (!owned || !ownsFingerprint(owned, current.fingerprint))) {
+                if (!owned && current.fingerprint === desired.fingerprint)
+                    return finding(operation === "apply" ? "skill_already_equivalent" : "skill_equivalent", "unchanged");
+                return finding("skill_divergent", "divergent");
+            }
+            if (current.state === "tree" && current.fingerprint === desired.fingerprint) {
+                if (operation === "apply" && owned?.phase === "pending") {
+                    healthy(ownership);
+                    await ownership.put(ownedRecord(owned, desired.fingerprint));
+                    healthy(ownership);
+                }
+                return finding(operation === "apply" ? "skill_already_equivalent" : "skill_equivalent", "unchanged");
+            }
+            if (operation === "dry-run")
+                return current.state === "absent" ? finding("skill_absent", "absent") : finding("skill_update_planned", "planned");
+            // The pending record keeps the replaced fingerprint, so an interrupted update leaves a copy
+            // that setup can still finish or remove.
+            const pending = {
+                target: ownedTarget, fingerprint: desired.fingerprint, previous: "absent", phase: "pending", transactionId: randomUUID(),
+                ...(current.state === "tree" ? { replaces: current.fingerprint } : {}),
+            };
+            healthy(ownership);
+            await ownership.put(pending);
+            healthy(ownership);
+            await this.replace(path, name, desired, current, ownership);
+            healthy(ownership);
+            const after = await inspectSlot(path);
+            if (after.state !== "tree" || after.fingerprint !== desired.fingerprint)
+                throw new Error("skill_post_install_mismatch");
+            healthy(ownership);
+            await ownership.put(ownedRecord(pending, desired.fingerprint));
+            healthy(ownership);
+            return finding(current.state === "absent" ? "skill_installed" : "skill_updated", "ok");
+        }
+        catch {
+            return finding(operation === "apply" ? "skill_install_failed" : "skill_source_invalid", "failed");
+        }
+    }
+    async replace(path, name, desired, current, ownership) {
+        const parent = dirname(path);
+        healthy(ownership);
+        await ensureParents(parent, ownership);
+        healthy(ownership);
+        const temporary = join(parent, `.pi-session-mcp-${name}-${randomUUID()}`);
+        const backup = join(parent, `.pi-session-mcp-${name}-${randomUUID()}`);
+        let staged = false;
+        try {
+            healthy(ownership);
+            await mkdir(temporary, { mode: 0o755 });
+            staged = true;
+            for (const file of desired.files) {
+                healthy(ownership);
+                const destination = join(temporary, ...file.path.split("/"));
+                await ensureParents(dirname(destination), ownership);
+                healthy(ownership);
+                const handle = await open(destination, "wx", 0o644);
+                try {
+                    await handle.writeFile(file.bytes);
+                    await handle.sync();
+                }
+                finally {
+                    await handle.close();
+                }
+            }
+            await syncTreeDirectories(temporary, desired, ownership);
+            healthy(ownership);
+            if (!await sameSlot(path, current))
+                throw new Error("skill_slot_changed");
+            healthy(ownership);
+            if (current.state === "tree") {
+                await rename(path, backup);
+                healthy(ownership);
+                await syncDirectory(parent);
+                healthy(ownership);
+            }
+            await rename(temporary, path);
+            staged = false;
+            healthy(ownership);
+            await syncDirectory(parent);
+            healthy(ownership);
+            const after = await inspectSlot(path);
+            if (after.state !== "tree" || after.fingerprint !== desired.fingerprint)
+                throw new Error("skill_post_install_mismatch");
+            if (current.state === "tree") {
+                // Delete only the exact old tree moved by this transaction.
+                if (!await sameSlot(backup, current))
+                    throw new Error("skill_backup_changed");
+                healthy(ownership);
+                await rm(backup, { recursive: true });
+                healthy(ownership);
+                await syncDirectory(parent);
+            }
+        }
+        finally {
+            // An unhealthy fence retains staged/backup content for conservative recovery.
+            if (staged) {
+                healthy(ownership);
+                await rm(temporary, { recursive: true, force: true });
+            }
+        }
+    }
+}
+function healthy(ownership) { ownership.assertHealthy?.(); }
+/** The owned form of a record, without the replaced fingerprint of a finished update. */
+function ownedRecord(record, fingerprint) {
+    return { target: record.target, fingerprint, previous: record.previous, phase: "owned", transactionId: record.transactionId };
+}
+/** The real path of the nearest existing ancestor, with the not yet existing tail appended. */
+async function canonicalExisting(path) {
+    const missing = [];
+    let current = path;
+    for (;;) {
+        try {
+            return join(await realpath(current), ...missing);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT" || dirname(current) === current)
+                throw error;
+            missing.unshift(basename(current));
+            current = dirname(current);
+        }
+    }
+}
+/** Reject symlink parents too, so inspecting a slot never traverses one. */
+async function safeParents(directory) {
+    if (dirname(directory) !== directory)
+        await safeParents(dirname(directory));
+    try {
+        const info = await lstat(directory);
+        if (!info.isDirectory() || info.isSymbolicLink())
+            throw new Error("skill_parent_invalid");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+async function inspectSlot(path, linkTarget) {
+    try {
+        await safeParents(dirname(path));
+        const info = await lstat(path);
+        if (info.isSymbolicLink()) {
+            return linkTarget !== undefined && await realpath(path).then((target) => target === linkTarget, () => false) ? { state: "linked" } : { state: "divergent" };
+        }
+        if (!info.isDirectory())
+            return { state: "divergent" };
+        // Hidden entries are operator content: setup never writes them, and the fingerprint would not protect them.
+        const tree = await readSkillTree(path, { hidden: "reject" });
+        const after = await lstat(path);
+        if (!after.isDirectory() || after.isSymbolicLink() || after.dev !== info.dev || after.ino !== info.ino)
+            return { state: "divergent" };
+        return { state: "tree", fingerprint: tree.fingerprint, dev: info.dev, ino: info.ino };
+    }
+    catch (error) {
+        return { state: error.code === "ENOENT" ? "absent" : "divergent" };
+    }
+}
+async function sameSlot(path, expected, linkTarget) {
+    const actual = await inspectSlot(path, linkTarget);
+    return expected.state === "absent" ? actual.state === "absent" :
+        expected.state === "tree" && actual.state === "tree" && actual.fingerprint === expected.fingerprint && actual.dev === expected.dev && actual.ino === expected.ino;
+}
+async function ensureParents(directory, ownership) {
+    if (dirname(directory) !== directory)
+        await ensureParents(dirname(directory), ownership);
+    try {
+        const info = await lstat(directory);
+        if (!info.isDirectory() || info.isSymbolicLink())
+            throw new Error("skill_parent_invalid");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        healthy(ownership);
+        await mkdir(directory, { mode: 0o755 });
+        healthy(ownership);
+        await syncDirectory(directory);
+        await syncDirectory(dirname(directory));
+    }
+}
+async function syncDirectory(directory) {
+    const handle = await open(directory, "r");
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function syncTreeDirectories(root, tree, ownership) {
+    const directories = new Set([root]);
+    for (const file of tree.files) {
+        let cursor = dirname(join(root, file.path));
+        while (cursor !== root) {
+            directories.add(cursor);
+            cursor = dirname(cursor);
+        }
+    }
+    for (const directory of [...directories].sort((a, b) => b.length - a.length)) {
+        healthy(ownership);
+        await syncDirectory(directory);
+    }
+}

package/dist/setup.d.ts

@@ -1,5 +1,6 @@
 import type { CommandExecution, CommandRunner, RegistrationIntent, RegistrationState } from "./client-adapters/types.js";
 import { type OwnershipStore } from "./setup-ownership.js";
+import { type SetupSkillInstaller } from "./setup-skills.js";
 import { type SetupOperation, type SetupResult, type SetupTarget } from "./setup-result.js";
 export interface SetupClientAdapter {
     readonly name: string;
@@ -25,6 +26,7 @@ export interface SetupDependencies {
     readonly adapters?: readonly SetupClientAdapter[];
     readonly doctor?: SetupDoctor;
     readonly ownership?: OwnershipStore;
+    readonly skills?: SetupSkillInstaller;
     readonly intendedFingerprint: string;
 }
 export interface SetupRequest {
@@ -35,8 +37,13 @@ export declare const isSupportedTarget: (target: SetupTarget) => boolean;
 export declare class SetupOrchestrator {
     private readonly dependencies;
     private readonly ownership;
+    /** Apply results that the up-front plan refused: nothing was applied, so no skill is touched. */
+    private readonly refusedApplies;
     constructor(dependencies: SetupDependencies);
     run(request: SetupRequest): Promise<SetupResult>;
+    /** Registration planning gates apply; skill divergence must not block registration. */
+    private withSkills;
+    private restoreWithSkills;
     private adapter;
     private assertOwnershipHealthy;
     private signal;

package/dist/setup.js

@@ -8,6 +8,7 @@ import { createMcpStdioLauncher } from "./setup-process.js";
 import { verifyMcpCapabilities } from "./client-adapters/mcp-verifier.js";
 import { PACKAGE_VERSION, readLockfile, readPackageMetadata } from "./package-metadata.js";
 import { DurableOwnershipStore, MemoryOwnershipStore } from "./setup-ownership.js";
+import { FileSetupSkillInstaller } from "./setup-skills.js";
 import { result } from "./setup-result.js";
 export const isSupportedTarget = (target) => target.alias === "pi-session-mcp" &&
     (target.client === "codex" ? target.scope === "user" :
@@ -15,6 +16,8 @@ export const isSupportedTarget = (target) => target.alias === "pi-session-mcp" &
 export class SetupOrchestrator {
     dependencies;
     ownership;
+    /** Apply results that the up-front plan refused: nothing was applied, so no skill is touched. */
+    refusedApplies = new WeakSet();
     constructor(dependencies) {
         this.dependencies = dependencies;
         this.ownership = dependencies.ownership ?? new MemoryOwnershipStore();
@@ -25,14 +28,40 @@ export class SetupOrchestrator {
         if (targets.length !== request.targets.length || targets.length === 0)
             return result(operation, [{ target: { client: "invalid", scope: "invalid", alias: "invalid" }, status: "failed", code: "target_invalid" }], "failed");
         if (operation === "dry-run")
-            return this.plan(targets, this.ownership);
+            return this.withSkills(await this.plan(targets, this.ownership), this.ownership);
         if (operation === "apply")
-            return this.ownership.transaction((ownership) => this.apply(targets, ownership));
+            return this.ownership.transaction(async (ownership) => this.withSkills(await this.apply(targets, ownership), ownership));
         if (operation === "verify")
-            return this.ownership.transaction((ownership) => this.verify(targets, ownership));
+            return this.ownership.transaction(async (ownership) => this.withSkills(await this.verify(targets, ownership), ownership));
         if (operation === "rollback")
-            return this.ownership.transaction((ownership) => this.restore(targets, "rolled_back", ownership));
-        return this.ownership.transaction((ownership) => this.restore(targets, "removed", ownership));
+            return this.ownership.transaction((ownership) => this.restoreWithSkills(targets, "rolled_back", ownership));
+        return this.ownership.transaction((ownership) => this.restoreWithSkills(targets, "removed", ownership));
+    }
+    /** Registration planning gates apply; skill divergence must not block registration. */
+    async withSkills(registrations, ownership) {
+        const skills = this.dependencies.skills;
+        if (!skills || this.refusedApplies.has(registrations))
+            return registrations;
+        const findings = [];
+        for (const finding of registrations.findings) {
+            findings.push(finding);
+            const operation = registrations.operation;
+            const canRun = operation === "dry-run" || operation === "verify" ||
+                (operation === "apply" ? ["ok", "unchanged"].includes(finding.status) : finding.status === "ok");
+            if (canRun)
+                findings.push(...await skills.run(operation, finding.target, ownership));
+        }
+        const failed = findings.some((finding) => ["failed", "unsupported", "divergent"].includes(finding.status));
+        return result(registrations.operation, findings, failed ? "failed" : registrations.status, failed ? 1 : registrations.exitCode);
+    }
+    async restoreWithSkills(targets, success, ownership) {
+        if (!this.dependencies.skills)
+            return this.restore(targets, success, ownership);
+        const findings = [];
+        // Process each removal and its skill before removing another shared registration.
+        for (const target of targets)
+            findings.push(...(await this.withSkills(await this.restore([target], success, ownership), ownership)).findings);
+        return result(success === "removed" ? "remove" : "rollback", findings);
     }
     adapter(t) { return this.dependencies.adapters?.find((a) => a.name === t.client && a.supportedScopes.includes(t.scope)); }
     assertOwnershipHealthy(ownership) { ownership.assertHealthy?.(); }
@@ -84,7 +113,9 @@ export class SetupOrchestrator {
             const findings = plan.findings.map((finding) => finding.status === "divergent" && finding.code === "divergent"
                 ? { ...finding, code: "divergence_requires_replacement" }
                 : finding);
-            return result("apply", findings, "failed");
+            const refused = result("apply", findings, "failed");
+            this.refusedApplies.add(refused);
+            return refused;
         }
         const findings = [];
         for (const target of targets) {
@@ -205,6 +236,17 @@ export class SetupOrchestrator {
                 findings.push({ target, status: "unsupported", code: "client_unsupported" });
                 continue;
             }
+            if (!owned && this.dependencies.skills && await this.safe(() => this.dependencies.skills.owns(target, ownership))) {
+                // Registration removal can finish before skill cleanup (or before a crash). Retry only
+                // for a skill setup still owns, and only after proving the registration is absent; an
+                // unowned live registration stays untouched.
+                const current = await this.safe(() => adapter.inspect(target, this.dependencies.intendedFingerprint));
+                this.assertOwnershipHealthy(ownership);
+                if (current?.state === "absent") {
+                    findings.push({ target, status: "ok", code: success });
+                    continue;
+                }
+            }
             if (!owned || (owned.phase !== "owned" && owned.phase !== "pending")) {
                 findings.push({ target, status: "failed", code: "ownership_unavailable" });
                 continue;
@@ -320,6 +362,7 @@ export async function createProductionSetup(runner, packageRoot, configPath, own
                 return { ok: doctor.ok, code: doctor.ok ? "doctor_ok" : "doctor_failed" };
             },
         },
+        skills: new FileSetupSkillInstaller({ packageRoot, configPath, home: homedir(), cwd: process.cwd() }),
         ownership: new DurableOwnershipStore(ownershipPath, { ...(signal ? { signal } : {}) }),
         intendedFingerprint: await fingerprintFor(referenceTarget),
     };

package/dist/skill-catalog.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A catalog skill that an execution profile selects. The alias is the only public name;
+ * the path stays inside the server and never appears in MCP output, errors or diagnostics.
+ */
+export interface SkillSelection {
+    /** The operator's `skillCatalog` alias. Path-free; it may differ from the skill's own name. */
+    readonly alias: string;
+    /** Absolute path of the selected `SKILL.md`, resolved against the configuration file's directory. */
+    readonly path: string;
+}
+export declare const MAX_SKILL_CATALOG_ENTRIES = 64;
+export declare const MAX_PROFILE_SKILLS = 16;
+export declare const MAX_SKILL_PATH_LENGTH = 4096;
+/** Upper bound for one selected `SKILL.md`, checked before the Pi SDK reads it. */
+export declare const MAX_SKILL_FILE_BYTES: number;
+export declare const SKILL_FILE_NAME = "SKILL.md";
+/** The library skill name of a `builtin:<name>` catalog value; undefined for every other value. */
+export declare function builtinSkillName(value: string): string | 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 declare function isSkillCatalogPath(value: string): boolean;

package/dist/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/dist/skill-customize.d.ts

@@ -0,0 +1,23 @@
+import { type SetupResult } from "./setup-result.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 declare const SKILL_BASES_FILE = ".pi-session-mcp-bases.json";
+export declare const MAX_SKILL_BASES_BYTES: number;
+export declare class SkillBasesError extends Error {
+    constructor();
+}
+export type SkillBases = Readonly<Record<string, string>>;
+/** Strictly validated contents of the bases file; an absent file or override directory is an empty record. */
+export declare function readSkillBases(overrideDirectory: string): Promise<SkillBases>;
+export interface SkillCustomizeRequest {
+    readonly name: string;
+    readonly configPath: string;
+    readonly apply: boolean;
+    /** Package root that holds the shipped `skills/` directory; defaults to this package. */
+    readonly packageRoot?: string;
+}
+export declare function customizeSkill(request: SkillCustomizeRequest): Promise<SetupResult>;