pi-session-mcp 0.7.1 → 0.8.0

package/docs/skills.md

@@ -0,0 +1,487 @@
+# Pi skills in execution profiles
+
+Status: decided in [ADR 0007](adr/0007-profile-skill-selection.md), issue
+[#46](https://github.com/plagor44-ux/pi-session-mcp/issues/46).
+
+A Pi skill is a `SKILL.md` file with instructions that Pi lists to the model in
+its system prompt. The model may read the file when a task matches the skill's
+description. Pi Session MCP lets the operator register skill files in a catalog
+and select them per execution profile. MCP callers never choose skills.
+
+The package ships three skills and keeps them in a skill library together with
+the operator's own overrides. `pi-session-mcp-setup --apply` also installs the
+controller skill into Claude Code and Codex. Nothing needs to be linked by hand.
+Sections: [Configuration](#configuration), [The skill library](#the-skill-library),
+[Customize and add skills](#customize-and-add-skills) and [Install the
+orchestration skill into Codex and Claude Code](#install-the-orchestration-skill-into-codex-and-claude-code).
+
+## Configuration
+
+Two optional parts of `pi-session-mcp.json`:
+
+```json
+{
+  "workspaces": {
+    "my-project": "/absolute/path/to/my-project"
+  },
+  "skillCatalog": {
+    "pi-session-implementation": "builtin:pi-session-implementation",
+    "pi-session-review": "builtin:pi-session-review",
+    "release-notes": "skills-local/release-notes/SKILL.md"
+  },
+  "executionProfiles": {
+    "safe-readonly": {
+      "default": true,
+      "permissionProfile": "read-only",
+      "provider": "your-configured-provider",
+      "model": "your-configured-model",
+      "thinkingLevel": "medium",
+      "skills": ["pi-session-review"]
+    },
+    "coding-worker": {
+      "default": false,
+      "permissionProfile": "coding",
+      "provider": "your-configured-provider",
+      "model": "your-configured-model",
+      "thinkingLevel": "high",
+      "skills": ["pi-session-implementation", "release-notes"]
+    }
+  }
+}
+```
+
+### Catalog: `skillCatalog`
+
+- An optional top-level object that maps a skill alias to the path of a
+  `SKILL.md` file. A missing catalog is an empty catalog.
+- At most 64 entries. An alias matches `^[a-z][a-z0-9_-]{0,63}$`, like every
+  other alias.
+- Each value is either `builtin:<name>` or names exactly one regular, readable
+  file whose last path segment is `SKILL.md`. `builtin:<name>` refers to a
+  skill of the [skill library](#the-skill-library); `<name>` must follow the
+  skill name rule below, and `builtin:` followed by anything else is rejected.
+  Directories, globs, URLs and every other scheme-prefixed source (`npm:`,
+  `git+…`, `https:`) are rejected. So are `~` and backslashes. A value has at
+  most 4096 characters.
+- A relative path resolves against the directory of the configuration file,
+  like a workspace. It never resolves against a workspace or the shell's
+  working directory. `~` is not expanded: write an absolute path, or use
+  `builtin:<name>` for a library skill.
+- A skill folder needs no `package.json` and no extension. The file can live
+  anywhere the server's OS user can read. Keep catalog files outside every
+  configured workspace: a `coding` session can change any file in its
+  workspace, and a changed skill reaches other sessions too (see
+  [snapshot semantics](#snapshot-semantics)).
+- The catalog alias is only the public handle. It may differ from the `name` in
+  the skill's own frontmatter. Nothing is renamed.
+
+### Selection: `executionProfiles.<alias>.skills`
+
+- An optional list of catalog aliases, at most 16, no duplicates.
+- Missing or empty means no skills for that profile. There is no inheritance
+  between profiles and no default skill.
+- All other profile fields and the rule that unknown fields are rejected are
+  unchanged.
+
+### Invalid configuration
+
+These make the whole configuration invalid. The server does not start, and
+Doctor reports `config_invalid`. Stderr shows the stable startup code
+`invalid_execution_profile_config`:
+
+- a selected alias that is not in the catalog;
+- a duplicate alias in one profile's list;
+- two selected aliases of one profile whose paths resolve to the same path,
+  for example two aliases for `builtin:pi-session-review`;
+- a catalog value that violates the rules above (including a malformed
+  `builtin:` name), or more than 64 entries;
+- more than 16 selected aliases.
+
+## The skill library
+
+The skill library has two sources and nothing else:
+
+1. **Shipped skills.** The package's `skills/` directory.
+2. **Operator overrides.** A `skills/` directory next to the configuration
+   file, that is, in the directory of the path in `PI_SESSION_MCP_CONFIG`. For
+   the default location `~/.config/pi-session-mcp/pi-session-mcp.json` it is
+   `~/.config/pi-session-mcp/skills/<name>/SKILL.md`.
+
+An override with the same name replaces the shipped skill. A name that is not
+shipped adds a skill. A name follows the Agent Skills rule: lowercase letters
+and digits in hyphen-separated groups, 1 to 64 characters. No other directory
+is searched: not the current directory, not a workspace and not a client's
+skill directory.
+
+### `builtin:<name>` in the catalog
+
+A catalog value `builtin:<name>` resolves to `<override dir>/<name>/SKILL.md`
+if that file exists, else to the shipped skill of that name. If neither
+exists, the value keeps the shipped location. Nothing fails when the
+configuration loads, but Doctor then reports `skill_missing` for the profile
+that selects it, and a session start fails with `skill_load_failed`.
+
+Resolution happens when the server loads the configuration. Adding or removing
+an override therefore needs a server restart, like any configuration change.
+Edits to a skill file that already resolves reach new sessions, as described
+under [snapshot semantics](#snapshot-semantics). Deleting a resolved override
+leaves the catalog pointing at a missing file until the restart.
+
+The shipped example configuration registers the two worker skills with
+`builtin:`. After you copy the example, its skill entries need no path edits.
+
+### Shipped skills
+
+The package ships three skills under `skills/`. Each has one canonical copy and
+frontmatter with only `name` and `description`.
+
+| Skill | For | Use |
+| --- | --- | --- |
+| `pi-session-implementation` | A Pi worker | One bounded implementation task and a fixed final report. Register it as `builtin:pi-session-implementation` and select it on coding profiles. |
+| `pi-session-review` | A Pi worker | A review of a fixed target with findings and evidence. Register it as `builtin:pi-session-review` and select it on read-only profiles. |
+| `pi-session-orchestration` | The controlling Claude Code or Codex agent | How to run Pi worker sessions through this server. `setup --apply` installs it into the clients. It is not a Pi worker skill: do not select it in a profile. |
+
+A package update can change the shipped skills. Close affected sessions before
+you update, as for any skill change.
+
+## Customize and add skills
+
+Do not edit the files inside the installed package: an update replaces them.
+Put your version in the override directory.
+
+### Customize a shipped skill
+
+```bash
+export PI_SESSION_MCP_CONFIG="$HOME/.config/pi-session-mcp/pi-session-mcp.json"
+pi-session-mcp-setup --customize-skill pi-session-review            # dry-run
+pi-session-mcp-setup --apply --customize-skill pi-session-review
+```
+
+The dry-run reports what would happen, for example:
+
+```text
+dry-run: planned
+skills/override/pi-session-review: planned (skill_customize_planned)
+```
+
+`--apply` copies the shipped skill directory into the override directory as a
+starting point and records the fingerprint of the shipped skill in
+`<override dir>/.pi-session-mcp-bases.json`. Then edit
+`<override dir>/pi-session-review/SKILL.md`, restart the server so that the new
+override is picked up, and start new sessions.
+
+- The command works without `--target`; it touches no client. It cannot be
+  combined with `--target`, `--verify`, `--rollback` or `--remove`, which are
+  usage errors (exit 64).
+- It requires `PI_SESSION_MCP_CONFIG` (otherwise `config_required`) and the
+  same platform as the rest of `setup`: Linux or macOS, otherwise
+  `platform_unsupported`. It takes no ownership lock.
+- It never overwrites an existing override and never edits your files.
+- Only regular files are copied: at most 32 files, 1 MiB and 8 directory
+  levels, no links, and entries whose name starts with `.` are skipped.
+
+The finding target is `{ client: "skills", scope: "override", alias: <name> }`:
+
+| Code | Status | Meaning |
+| --- | --- | --- |
+| `skill_customize_planned` | planned | Dry-run: no override exists; `--apply` would copy the shipped skill. |
+| `skill_customized` | ok | The override was created and its base recorded. |
+| `skill_override_current` | unchanged | The override exists and its recorded base equals the current shipped skill. |
+| `skill_override_outdated` | planned | The shipped skill changed since the copy, or no base is recorded for the existing override. |
+| `skill_base_updated` | ok | `--apply` after `skill_override_outdated`: only the recorded base moved. |
+| `skill_not_shipped` | failed | The name is not valid or the package ships no such skill. |
+| `skill_bases_corrupt` | failed | The bases file is not valid. Repair or remove it. |
+| `skill_override_invalid` | failed | The override entry is not a directory, or its tree is unusable (no `SKILL.md`, a link, too large). |
+| `skill_customize_failed` | failed | Any other failure while copying or recording. |
+
+### Follow a changed shipped skill
+
+After a package update, `skill_override_outdated` (from the command above, or
+as a [Doctor](#doctor-boundary) warning) means that the shipped skill differs
+from the one your override was copied from. Review the shipped text, merge what
+you want into your override by hand, and then acknowledge it:
+
+```bash
+pi-session-mcp-setup --apply --customize-skill pi-session-review
+```
+
+That moves only the recorded base (`skill_base_updated`). It never touches your
+files. The override keeps winning until you delete it; the base only decides
+whether Doctor warns.
+
+### Add a new skill
+
+No command is needed. Create `<override dir>/<new-name>/SKILL.md` (a valid
+Agent Skills file with `name` and `description` frontmatter), reference it as
+`builtin:<new-name>` in `skillCatalog`, select its alias in a profile, and
+restart the server. Companion files belong in the same directory. A name that
+equals a shipped skill replaces that skill instead of adding one.
+
+Where `setup` is unsupported, create an override by copying a shipped skill
+directory by hand. Doctor does not track a copy that has no recorded base.
+
+## Install the orchestration skill into Codex and Claude Code
+
+The orchestration skill is for the controlling agent, not for a Pi worker.
+`pi-session-mcp-setup --apply --target <target>` installs it after the
+registration, as a real copy of the effective skill: your override if you have
+one, else the shipped skill. Clients discover it without further steps.
+
+| Target | Skill directory |
+| --- | --- |
+| `codex:user:pi-session-mcp` | `~/.agents/skills/pi-session-orchestration` |
+| `claude-code:user:pi-session-mcp` and `claude-code:local:pi-session-mcp` | `~/.claude/skills/pi-session-orchestration` (one shared directory) |
+| `claude-code:project:pi-session-mcp` | `<project>/.claude/skills/pi-session-orchestration`, where `<project>` is the directory in which `setup` runs |
+
+Claude Code reads personal skills in `~/.claude/skills/<name>/SKILL.md` and
+project skills in `.claude/skills/<name>/SKILL.md`
+([Claude Code skills](https://code.claude.com/docs/en/skills)). Codex reads user
+skills in `~/.agents/skills`
+([Codex skills](https://learn.chatgpt.com/docs/build-skills)).
+
+Every `setup` result has a second finding per target, with the same client and
+scope and the alias `pi-session-orchestration`. A skill problem never blocks
+the registration, but a `divergent` or `failed` skill finding makes the overall
+status `failed` (exit 1), so it is not overlooked.
+
+| Operation | Code (status) |
+| --- | --- |
+| `--dry-run` | `skill_absent` (absent), `skill_equivalent` (unchanged), `skill_linked` (unchanged), `skill_update_planned` (planned), `skill_divergent` (divergent), `skill_source_invalid` (failed) |
+| `--apply` | `skill_installed` (ok), `skill_already_equivalent` (unchanged), `skill_linked` (unchanged), `skill_updated` (ok), `skill_divergent` (divergent), `skill_source_invalid` (failed), `skill_install_failed` (failed) |
+| `--verify` | `skill_verified` (ok), `skill_missing` (failed), `skill_not_equivalent` (failed) |
+| `--rollback`, `--remove` | `skill_removed` (ok), `skill_kept_shared` (unchanged), `skill_not_owned` (unchanged), `skill_absent` (ok), `skill_divergent` (divergent) |
+
+- `--apply` installs the skill only when the registration finding is `ok` or
+  `unchanged`; `--rollback` and `--remove` handle it only after the
+  registration was removed.
+- `skill_updated` means that setup replaced its own unmodified copy after a
+  package update or a changed override.
+- `skill_kept_shared` means that the other Claude Code registration (`user` or
+  `local`) still uses the shared directory. The last one removes the skill.
+- A copy that already equals the effective skill but was not created by `setup`
+  is reported as equivalent and stays unowned; a later `--remove` reports
+  `skill_not_owned`.
+- `--verify` compares the installed copy with the effective skill and does not
+  look at ownership.
+
+### What setup never replaces or deletes
+
+Setup reports `skill_divergent` and leaves the entry alone when it finds:
+
+- an installed copy that was modified after setup wrote it;
+- a skill of the same name that setup did not install and that differs from the
+  effective skill;
+- any entry whose name starts with `.` inside an installed copy, such as your
+  own notes or a `.DS_Store` that macOS Finder adds: setup never writes such
+  entries, so it treats them as yours; delete them to let setup manage the copy
+  again;
+- a link at the skill entry that points anywhere but the effective skill, or a
+  non-directory there.
+
+A link at the skill entry that points exactly at the effective skill (your
+override, else the shipped skill) is your own equivalent setup: setup reports
+`skill_linked` (unchanged), `--verify` reports `skill_verified`, and removal
+leaves the link alone (`skill_not_owned`). If you replace setup's own copy with
+such a link, setup forgets its copy on the next `--apply` or `--remove`. A link
+counts only while the effective skill itself is valid.
+
+If an update is interrupted, for example by a full disk or a signal, setup still
+recognizes the old copy as its own: the next `--apply` finishes the update and
+`--remove` deletes it. A project copy belongs to its project: setup records an
+opaque project identity, so a `--remove` in another project never deletes it.
+
+Links in the path to the entry are handled by place. In your home directory,
+the client's skill directory may be your own link, for example into a dotfiles
+checkout, and is followed. Inside a project, which may be untrusted, any link
+below the project root makes the entry divergent, so setup never writes outside
+the project.
+
+### Customize the controller skill
+
+Never edit the installed copy: it becomes divergent. Instead:
+
+1. `pi-session-mcp-setup --apply --customize-skill pi-session-orchestration`
+2. Edit `<override dir>/pi-session-orchestration/SKILL.md`.
+3. `pi-session-mcp-setup --apply --target <target>` again. The unmodified
+   installed copy is replaced (`skill_updated`).
+
+To recover after editing the installed copy, move your edits into the override,
+delete the installed copy, and run `--apply` again.
+
+### Scope of what setup installs
+
+Setup installs only `pi-session-orchestration` into clients. The worker skills
+are for Pi profiles and are used through `builtin:`. Controller skills of your
+own belong in the clients' native skill directories; setup does not manage
+them.
+
+### Install by hand where setup is unsupported
+
+Where `setup` does not run, copy the directory; do not link it. Copy
+`skills/pi-session-orchestration` from the installed package (in an npm
+installation `"$(npm root -g)/pi-session-mcp/skills/pi-session-orchestration"`)
+to `~/.claude/skills/` or `.claude/skills/` of a project for Claude Code, or to
+`~/.agents/skills/` for Codex. Repeat the copy after a package update; nothing
+keeps a manual copy current. Do not replace an existing skill of the same name
+without checking it first.
+
+Neither client needs a skill to call the Pi Session MCP tools; the skill only
+describes the working method. Headless `codex exec` runs still need the
+per-tool approvals for `pi_session_prompt`, `pi_session_abort` and
+`pi_session_close` that [client
+setup](client-setup.md#run-codex-without-prompts) describes.
+
+### Pi workers
+
+Pi workers never discover skills on their own in Pi Session MCP. Register the
+worker skills with `builtin:` and select them on profiles, as described above.
+Do not select the orchestration skill for a Pi worker: a worker has only the
+tools of its profile and is not a controller of other Pi sessions.
+
+## What happens at session start
+
+The server loads exactly the selected files through the Pi SDK's public
+`loadSkills`, without any default directories, and validates them completely.
+The SDK's skill override returns exactly that set, also after an extension adds
+resources later (`resources_discover`). A profile without skills gets no
+skills, whatever is installed on the machine or shipped by an extension.
+
+The start fails with `skill_load_failed` (message `Configured Pi skill could
+not be loaded`) if:
+
+- a selected file is missing, unreadable, or larger than 256 KiB (also a
+  `builtin:` value that resolved to no skill);
+- the SDK reports the skill as invalid, for example a missing description or an
+  invalid name;
+- two selected files declare the same Pi skill name;
+- two aliases point at the same canonical file, for example through a symlink;
+- the skill sets `disable-model-invocation: true`.
+
+The message is fixed. It never contains a path, a skill name or SDK text.
+Stderr gets a structured diagnostic. A selected file that fails validation
+reports the stage `skill_load` and, when one alias is to blame, that catalog
+alias in a `skill` field. If the session's actual skill catalog differs from
+the selection after construction, the stage is `postcheck`, or
+`extension_load` and `extension_bind` for a profile with extensions. Neither
+carries a path.
+
+If the session's prompt-template or theme catalog is not empty after
+construction, which the overrides should prevent, the start fails with
+`pi_session_creation_failed`.
+
+Explicit-only skills (`disable-model-invocation: true`) are incompatible in
+this version. Pi hides such skills from the model, and MCP prompts never run
+`/skill:` commands, so the skill could never be used. The server does not
+rewrite the flag. The same Pi skill name in different sessions is fine.
+
+## Doctor boundary
+
+Doctor stays offline and never parses or executes a skill. For each profile and
+selected alias it adds three checks after the extension checks, with the
+subject `<profile>:<skill-alias>`. A `builtin:` alias is checked at the
+location it resolved to:
+
+| ID | Condition |
+| --- | --- |
+| `skill_missing` | The selected file does not exist. |
+| `skill_unreadable` | The path is not a regular file, is over 256 KiB, or cannot be read. |
+| `skill_duplicate` | Two selected aliases of one profile resolve to the same canonical file. |
+
+Frontmatter, name rules, name collisions and the explicit-only flag are checked
+only at session start by the SDK contract. A clean Doctor run therefore does
+not promise that the skill loads.
+
+A fourth check concerns overrides, not profiles:
+
+| ID | Severity | Subject | Condition |
+| --- | --- | --- | --- |
+| `skill_override_outdated` | warning | `skill:<name>` | The shipped skill's current fingerprint differs from the base recorded in `<override dir>/.pi-session-mcp-bases.json`. |
+| `skill_override_outdated` | warning | `skill:bases` | The bases file is corrupt. |
+
+It is `ok` for a recorded base that still matches. The remediation for a
+changed skill names the command
+`pi-session-mcp-setup --apply --customize-skill <name>`, after you reviewed the
+change (see [Follow a changed shipped skill](#follow-a-changed-shipped-skill)).
+Only skills with a recorded base are compared. Doctor reads the bases file and
+the shipped files and executes nothing. A warning gives exit status `1`; it does
+not block `setup`.
+
+## Three states, and a fourth thing
+
+Keep these apart:
+
+1. **Configured.** `pi_capabilities_get` lists the alias under the profile's
+   `skills`. This is configuration intent only. It says nothing about the file.
+2. **Available in the SDK catalog.** The skill passed validation at session
+   start and Pi lists it to the model in the system prompt.
+3. **Actually read by the model.** The model decides to read the `SKILL.md`
+   with its `read` tool. This is not guaranteed.
+
+Task success is separate from all three. A skill that the model read can still
+produce a bad result, and a task can succeed without the skill.
+
+## Snapshot semantics
+
+The profile and its skill selection are fixed per session. The skill content
+is not snapshotted: the SDK keeps file paths, and the model's later reads may
+see changed files. This also applies to companion files that a skill refers
+to.
+
+- Manage skill files and companion files as operator content. Do not change
+  them while sessions that use them are active.
+- Close the affected sessions before an update. New sessions then load the new
+  content.
+- The configuration fingerprint covers the configuration bytes, not skill
+  contents.
+- There is no hot reload, no watcher, no copy store for sessions and no
+  versioning. A change
+  to `skillCatalog` or `skills` needs a new server process like any other
+  configuration change. So does adding or removing an override of a library
+  skill, because `builtin:` is resolved when the configuration loads. Editing
+  the file of an override that already resolves needs no restart for new
+  sessions.
+
+## Trust and limits
+
+Skills are operator-managed prompt content. The override directory and its
+bases file are operator-trusted configuration next to the configuration file,
+never a workspace; keep them out of every workspace and writable only by you.
+Setup copies the effective orchestration skill into the clients' skill
+directories, where it becomes instructions for the controlling agent, so review
+an override like code. In a `coding` profile a skill's
+instructions are executed with that profile's tools, so review a skill like
+code. A skill grants no rights: the tools of the permission profile stay the
+limit.
+
+Skill selection limits the regular skill catalog only. An allowlisted
+extension remains trusted executable code. It can still read files or inject
+prompt text. This is not a sandbox.
+
+No MCP tool and no tool argument takes a skill. `pi_session_start` and
+`pi_session_prompt` are unchanged.
+
+Pi lists each available skill to the model with the absolute path of its
+`SKILL.md`, so that the model can read it. The model may repeat that path in
+its answer. Capabilities, errors and diagnostics stay path-free, but completed
+`assistantText` is model output and is not sanitized.
+
+## Migration: profiles that relied on package skills
+
+With Pi SDK 1.1.0, an allowlisted extension package's bundled skills reached
+the session although `noSkills` was set. The same held for prompt
+templates and themes that a package shipped. Now an extension allowlist alone
+makes none of its skills available. Prompt templates and themes that packages
+ship are closed as well, through the SDK's public overrides. They were never
+expanded for MCP prompts. Profiles without extensions are not affected.
+
+If a profile used a skill that a package shipped:
+
+1. Find the package's `SKILL.md` inside Pi's install, normally
+   `<Pi agent dir>/npm/node_modules/<package>/…`.
+2. Add a catalog entry with the absolute path of that file. `~` is not
+   expanded.
+3. Select the alias in the profile's `skills`.
+4. Run Doctor and start a session to confirm.
+
+Keep in mind that a package update can move or change the file. The catalog
+path then needs a check.

package/docs/threat-model.md

@@ -26,6 +26,14 @@ Pi Session MCP trusts the local process that launches and speaks MCP over inheri
   `process.execPath`, `dist/`, and `PI_SESSION_MCP_CONFIG`; no arbitrary `cwd` is
   accepted. Durable pending/owned ownership state contains neither paths nor
   secrets.
+- **Skill installation into clients:** `setup --apply` writes the controller skill `pi-session-orchestration` into the clients' skill directories, in the home directory (`~/.agents/skills`, `~/.claude/skills`) and, for Claude Code `project`, in the project that setup runs in (`<project>/.claude/skills`). What is written there becomes instructions for the controlling agent, so the copy is as trusted as the package or the override it comes from. Mitigations:
+  - Copies come only from the package's `skills/` directory or from the operator's override directory next to the configuration file. No tool argument, client prompt or workspace names a source.
+  - The override directory and its `.pi-session-mcp-bases.json` are operator-trusted configuration next to the configuration file, never a workspace. Keep them out of every workspace and writable only by the operator; a `coding` session that can write there could change what setup installs next.
+  - Setup reads a bounded tree of regular files (at most 32 files and 1 MiB, no links or special files) and installs it as a real copy, never as a link. The copy is staged and renamed into place; only the exact old tree that setup itself moved is deleted afterwards.
+  - Setup never replaces or deletes a modified installed copy, hidden operator entries inside it, a foreign skill of the same name or a linked or non-directory entry; it reports `skill_divergent`. A link to exactly the effective skill is accepted as the operator's own (`skill_linked`) and never written through or deleted. Ownership records hold a content fingerprint (and, during an update, the replaced fingerprint), no path; a project record carries an unsalted, truncated SHA-256 of the project's real path as an opaque identity, which someone who can read the state file could test against guessed paths.
+  - A project may be untrusted. Inside a project setup never follows a link: any link below the project root makes the slot divergent, so a repository cannot redirect the write outside itself. In the home directory the client's skills directory may be the operator's own link (for example into a dotfiles checkout) and is followed; the skill entry itself is never followed.
+  - `--customize-skill` writes only below the override directory, never overwrites an existing override and never edits an operator's file. It moves the recorded base only on an explicit `--apply`, which acknowledges a reviewed change to the shipped skill.
+  - Worker skills are not installed into clients. Reports name the skill and a stable code, never a path or content.
 - **False verification:** Verify combines Doctor and exact registration
   equality with a bounded direct MCP initialize, `tools/list`, and
   `pi_capabilities_get({})` call. It never starts a session or invokes
@@ -68,7 +76,7 @@ Pi Session MCP trusts the local process that launches and speaks MCP over inheri
 - **Thinking-level clamping:** SDK capability handling can alter a requested level. The adapter compares the effective `session.thinkingLevel` after creation and disposes on a mismatch.
 - **Orphaned SDK session:** a post-creation mismatch or later registry failure could otherwise leave a live Pi handle. The adapter holds it locally until all postconditions pass, best-effort disposes on each later failure, and the registry admits only verified handles.
 - **Excess capability:** the execution profile selects a permission-derived tool allowlist. Read-only permits only `read`, `grep`, `find`, and `ls`; coding remains high impact.
-- **Project resource code execution:** Pi resource loading disables extension discovery, skills, prompts, and themes; only a profile's allowlisted extensions load (see below). Non-executable `AGENTS.md` context remains untrusted instruction content, never authorization.
+- **Project resource code execution:** Pi resource loading disables extension discovery, default skill directories, prompts, and themes; only a profile's allowlisted extensions and its explicitly selected catalog skills load (see below). A skill, prompt template or theme that an extension package ships is not made available by the allowlist. Non-executable `AGENTS.md` context remains untrusted instruction content, never authorization.
 - **Concurrent state corruption:** a per-session queue serializes prompt admission and close; concurrent abort callers share one attempt for the active turn. Closing is terminal, settles an active turn, and disposes once.
 - **Secret/prompt disclosure:** stdout is protocol-only. Stderr diagnostics use stable code and safe context only. Public metadata is whitelisted and omits auth objects/sources, credential paths, headers, base URLs, complete model objects, SDK IDs, raw provider errors, prompts, transcripts, and tool data. Completed `assistantText` can still repeat model-visible data and is potentially sensitive.
 - **Capability-enumeration disclosure:** the trusted local MCP peer can read configured workspace aliases and execution-profile provider/model intent. Discovery omits workspace paths, authentication state, SDK state, sessions, turns, prompts, transcripts, and tool data. Operators must choose aliases that are suitable for this trusted-peer boundary.
@@ -80,6 +88,15 @@ Pi Session MCP trusts the local process that launches and speaks MCP over inheri
   - `read-only` profiles never activate extension tools. At session start, after load and again after binding, no extension tool may shadow a built-in or granted tool; later registrations are covered in the residual risks.
   - Client prompts never dispatch extension commands, but extension input hooks can still see, rewrite or consume a prompt. They receive it with `source: "rpc"`, Pi's marker for input from a program, so a hook that reads the source sees that no human typed it. A hook that ignores the source treats it like any other input.
   - Each extension session gets its own model runtime, and close emits `session_shutdown`.
+- **Skills as prompt content:** a profile's `skills` select files from the operator's `skillCatalog`. The MCP client cannot name a skill, a path or a catalog entry; `pi_session_start` and `pi_session_prompt` take no skill input. Mitigations:
+  - Catalog values are single local `SKILL.md` files: no directories, globs, URLs, scheme-prefixed sources, `~` or backslashes. The one accepted scheme is `builtin:<name>`, which resolves to the operator's override next to the configuration file or else to the skill shipped in the package, and to no other place. Relative paths resolve against the configuration file's directory, never against a workspace.
+  - The server loads exactly the selected files with no default directories, validates them at session start and rejects oversized (over 256 KiB), duplicate, invalid and explicit-only skills with `skill_load_failed`. Its message and diagnostics never contain a path, skill name or SDK text.
+  - Selection limits the regular skill catalog only. An allowlisted extension stays trusted executable code and can still read files or inject prompt text.
+  - Skills are operator-managed prompt content. In `coding` profiles a skill's instructions run with the profile's tools, so a skill grants no rights but can direct everything the profile may do. Review skills like code.
+  - Content is not snapshotted: the SDK keeps file paths, so a changed skill or companion file can reach a running session. Operators must not change them during active sessions. The configuration fingerprint covers configuration bytes, not skill contents.
+  - A `coding` session can write any file in its workspace, including a catalog file that lies inside it, and so change the instructions of other sessions and profiles. Operators keep catalog files outside every configured workspace; nothing enforces this.
+  - Whether the model reads a listed skill is the model's decision; configured, available and actually read are different states.
+  - Pi lists each available skill to the model with the absolute path of its `SKILL.md`, so the model knows that path and can repeat it in `assistantText`. Capabilities, errors and diagnostics stay path-free; completed `assistantText` is model output and not sanitized.
 - **stdout corruption:** every write through `process.stdout` or `console.log`, `console.info` and `console.debug` other than the MCP transport's is dropped. The stdout guard intercepts `process.stdout.write`, `process.stdout.end` and `console.log`, `console.info` and `console.debug`, which covers output from extensions and the SDK in the server process. stderr gets only `foreign_stdout_suppressed` with byte and write counts, never the content. Anything that writes file descriptor 1 directly is not covered; see the residual risks.
 - **Misleading annotations:** annotations are client hints only and never grant access.
 - **Shutdown orphaning:** `SIGINT`, `SIGTERM`, and stdin EOF invoke the same bounded registry cleanup and transport close, so a client that only closes stdin does not leave sessions or their MCP children running. Handles are disposed at most once; late promises are ignored after removal. Explicit process exit prevents local shutdown from hanging indefinitely, but SDK limitations can leave external work unconfirmed or abruptly cut off.
@@ -104,7 +121,7 @@ sanitizing catch. A foreign transport exception with identical text remains
 generic. This does not raise the limit, permit additional remote error codes or
 change public terminal errors; cancellation and close still take precedence.
 
-Aliases and profile definitions are trusted administrator configuration, not a filesystem or provider-security sandbox. A locally available model may later be unreachable; no live provider request is made during selection. Symlinks and Pi tools can reach resources permitted to the OS identity. `AGENTS.md` can influence model behavior. The number of active sessions and the duration of an already accepted turn remain unbounded. Stdio peer authentication, quotas, persistent recovery, provider hard-kill capability, dependency integrity policy, and OS/filesystem isolation remain outside the verified boundary. Coding-profile acceptance checks behavior in a selected fixture; it does not prove OS-level isolation.
+Aliases, profile definitions, skill catalog entries and the skill override directory are trusted administrator configuration, not a filesystem or provider-security sandbox. A locally available model may later be unreachable; no live provider request is made during selection. Symlinks and Pi tools can reach resources permitted to the OS identity. `AGENTS.md` can influence model behavior. The number of active sessions and the duration of an already accepted turn remain unbounded. Stdio peer authentication, quotas, persistent recovery, provider hard-kill capability, dependency integrity policy, and OS/filesystem isolation remain outside the verified boundary. Coding-profile acceptance checks behavior in a selected fixture; it does not prove OS-level isolation.
 The trusted same-UID operator can unlink or replace the setup lock path between
 checks and must not mutate the ownership directory during a transaction.
 

package/docs/tool-contracts.md

@@ -22,7 +22,7 @@ There are exactly eight tools. No `pi_turn_wait` tool or live provider/model inv
 ```json
 {
   "ok": true,
-  "server": { "name": "pi-session-mcp", "version": "0.7.1" },
+  "server": { "name": "pi-session-mcp", "version": "0.8.0" },
   "configuration": {
     "fingerprint": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
     "reloadPolicy": "restart-required"
@@ -35,12 +35,13 @@ There are exactly eight tools. No `pi_turn_wait` tool or live provider/model inv
     "provider": "configured-provider",
     "model": "configured-model",
     "thinkingLevel": "medium",
-    "extensions": []
+    "extensions": [],
+    "skills": []
   }]
 }
 ```
 
-The server sorts both arrays by alias with a deterministic code-point comparison. It copies only loaded configuration fingerprint/reload policy, configured aliases, and the seven documented profile fields. `extensions` lists the configured extension specs (`npm:<name>@<version>`), empty when a profile loads none; it makes no claim that the package is installed. It never copies the configuration path or contents, workspace paths, authentication state, SDK data, session/turn data, prompts, transcripts, or tool arguments/results. The handler reads the in-memory loaded snapshot only and does not call the registry, Pi adapter, provider, filesystem, or network. The fingerprint identifies the exact loaded bytes, not current-file freshness; provider/model fields describe configured intent and make no availability claim.
+The server sorts both arrays by alias with a deterministic code-point comparison. It copies only loaded configuration fingerprint/reload policy, configured aliases, and the eight documented profile fields. `extensions` lists the configured extension specs (`npm:<name>@<version>`), empty when a profile loads none; it makes no claim that the package is installed. `skills` lists the skill-catalog aliases that the profile selects, in configured order, `[]` when it selects none. It contains no paths, file names, contents or SDK diagnostics, and it is configuration intent only: it makes no claim that a skill file exists, loads, or will be read by the model. See [Pi skills](skills.md). It never copies the configuration path or contents, workspace paths, authentication state, SDK data, session/turn data, prompts, transcripts, or tool arguments/results. The handler reads the in-memory loaded snapshot only and does not call the registry, Pi adapter, provider, filesystem, or network. The fingerprint identifies the exact loaded bytes, not current-file freshness; provider/model fields describe configured intent and make no availability claim.
 
 Annotations are `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, and `openWorldHint: false`. Clients may use them for presentation, but the strict input schema and server-owned projection enforce the contract.
 
@@ -52,6 +53,8 @@ The former `profile` input is rejected; it is not reinterpreted as an execution-
 
 Successful session metadata is a whitelist: `id`, `workspace`, `executionProfile`, `profile`, `provider`, `model`, `thinkingLevel`, `state`, `createdAt`, and `updatedAt`. `profile` remains derived permission metadata (`read-only` or `coding`) for compatibility; it is not client-selectable. Provider, model, and thinking level are projected only after SDK post-verification.
 
+The selected skills of an execution profile are never an input. A session loads exactly the skills that the profile selects from the operator's skill catalog, validated at start; a failure is `skill_load_failed`. A catalog value is the path of one `SKILL.md` or `builtin:<name>`, which names a skill of the skill library: the operator's override next to the configuration file if it exists, else the skill shipped in the package. It is resolved when the server loads the configuration, and the value never appears in tool output. See [Pi skills](skills.md).
+
 ## Deterministic MCP errors
 
 Public MCP errors are stable and sanitized. Their messages do not include inputs, auth details, provider responses, filesystem paths, or secrets.
@@ -72,6 +75,7 @@ Public MCP errors are stable and sanitized. Their messages do not include inputs
 | `extension_version_mismatch` | Pi's installed extension package has another version than the configured one. |
 | `extension_load_failed` | A configured extension has an invalid manifest, failed to load or failed to bind. |
 | `extension_tool_conflict` | An extension tool name collides with a built-in, MCP or other extension tool, or is unsafe: not 1 to 64 letters, digits, `_` or `-` (not starting with `-`), or reserved for MCP (`mcp__` prefix, `list_mcp_resources`, `list_mcp_resource_templates`, `read_mcp_resource`). |
+| `skill_load_failed` | A skill that the profile selects could not be loaded: a missing (also a `builtin:` name that matches no override and no shipped skill), unreadable or oversized (over 256 KiB) file, an invalid skill, two selected files with the same Pi skill name, two aliases on the same canonical file, or a skill with `disable-model-invocation: true`. The message is the fixed `Configured Pi skill could not be loaded`; it never contains a path, skill name or SDK text. |
 | `pi_session_creation_failed` | Pi session construction failed without a more specific safe classification. |
 | `server_stopping` | Shutdown has begun, so a new session cannot be admitted. |
 
@@ -81,7 +85,7 @@ Invalid execution-profile configuration prevents startup, so it cannot be an MCP
 
 | Startup diagnostic code | Meaning |
 | --- | --- |
-| `invalid_execution_profile_config` | The execution-profile configuration violates its invariants or strict shape. |
+| `invalid_execution_profile_config` | The execution-profile configuration violates its invariants or strict shape, including an unknown or duplicate selected skill alias, two selected skill aliases with the same path, or an invalid `skillCatalog` entry (including a malformed `builtin:` name). |
 | `invalid_thinking_level` | A configured thinking level is outside the supported enum. |
 
 `pi_session_prompt` returns `{session,turn}` only after successful Pi preflight. Preflight is bounded at 5,000 ms; a missing callback, hanging prompt acceptance, or timeout returns `prompt_timeout` / `Pi prompt preflight timed out` and creates no public turn. Late settlement may only release the unpublished operation's quarantine; it cannot publish a turn. `pi_session_abort` waits at most 5,000 ms per caller for one shared SDK abort attempt and returns `abort_timeout` / `Pi abort timed out` without claiming the turn was aborted. Rejection/failure remain `prompt_rejected`/`abort_failed`. Close allows at most 5,000 ms for abort cleanup, then performs best-effort disposal and removes the public registry entry; it remains idempotent through the retained tombstone. Registry shutdown rejects new starts, allows 12,000 ms, and disposes a handle from a late-resolving start instead of admitting it. Process shutdown, started by `SIGINT`, `SIGTERM`, or stdin EOF, allows 15,000 ms, attempts transport cleanup even after registry failure/timeout, then explicitly exits the process. These boundaries do not guarantee graceful cancellation of a provider request. `pi_turn_get` returns a `TurnView` with `turnId`, `sessionId`, state, timestamps, and `completedAt` for terminal turns. Completed views add normalized final `assistantText` and `truncated`; failed views contain only `{code:"turn_failed",message:"Pi turn failed"}`. Final assistant text is capped at 64 KiB UTF-8 bytes, each active session retains at most 20 turns, and close removes its turn data.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-session-mcp",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Local stdio MCP server for controlled Pi coding-agent sessions",
   "license": "MIT",
   "keywords": [
@@ -29,6 +29,7 @@
     ".pi-session-mcp-cli/",
     "scripts/doctor.mjs",
     "pi-session-mcp.example.json",
+    "skills/",
     "docs/",
     "!docs/superpowers/",
     "CHANGELOG.md",

package/pi-session-mcp.example.json

@@ -1,6 +1,10 @@
 {
   "workspaces": {
-    "project": "."
+    "project": "/absolute/path/to/project"
+  },
+  "skillCatalog": {
+    "pi-session-implementation": "builtin:pi-session-implementation",
+    "pi-session-review": "builtin:pi-session-review"
   },
   "executionProfiles": {
     "safe-readonly": {
@@ -8,14 +12,16 @@
       "permissionProfile": "read-only",
       "provider": "example-provider",
       "model": "example-model",
-      "thinkingLevel": "medium"
+      "thinkingLevel": "medium",
+      "skills": ["pi-session-review"]
     },
     "coding-example": {
       "default": false,
       "permissionProfile": "coding",
       "provider": "another-example-provider",
       "model": "another-example-model",
-      "thinkingLevel": "high"
+      "thinkingLevel": "high",
+      "skills": ["pi-session-implementation"]
     }
   }
 }