pi-session-mcp 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,116 @@
 
 ## 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.
+
+- Extension tool names are now limited to 1 to 64 letters, digits, `_` and
+  `-`, not starting with `-`, so `.` and `:` no longer pass and every name fits
+  the common provider function-name limit. Names that Pi SDK 1.1.0 treats as
+  MCP tools (the `mcp__` prefix, `list_mcp_resources`,
+  `list_mcp_resource_templates`, `read_mcp_resource`) are rejected too, because
+  the SDK would keep them outside the allowlist. Both cases fail with
+  `extension_tool_conflict`. Fixes #41.
+- Extension pins with build metadata, such as `npm:<name>@1.2.3+build.1`, are
+  now rejected when the configuration loads. npm does not keep build metadata
+  in a published version, so such a pin could never match the installed
+  manifest. Such a configuration is now invalid as a whole: the server does not
+  start and Doctor reports `config_invalid`, instead of every session of the
+  profile failing with `extension_version_mismatch`. Fixes #42.
+- Client prompts now reach Pi with `source: "rpc"`, the marker Pi's own RPC
+  mode uses for input from a program, instead of the SDK default
+  `interactive`. Extension `input` hooks that read the source now see that a
+  program, not a human at the terminal, sent the prompt. Fixes #43.
+- The npm package no longer ships the implementation plans under
+  `docs/superpowers/`; the operator documentation stays included. A test
+  checks the packed file list. Fixes #39.
+
 ## 0.7.0 — 2026-10-11
 
 This is a minor release because the public contract changes, as ADR 0003

package/README.md

@@ -18,6 +18,7 @@ Reasons to do that:
 - **Follow-up turns keep their context.** A session stays open across prompts, so a follow-up question does not pay for the same exploration twice.
 - **You set the limits, not the agent.** The client can only pick from the workspaces and profiles in your configuration file. It cannot name a directory, a model, a provider or a permission level, and the default profile is read-only.
 - **Exactly the extra tools a task needs.** A profile can grant individual tools of local stdio MCP servers to its sessions, and nothing else from those servers.
+- **Role instructions you control.** A profile can select Pi skills from a catalog in your configuration, such as the implementation and review skills this package ships, or your own versions of them. The client cannot choose skills. The package also ships an orchestration skill for the controlling agent, which `setup` installs into Claude Code and Codex.
 - **Predictable to automate.** Sessions and turns have a small set of states and stable error codes. Results contain no paths, credentials, prompts or raw provider errors.
 - **Small footprint.** No daemon, no network listener and no stored state. An offline `doctor` checks an installation, and `setup` registers, verifies and removes the server reproducibly.
 
@@ -29,7 +30,7 @@ It is not the right tool when:
 
 ## Status
 
-The package version is **0.7.0**.
+The package version is **0.8.0**.
 
 - **Pre-1.0.** The public tool contract is stable within a minor line: a change to tools, fields, states or error codes needs a new minor release.
 - **Linux and macOS**, Node.js 22.19.0 or newer. macOS is tested in CI on macOS 15 and 26 on Apple silicon; Intel Macs run the same code but are untested. Setup acceptance on a real Mac is recorded for Claude Code only; Codex is still pending. See [Acceptance](docs/acceptance.md#status). On other platforms `setup` refuses with `platform_unsupported`.
@@ -76,9 +77,17 @@ pi-session-mcp-setup --apply --target claude-code:user:pi-session-mcp
 pi-session-mcp-setup --verify --target claude-code:user:pi-session-mcp
 ```
 
-Use `codex:user:pi-session-mcp` for Codex. The example configuration contains placeholders only: replace the workspace, provider and model with real local values, and never add credentials to the file.
+Use `codex:user:pi-session-mcp` for Codex. The example configuration contains placeholders only: replace the workspace, provider and model with real local values, and never add credentials to the file. The example also registers the two worker skills with `builtin:` references, which resolve to the skills in the package, so the copied example needs no path edits for skills (see [Pi skills](docs/skills.md)).
 
-`pi-session-mcp-doctor` is an offline health check. `pi-session-mcp-setup` plans by default, changes a client registration only with an explicit operation, and never replaces an existing divergent registration. Neither needs credentials, a provider or a model.
+`--apply` registers the server and also installs the controller skill `pi-session-orchestration` for that client, so the agent knows how to drive Pi worker sessions: Claude Code `user` and `local` get `~/.claude/skills/`, Claude Code `project` gets `.claude/skills/` of the project, and Codex gets `~/.agents/skills/`. Setup never replaces a skill it did not install or that you modified. To adjust a skill, copy it into the override directory next to your configuration file and edit the copy:
+
+```bash
+pi-session-mcp-setup --apply --customize-skill pi-session-review
+```
+
+To add a skill of your own, create `skills/<name>/SKILL.md` next to the configuration file and reference it as `builtin:<name>`. Do not edit the installed package or the installed copy in the client.
+
+`pi-session-mcp-doctor` is an offline health check. `pi-session-mcp-setup` plans by default, changes a client registration or skill only with an explicit operation, and never replaces an existing divergent registration or a skill it did not install. Neither needs credentials, a provider or a model.
 
 The [installation guide](docs/installation.md) also covers installing from a release tag with the exact locked dependency tree, the configuration rules, existing registrations, configuration changes, upgrades and removal.
 
@@ -104,6 +113,7 @@ The [installation guide](docs/installation.md) also covers installing from a rel
 - A workspace alias maps to a directory. Clients can select aliases only.
 - An execution profile binds a permission profile (`read-only` or `coding`), a provider, a model and a thinking level. Exactly one profile is the default, and it must be `read-only`.
 - A profile can grant individual tools of local stdio MCP servers to its sessions; see [External MCP tools in embedded sessions](docs/session-mcp.md).
+- An optional top-level `skillCatalog` maps skill aliases to `builtin:<name>` (a skill of the package or of your override directory) or to a `SKILL.md` file, and a profile's optional `skills` selects aliases from it. A profile without `skills` gets no skills. See [Pi skills](docs/skills.md).
 - The server reads the file once at startup. Start a new client session after changing it.
 
 ## Run it by hand
@@ -144,6 +154,7 @@ Operate:
 - [Installation](docs/installation.md)
 - [Client setup reference](docs/client-setup.md): manual registration, the tool flow, deadlines and troubleshooting
 - [External MCP tools in embedded sessions](docs/session-mcp.md)
+- [Pi skills in execution profiles](docs/skills.md)
 - [Changelog](CHANGELOG.md)
 
 Contract and design:
@@ -157,6 +168,7 @@ Contract and design:
 - [ADR 0002: embedded Pi SDK](docs/adr/0002-embedded-pi-sdk.md)
 - [ADR 0003: no new feature phase after the MVP](docs/adr/0003-post-mvp-maintenance.md)
 - [ADR 0004: setup accepts clients by contract, not by version](docs/adr/0004-client-contract-not-version.md)
+- [ADR 0007: execution profiles select Pi skills from an operator catalog](docs/adr/0007-profile-skill-selection.md)
 
 Maintain:
 

package/dist/capabilities.d.ts

@@ -22,5 +22,6 @@ export declare function projectCapabilities(workspaces: ReadonlyMap<string, stri
         model: string;
         thinkingLevel: import("./execution-profile.js").ThinkingLevel;
         extensions: string[];
+        skills: string[];
     }[];
 };

package/dist/capabilities.js

@@ -14,7 +14,7 @@ export function projectCapabilities(workspaces, executionProfiles, configuration
             .map((alias) => ({ alias })),
         executionProfiles: [...executionProfiles.values()]
             .sort((left, right) => compareAliases(left.alias, right.alias))
-            .map(({ alias, default: isDefault, permissionProfile, provider, model, thinkingLevel, extensions }) => ({
+            .map(({ alias, default: isDefault, permissionProfile, provider, model, thinkingLevel, extensions, skills }) => ({
             alias,
             default: isDefault,
             permissionProfile,
@@ -22,6 +22,7 @@ export function projectCapabilities(workspaces, executionProfiles, configuration
             model,
             thinkingLevel,
             extensions: (extensions ?? []).map((extension) => extension.spec),
+            skills: (skills ?? []).map((skill) => skill.alias),
         })),
     };
 }

package/dist/client-adapters/mcp-verifier.js

@@ -1,4 +1,5 @@
 import { MAX_PROFILE_EXTENSIONS, parseExtensionSpec } from "../extension-spec.js";
+import { MAX_PROFILE_SKILLS } from "../skill-catalog.js";
 import { PACKAGE_NAME, PACKAGE_VERSION } from "../package-metadata.js";
 export const MCP_VERIFY_TIMEOUT_MS = 5_000;
 export const MCP_MAX_FRAME_BYTES = 65_536;
@@ -99,7 +100,7 @@ function validCapabilities(value) {
         if (!profile || typeof profile !== "object")
             return false;
         const record = profile;
-        return exactKeys(record, ["alias", "default", "permissionProfile", "provider", "model", "thinkingLevel", "extensions"])
+        return exactKeys(record, ["alias", "default", "permissionProfile", "provider", "model", "thinkingLevel", "extensions", "skills"])
             && typeof record.alias === "string" && ALIAS_PATTERN.test(record.alias)
             && typeof record.default === "boolean"
             && (record.permissionProfile === "read-only" || record.permissionProfile === "coding")
@@ -107,7 +108,10 @@ function validCapabilities(value) {
             && typeof record.model === "string" && record.model.length > 0 && record.model.length <= 256
             && typeof record.thinkingLevel === "string" && ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(record.thinkingLevel)
             && Array.isArray(record.extensions) && record.extensions.length <= MAX_PROFILE_EXTENSIONS
-            && record.extensions.every((spec) => typeof spec === "string" && parseExtensionSpec(spec) !== undefined);
+            && record.extensions.every((spec) => typeof spec === "string" && parseExtensionSpec(spec) !== undefined)
+            && Array.isArray(record.skills) && record.skills.length <= MAX_PROFILE_SKILLS
+            && record.skills.every((skill) => typeof skill === "string" && ALIAS_PATTERN.test(skill))
+            && new Set(record.skills).size === record.skills.length;
     }))
         return false;
     const defaults = profiles.filter((profile) => profile.default === true);

package/dist/config.d.ts

@@ -7,6 +7,7 @@ export declare class ConfigError extends Error {
 }
 export declare const configSchema: z.ZodObject<{
     workspaces: z.ZodRecord<z.ZodString, z.ZodString>;
+    skillCatalog: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     executionProfiles: z.ZodRecord<z.ZodString, z.ZodObject<{
         default: z.ZodBoolean;
         permissionProfile: z.ZodEnum<{
@@ -26,6 +27,7 @@ export declare const configSchema: z.ZodObject<{
         }>;
         mcpServers: z.ZodOptional<z.ZodCustom<Readonly<Record<string, import("./mcp-config.js").McpServerConfig>>, Readonly<Record<string, import("./mcp-config.js").McpServerConfig>>>>;
         extensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 /** The only supported reload behavior: a running controller keeps the snapshot it loaded at startup. */
@@ -42,6 +44,8 @@ export interface AppConfig {
     readonly executionProfiles: ReadonlyMap<string, ConfiguredExecutionProfile>;
     readonly defaultExecutionProfile: string;
     readonly configuration: ConfigurationMetadata;
+    /** Absolute skill override directory next to the configuration file. Internal; never projected. */
+    readonly skillOverrideDirectory: string;
 }
 /**
  * The configuration path comes only from the caller or from `PI_SESSION_MCP_CONFIG`.

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

@@ -2,7 +2,7 @@ import { type AppConfig } from "./config.js";
 import { type ExtensionSpec } from "./extension-spec.js";
 export type DoctorSeverity = "ok" | "warning" | "error";
 export type DoctorExitCode = 0 | 1 | 2 | 64;
-export type DoctorCheckId = "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";
+export type DoctorCheckId = "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";
 export interface DoctorCheck {
     readonly id: DoctorCheckId;
     readonly severity: DoctorSeverity;
@@ -30,8 +30,11 @@ export interface DoctorFileSystem {
         readonly isDirectory: () => boolean;
         readonly isFile: () => boolean;
         readonly mtimeMs?: number;
+        readonly size?: number;
     }>;
     readonly access: (path: string, mode: number) => Promise<void>;
+    /** Canonical path; defaults to the real file system when an injected fake omits it. */
+    readonly realpath?: (path: string) => Promise<string>;
 }
 export interface DoctorDependencies {
     readonly packageRoot?: string;

package/dist/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/dist/execution-profile.d.ts

@@ -1,5 +1,6 @@
 import type { ExtensionSpec } from "./extension-spec.js";
 import { type McpServers } from "./mcp-config.js";
+import type { SkillSelection } from "./skill-catalog.js";
 export declare const ALIAS_PATTERN: RegExp;
 export type PermissionProfile = "read-only" | "coding";
 export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
@@ -13,6 +14,8 @@ export interface ConfiguredExecutionProfile {
     readonly thinkingLevel: ThinkingLevel;
     readonly mcpServers?: McpServers;
     readonly extensions?: readonly ExtensionSpec[];
+    /** The selected catalog skills in configured order; absent when the profile selects none. */
+    readonly skills?: readonly SkillSelection[];
 }
 /** The immutable, server-side selection passed to the Pi adapter. */
 export interface ResolvedExecutionProfile {
@@ -23,6 +26,7 @@ export interface ResolvedExecutionProfile {
     readonly thinkingLevel: ThinkingLevel;
     readonly mcpServers?: McpServers;
     readonly extensions?: readonly ExtensionSpec[];
+    readonly skills?: readonly SkillSelection[];
 }
 export declare function toResolvedExecutionProfile(profile: ConfiguredExecutionProfile): ResolvedExecutionProfile;
 /** A small read-only map implementation which has no mutating methods at runtime. */

package/dist/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/dist/extension-spec.js

@@ -1,7 +1,12 @@
 export const MAX_PROFILE_EXTENSIONS = 8;
 const MAX_SPEC_LENGTH = 256;
-/** `npm:<name>@<exact semver>`; the name may be scoped. Ranges, tags, git sources and paths never match. */
-const EXTENSION_SPEC_PATTERN = /^npm:((?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*)@(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)$/;
+/**
+ * `npm:<name>@<exact semver>` with an optional prerelease; the name may be scoped. Ranges, tags,
+ * git sources and paths never match. Build metadata (`+build`) never matches either: npm does not
+ * keep it in a published version, so such a pin could never equal the installed manifest. Rejecting
+ * it here fails the configuration instead of every session with `extension_version_mismatch`.
+ */
+const EXTENSION_SPEC_PATTERN = /^npm:((?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*)@(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)$/;
 export function parseExtensionSpec(spec) {
     if (spec.length > MAX_SPEC_LENGTH)
         return undefined;

package/dist/pi-adapter.d.ts

@@ -13,7 +13,7 @@ export interface PiAppliedSelection {
     readonly model: string;
     readonly thinkingLevel: ThinkingLevel;
 }
-export type PiSessionCreationErrorCode = "unknown_provider" | "unknown_model" | "local_authentication_missing" | "local_authentication_unavailable" | "model_unavailable" | "thinking_level_unavailable" | "execution_selection_mismatch" | "external_mcp_unavailable" | "external_mcp_no_tools" | "external_mcp_grant_tool_missing" | "external_mcp_activation_mismatch" | "extension_not_installed" | "extension_version_mismatch" | "extension_load_failed" | "extension_tool_conflict" | "pi_session_creation_failed";
+export type PiSessionCreationErrorCode = "unknown_provider" | "unknown_model" | "local_authentication_missing" | "local_authentication_unavailable" | "model_unavailable" | "thinking_level_unavailable" | "execution_selection_mismatch" | "external_mcp_unavailable" | "external_mcp_no_tools" | "external_mcp_grant_tool_missing" | "external_mcp_activation_mismatch" | "extension_not_installed" | "extension_version_mismatch" | "extension_load_failed" | "extension_tool_conflict" | "skill_load_failed" | "pi_session_creation_failed";
 export declare class PiSessionCreationError extends Error {
     readonly code: PiSessionCreationErrorCode;
     constructor(code: PiSessionCreationErrorCode);

package/dist/pi-adapter.js

@@ -14,6 +14,7 @@ const PI_SESSION_CREATION_MESSAGES = {
     extension_version_mismatch: "Configured Pi extension version is not installed",
     extension_load_failed: "Configured Pi extension could not be loaded",
     extension_tool_conflict: "Configured Pi extension tools conflict",
+    skill_load_failed: "Configured Pi skill could not be loaded",
     pi_session_creation_failed: "Pi session creation failed",
 };
 export class PiSessionCreationError extends Error {

package/dist/pi-skills.d.ts

@@ -0,0 +1,17 @@
+import { type Stats } from "node:fs";
+import { loadSkills, type Skill } from "@earendil-works/pi-coding-agent";
+import { PiSessionCreationError } from "./pi-adapter.js";
+import { type SkillSelection } from "./skill-catalog.js";
+export declare class PiSkillError extends PiSessionCreationError {
+    readonly alias?: string | undefined;
+    constructor(alias?: string | undefined);
+}
+interface SkillDependencies {
+    readonly stat: (path: string) => Promise<Stats>;
+    readonly access: (path: string, mode: number) => Promise<void>;
+    readonly realpath: (path: string) => Promise<string>;
+    readonly loadSkills: typeof loadSkills;
+}
+/** Load only the configured files, independently of package discovery and SDK deduplication. */
+export declare function loadSelectedSkills(selection: readonly SkillSelection[], cwd: string, dependencies?: Partial<SkillDependencies>): Promise<Skill[]>;
+export {};

package/dist/pi-skills.js

@@ -0,0 +1,64 @@
+import { constants } from "node:fs";
+import { access, realpath, stat } from "node:fs/promises";
+import { resolve } from "node:path";
+import { loadSkills } from "@earendil-works/pi-coding-agent";
+import { PiSessionCreationError } from "./pi-adapter.js";
+import { MAX_SKILL_FILE_BYTES } from "./skill-catalog.js";
+export class PiSkillError extends PiSessionCreationError {
+    alias;
+    constructor(alias) {
+        super("skill_load_failed");
+        this.alias = alias;
+        this.name = "PiSkillError";
+    }
+}
+/** Load only the configured files, independently of package discovery and SDK deduplication. */
+export async function loadSelectedSkills(selection, cwd, dependencies = {}) {
+    if (selection.length === 0)
+        return [];
+    const fs = { stat, access, realpath, loadSkills, ...dependencies };
+    const paths = [];
+    const canonical = new Set();
+    try {
+        for (const selected of selection) {
+            try {
+                const path = resolve(selected.path);
+                const info = await fs.stat(path);
+                if (!info.isFile() || info.size > MAX_SKILL_FILE_BYTES)
+                    throw new PiSkillError(selected.alias);
+                await fs.access(path, constants.R_OK);
+                const real = await fs.realpath(path);
+                if (canonical.has(real))
+                    throw new PiSkillError(selected.alias);
+                canonical.add(real);
+                paths.push(path);
+            }
+            catch {
+                throw new PiSkillError(selected.alias);
+            }
+        }
+        const result = fs.loadSkills({ cwd, agentDir: cwd, skillPaths: paths, includeDefaults: false });
+        if (result.diagnostics.length > 0) {
+            const aliases = new Set(result.diagnostics.map((diagnostic) => {
+                const index = paths.indexOf(diagnostic.path ?? "");
+                return index < 0 ? undefined : selection[index].alias;
+            }));
+            throw new PiSkillError(aliases.size === 1 ? [...aliases][0] : undefined);
+        }
+        if (result.skills.length !== paths.length) {
+            const missing = selection.filter((_selected, index) => !result.skills.some((skill) => skill.filePath === paths[index]));
+            throw new PiSkillError(missing.length === 1 ? missing[0].alias : undefined);
+        }
+        return paths.map((path, index) => {
+            const matches = result.skills.filter((skill) => skill.filePath === path);
+            if (matches.length !== 1 || matches[0].disableModelInvocation === true)
+                throw new PiSkillError(selection[index].alias);
+            return matches[0];
+        });
+    }
+    catch (error) {
+        if (error instanceof PiSkillError)
+            throw error;
+        throw new PiSkillError();
+    }
+}