pi-session-mcp 0.7.1 → 0.8.0

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.1**.
+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/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();
+    }
+}

package/dist/sdk-pi-adapter.d.ts

@@ -1,4 +1,4 @@
-import { type AgentSessionEvent, type CreateAgentSessionOptions, type CreateAgentSessionResult, createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, DefaultResourceLoader, ModelRuntime, type PromptOptions, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { type AgentSessionEvent, type CreateAgentSessionOptions, type CreateAgentSessionResult, createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, DefaultResourceLoader, ModelRuntime, type PromptOptions, type Skill, SettingsManager } from "@earendil-works/pi-coding-agent";
 import { type ExtensionSpec } from "./extension-spec.js";
 import type { ResolvedExecutionProfile, ThinkingLevel } from "./execution-profile.js";
 import { type McpConnectionFactory } from "./mcp-session-tools.js";
@@ -11,7 +11,7 @@ export declare const SESSION_CREATION_TIMEOUT_MS = 10000;
 export interface SdkPiAdapterDiagnostic {
     readonly level: "error";
     readonly event: "pi_session_creation_failed";
-    readonly stage: "runtime" | "provider" | "model" | "check_auth" | "get_auth" | "availability" | "resource_loader" | "mcp_tools" | "create_session" | "postcheck" | "extension_resolve" | "extension_load" | "extension_bind";
+    readonly stage: "runtime" | "provider" | "model" | "check_auth" | "get_auth" | "availability" | "resource_loader" | "mcp_tools" | "create_session" | "postcheck" | "extension_resolve" | "extension_load" | "extension_bind" | "skill_load";
     readonly code: PiSessionCreationErrorCode;
     readonly executionProfile: string;
     readonly provider: string;
@@ -22,6 +22,8 @@ export interface SdkPiAdapterDiagnostic {
     readonly discoveredToolCount?: number;
     /** `<name>@<version>` of the extension that failed to resolve; never a path. */
     readonly extension?: string;
+    /** The failing configured catalog alias, never a skill-file name or path. */
+    readonly skill?: string;
 }
 /** The Pi SDK session-lifecycle API used for profiles with extensions; injectable for tests. */
 export interface ExtensionSdk {
@@ -64,7 +66,7 @@ export type PromptDisposition = Parameters<NonNullable<PromptOptions["preflightR
  * typecheck (and therefore the Pi SDK canary) instead of being mapped silently.
  */
 export declare function admitsTurn(disposition: PromptDisposition): boolean;
-export declare function createPhase0ResourceLoader(cwd: string): Promise<{
+export declare function createPhase0ResourceLoader(cwd: string, skills?: readonly Skill[]): Promise<{
     resourceLoader: DefaultResourceLoader;
     settingsManager: SettingsManager;
 }>;
@@ -83,6 +85,8 @@ export declare class SdkPiSessionAdapter implements PiSessionAdapter {
         signal?: AbortSignal;
     }): Promise<PiSessionHandle>;
     private createWithExtensions;
+    private loadSkills;
+    private checkResources;
     /** Provider, model, authentication and availability, exactly as configured. */
     private resolveVerifiedModel;
     private connectMcpTools;