pi-ui-extend 0.1.39 → 0.1.41

package/dist/app/app.js

@@ -666,6 +666,12 @@ export class PiUiExtendApp {
             setSessionActivity: (activity) => this.setSessionActivity(activity),
             addEntry: (entry) => this.addEntry(entry),
             addSessionAbortedEntry: () => this.sessionEvents.addSessionAbortedEntry(),
+            emitSessionAborted: () => {
+                const runtime = this.runtime;
+                if (!runtime)
+                    return;
+                this.extensionEventBusByRuntime.get(runtime)?.emit("pix:session-aborted", { aborted: true });
+            },
             showToast: (message, kind) => this.showToast(message, kind),
             dismissActiveDialog: () => this.toastController.dismissActiveDialog(),
             stopVoiceInput: () => this.voiceController.stopRecording(),

package/dist/app/constants.js

@@ -78,7 +78,7 @@ export const SUBAGENTS_WIDGET_MAX_ROWS = 8;
 export const DEFAULT_THINKING_TOOL_RULE = {
     previewLines: 0,
     direction: "head",
-    color: "thinkingForeground",
+    color: "assistantForeground",
 };
 export const TERMINAL_COMMAND_MODIFIER_FLAG = 8;
 export const GIT_BRANCH_CACHE_MS = 30_000;

package/dist/app/input/input-action-controller.d.ts

@@ -18,6 +18,7 @@ export type AppInputActionControllerHost = {
     setSessionActivity(activity: SessionActivity): void;
     addEntry(entry: Entry): void;
     addSessionAbortedEntry(): void;
+    emitSessionAborted(): void;
     showToast(message: string, kind: "success" | "error" | "warning" | "info"): void;
     dismissActiveDialog?(): boolean;
     stopVoiceInput(): Promise<void>;

package/dist/app/input/input-action-controller.js

@@ -88,6 +88,9 @@ export class AppInputActionController {
     }
     async abortStreamingSession(runtime, options) {
         const session = runtime.session;
+        // Relay the user-initiated abort to extensions (e.g. the terminal-bell
+        // extension) so they can suppress the attention bell for this turn.
+        this.host.emitSessionAborted();
         if (this.abortInFlight) {
             session.agent.abort();
             if (options.stopIfAlreadyAborting)

package/dist/app/process.js

@@ -37,6 +37,17 @@ export async function runProcess(command, args = [], options = {}) {
         child.once("error", (err) => {
             error = err;
         });
+        // Writing to stdin after the child has closed it raises EPIPE. This is
+        // common with clipboard helpers (xclip/xsel/wl-copy) that exit once they
+        // have read enough, or when a candidate command exits early. The child's
+        // exit status is still captured by the "close" handler, so treat EPIPE as
+        // benign and never let it surface as an unhandled "error" event.
+        child.stdin?.once("error", (err) => {
+            if (err?.code === "EPIPE")
+                return;
+            if (error === undefined)
+                error = err;
+        });
         child.once("close", (status, signal) => {
             if (timer)
                 clearTimeout(timer);

package/dist/app/rendering/conversation-tool-renderer.js

@@ -7,7 +7,6 @@ import { formatStructuredText } from "./message-content.js";
 import { formatSubagentTimestamp, isSubagentRunRenderDetails, isSubagentsToolName, subagentRunName, subagentStatusIcon, taskPreviewMap, } from "../subagents/subagents-model.js";
 import { formatTodoTaskLine, isTodoDetails, visibleTodoTasks } from "../todo/todo-model.js";
 import { renderToolBlock } from "./tool-block-renderer.js";
-import { thinkingLevelThemeColor } from "./status-line-renderer.js";
 export function renderConversationToolEntry(entry, width, options) {
     const todoLines = renderTodoToolEntry(entry, width, options);
     if (todoLines)
@@ -53,14 +52,14 @@ export function renderThinkingEntry(entry, width, options) {
     const forceExpanded = Boolean(options.allThinkingExpanded);
     const compactExpandedText = options.superCompactTools && forceExpanded ? removeBlankLines(expandedText) : expandedText;
     const expanded = forceExpanded || (entry.expanded && expandedText.trim().length > 0);
-    const headerColorOverride = entry.level
-        ? thinkingLevelThemeColor(entry.level, options.colors, options.availableThinkingLevels)
-        : undefined;
     const elapsed = thinkingElapsedText(entry, options.currentTimeMs ?? Date.now());
+    const headerArgs = [entry.level ? `(${entry.level})` : undefined, elapsed]
+        .filter((part) => part !== undefined)
+        .join(" ");
     return renderToolBlock({
         id: entry.id,
         toolName: THINKING_TOOL_NAME,
-        ...(elapsed === undefined ? {} : { headerArgs: elapsed }),
+        ...(headerArgs === "" ? {} : { headerArgs }),
         expanded,
         status: entry.status,
         isError: false,
@@ -73,7 +72,6 @@ export function renderThinkingEntry(entry, width, options) {
         superCompact: Boolean(options.superCompactTools && !forceExpanded),
         backgroundOverride: options.colors.thinkingMessageBackground,
         showGutter: true,
-        ...(headerColorOverride === undefined ? {} : { headerColorOverride }),
     });
 }
 function thinkingElapsedText(entry, currentTimeMs) {

package/dist/bundled-extensions/terminal-bell/index.js

@@ -15,6 +15,13 @@ const TERMINAL_BELL_ATTENTION_EVENT = "pix:terminal-bell:attention";
  * extensions, so the renderer emits this on the extension event bus.
  */
 const RETRY_ACTIVE_EVENT = "pix:retry-active";
+/**
+ * Renderer-relayed signal that the user interrupted the session (Esc/Ctrl-C).
+ * Payload: `{ aborted: boolean }`. Aborting the SDK stream during tool
+ * execution does not always produce an aborted `message_update`, so the
+ * renderer relays the abort here to reliably suppress the attention bell.
+ */
+const SESSION_ABORTED_EVENT = "pix:session-aborted";
 const DEFAULT_COMPLETION_NOTIFICATION_TITLE = "Pix - complete";
 const DEFAULT_ERROR_NOTIFICATION_TITLE = "Pix - error";
 const DEFAULT_QUESTION_NOTIFICATION_TITLE = "Pix - question";
@@ -220,9 +227,16 @@ function notificationTitleTemplate(defaultTitle) {
 function willRetryAfterAgentEnd(event) {
     return event.willRetry === true;
 }
+function isAbortedMessageUpdate(event) {
+    return event.type === "error" && event.reason === "aborted";
+}
 function failureReasonFromMessageUpdate(event) {
     if (event.type !== "error")
         return undefined;
+    // The SDK reports a user-initiated interrupt as `{ type: "error", reason: "aborted" }`.
+    // That is not a failure the bell should announce, so treat it as "no reason".
+    if (event.reason === "aborted")
+        return undefined;
     const reason = event.error?.errorMessage;
     return typeof reason === "string" ? trimmed(reason) : undefined;
 }
@@ -387,6 +401,10 @@ export default function terminalBell(pi) {
     let deferredUntilSubagentsFinish = false;
     let liveSubagentCount = 0;
     let lastFailureReason;
+    // True when the user interrupted the session this turn (Esc/Ctrl-C). The
+    // attention bell should never ring for a user-initiated abort, so this flag
+    // suppresses any queued/pending bell until the next agent_start resets it.
+    let userAborted = false;
     // True while the session is in an auto-retry cycle (relayed via the
     // extension event bus). Suppresses the failure bell on intermediate retry
     // attempts; the final exhausted failure still rings because no retry-start
@@ -426,6 +444,13 @@ export default function terminalBell(pi) {
         // queued this bell and the timer firing, suppress the bell entirely.
         if (retryActive)
             return;
+        // Safety net: if the user aborted after the bell was queued (e.g. an
+        // aborted agent_end with no aborted message_update), suppress it.
+        if (userAborted) {
+            pendingBell = undefined;
+            deferredUntilSubagentsFinish = false;
+            return;
+        }
         try {
             if (!ctx.isIdle()) {
                 if (attempt < MAX_IDLE_RETRIES)
@@ -514,15 +539,39 @@ export default function terminalBell(pi) {
             deferredUntilSubagentsFinish = false;
         }
     });
+    pi.events.on(SESSION_ABORTED_EVENT, (data) => {
+        const aborted = data != null && typeof data === "object" && data.aborted === true;
+        if (!aborted)
+            return;
+        // The user interrupted the session. Aborting during tool execution does
+        // not always produce an aborted `message_update`, so the renderer relays
+        // the interrupt here. Suppress any pending bell until the next agent_start.
+        userAborted = true;
+        lastFailureReason = undefined;
+        clearTimer();
+        pendingBell = undefined;
+        deferredUntilSubagentsFinish = false;
+    });
     pi.on("agent_start", async () => {
         clearTimer();
         deferredUntilSubagentsFinish = false;
         lastFailureReason = undefined;
+        userAborted = false;
         retryActive = false;
         activeSubagentWaitToolCallIds.clear();
         notifiedAskUserToolCallIds.clear();
     });
     pi.on("message_update", async (event) => {
+        if (isAbortedMessageUpdate(event.assistantMessageEvent)) {
+            // The user interrupted the stream. Suppress any pending bell until
+            // the next agent_start.
+            userAborted = true;
+            lastFailureReason = undefined;
+            clearTimer();
+            pendingBell = undefined;
+            deferredUntilSubagentsFinish = false;
+            return;
+        }
         const reason = failureReasonFromMessageUpdate(event.assistantMessageEvent);
         if (reason) {
             lastFailureReason = reason;
@@ -554,6 +603,10 @@ export default function terminalBell(pi) {
             clearTimer();
             return;
         }
+        if (userAborted) {
+            clearTimer();
+            return;
+        }
         if (lastFailureReason) {
             scheduleBell(ctx, idleDelayMs, 0, renderNotificationTemplate(retryFailureMessageTemplate(), {
                 ...buildNotificationTemplateValues(ctx, pi),
@@ -569,6 +622,7 @@ export default function terminalBell(pi) {
         deferredUntilSubagentsFinish = false;
         liveSubagentCount = 0;
         lastFailureReason = undefined;
+        userAborted = false;
         retryActive = false;
         activeSubagentWaitToolCallIds.clear();
         notifiedAskUserToolCallIds.clear();

package/dist/config.js

@@ -19,7 +19,7 @@ const DEFAULT_TOOL_RENDERER = {
         color: "toolTitle",
     },
     tools: {
-        thinking: { previewLines: 0, direction: "head", color: "thinkingForeground" },
+        thinking: { previewLines: 0, direction: "head", color: "assistantForeground" },
         bash: { previewLines: 6, direction: "tail", color: "warning" },
         Bash: { previewLines: 6, direction: "tail", color: "warning" },
         shell: { previewLines: 6, direction: "tail", color: "warning" },

package/dist/default-pix-config.js

@@ -10,7 +10,7 @@ export const DEFAULT_PIX_CONFIG_JSONC = String.raw `{
   "toolRenderer": {
     "default": { "previewLines": 0, "direction": "head", "color": "toolTitle" },
     "tools": {
-      "thinking": { "previewLines": 0, "direction": "head", "color": "thinkingForeground" },
+      "thinking": { "previewLines": 0, "direction": "head", "color": "assistantForeground" },
       "bash": { "previewLines": 6, "direction": "tail", "color": "warning" },
       "Bash": { "previewLines": 6, "direction": "tail", "color": "warning" },
       "shell": { "previewLines": 6, "direction": "tail", "color": "warning" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ui-extend",
-  "version": "0.1.39",
+  "version": "0.1.41",
   "private": false,
   "type": "module",
   "bin": {

package/skills/skill-creator/SKILL.md

@@ -11,7 +11,7 @@ At a high level, the process of creating a skill goes like this:
 
 - Decide what you want the skill to do and roughly how it should do it
 - Write a draft of the skill
-- Create a few test prompts and run claude-with-access-to-the-skill on them
+- Create a few test prompts and run pi-with-access-to-the-skill on them
 - Help the user evaluate the results both qualitatively and quantitatively
   - While the runs happen in the background, draft some quantitative evals if there aren't any (if there are some, you can either use as is or modify if you feel something needs to change about them). Then explain them to the user (or if they already existed, explain the ones that already exist)
   - Use the `eval-viewer/generate_review.py` script to show the user the results for them to look at, and also let them look at the quantitative metrics
@@ -31,7 +31,7 @@ Cool? Cool.
 
 ## Communicating with the user
 
-The skill creator is liable to be used by people across a wide range of familiarity with coding jargon. If you haven't heard (and how could you, it's only very recently that it started), there's a trend now where the power of Claude is inspiring plumbers to open up their terminals, parents and grandparents to google "how to install npm". On the other hand, the bulk of users are probably fairly computer-literate.
+The skill creator is liable to be used by people across a wide range of familiarity with coding jargon. If you haven't heard (and how could you, it's only very recently that it started), there's a trend now where the power of AI coding agents like pi is inspiring plumbers to open up their terminals, parents and grandparents to google "how to install npm". On the other hand, the bulk of users are probably fairly computer-literate.
 
 So please pay attention to context cues to understand how to phrase your communication! In the default case, just to give you some idea:
 
@@ -48,7 +48,7 @@ It's OK to briefly explain terms if you're in doubt, and feel free to clarify te
 
 Start by understanding the user's intent. The current conversation might already contain a workflow the user wants to capture (e.g., they say "turn this into a skill"). If so, extract answers from the conversation history first — the tools used, the sequence of steps, corrections the user made, input/output formats observed. The user may need to fill the gaps, and should confirm before proceeding to the next step.
 
-1. What should this skill enable Claude to do?
+1. What should this skill enable pi to do?
 2. When should this skill trigger? (what user phrases/contexts)
 3. What's the expected output format?
 4. Should we set up test cases to verify the skill works? Skills with objectively verifiable outputs (file transforms, data extraction, code generation, fixed workflow steps) benefit from test cases. Skills with subjective outputs (writing style, art) often don't need them. Suggest the appropriate default based on the skill type, but let the user decide.
@@ -63,8 +63,8 @@ Check available MCPs - if useful for research (searching docs, finding similar s
 
 Based on the user interview, fill in these components:
 
-- **name**: Skill identifier
-- **description**: When to trigger, what it does. This is the primary triggering mechanism - include both what the skill does AND specific contexts for when to use it. All "when to use" info goes here, not in the body. Note: currently Claude has a tendency to "undertrigger" skills -- to not use them when they'd be useful. To combat this, please make the skill descriptions a little bit "pushy". So for instance, instead of "How to build a simple fast dashboard to display internal Anthropic data.", you might write "How to build a simple fast dashboard to display internal Anthropic data. Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a 'dashboard.'"
+- **name**: Skill identifier (lowercase, hyphens, a-z0-9 — see pi's skill validation rules)
+- **description**: When to trigger, what it does. This is the primary triggering mechanism - include both what the skill does AND specific contexts for when to use it. All "when to use" info goes here, not in the body. Note: currently models have a tendency to "undertrigger" skills -- to not use them when they'd be useful. To combat this, please make the skill descriptions a little bit "pushy". So for instance, instead of "How to build a simple fast dashboard to display internal Anthropic data.", you might write "How to build a simple fast dashboard to display internal Anthropic data. Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a 'dashboard.'"
 - **compatibility**: Required tools, dependencies (optional, rarely needed)
 - **the rest of the skill :)**
 
@@ -106,7 +106,15 @@ cloud-deploy/
     ├── gcp.md
     └── azure.md
 ```
-Claude reads only the relevant reference file.
+The agent reads only the relevant reference file.
+
+#### How pi discovers and loads skills
+
+This matters both for writing skills and for testing them. Pi scans skill locations at startup (`~/.pi/agent/skills/`, `~/.agents/skills/`, project `.pi/skills/` and `.agents/skills/`, settings `skills` arrays, and the `--skill <path>` CLI flag). It extracts each skill's `name` + `description` and lists them in the system prompt as `available_skills`. When a task matches a skill, the agent uses the `read` tool to load the full `SKILL.md` on demand — that's progressive disclosure. Skills also register as `/skill:name` commands the user can invoke directly to force-load them.
+
+Two practical consequences for this skill:
+- **Where to install a finished skill**: global skills go in `~/.pi/agent/skills/<skill-name>/`; project skills go in `.pi/skills/<skill-name>/` (only loaded once the project is trusted).
+- **How triggering is measured**: the eval scripts in `scripts/` test triggering by watching whether pi actually performs that `read` on the skill's `SKILL.md`. They invoke `pi -p --mode json --skill <temp-skill-dir>` so the description under test is evaluated in isolation (with `--no-skills` to suppress all other discovered skills).
 
 #### Principle of Lack of Surprise
 
@@ -168,9 +176,9 @@ Put results in `<skill-name>-workspace/` as a sibling to the skill directory. Wi
 
 ### Step 1: Spawn all runs (with-skill AND baseline) in the same turn
 
-For each test case, spawn two subagents in the same turn — one with the skill, one without. This is important: don't spawn the with-skill runs first and then come back for baselines later. Launch everything at once so it all finishes around the same time.
+For each test case, spawn two subagents in the same turn — one with the skill, one without. This is important: don't spawn the with-skill runs first and then come back for baselines later. Launch everything at once so it all finishes around the same time. (If your harness has no subagent tool, see "Running without subagents" below — run them inline, one at a time, and skip baselines.)
 
-**With-skill run:**
+**With-skill run** (give the subagent a task like this):
 
 ```
 Execute this task:
@@ -179,6 +187,8 @@ Execute this task:
 - Input files: <eval files if any, or "none">
 - Save outputs to: <workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/
 - Outputs to save: <what the user cares about — e.g., "the .docx file", "the final CSV">
+
+Load the skill at <path-to-skill> (read its SKILL.md) before starting, and follow it.
 ```
 
 **Baseline run** (same prompt, but the baseline depends on context):
@@ -206,7 +216,7 @@ Update the `eval_metadata.json` files and `evals/evals.json` with the assertions
 
 ### Step 3: As runs complete, capture timing data
 
-When each subagent task completes, you receive a notification containing `total_tokens` and `duration_ms`. Save this data immediately to `timing.json` in the run directory:
+When each subagent task completes, you receive a notification containing `total_tokens` and `duration_ms` (or equivalent usage info from the result). Save this data immediately to `timing.json` in the run directory:
 
 ```json
 {
@@ -216,7 +226,7 @@ When each subagent task completes, you receive a notification containing `total_
 }
 ```
 
-This is the only opportunity to capture this data — it comes through the task notification and isn't persisted elsewhere. Process each notification as it arrives rather than trying to batch them.
+If your harness's completion notification carries a different shape, capture whatever token/duration fields it provides. Process each notification as it arrives rather than trying to batch them.
 
 ### Step 4: Grade, aggregate, and launch the viewer
 
@@ -244,7 +254,7 @@ Put each with_skill version before its baseline counterpart.
    ```
    For iteration 2+, also pass `--previous-workspace <workspace>/iteration-<N-1>`.
 
-   **Cowork / headless environments:** If `webbrowser.open()` is not available or the environment has no display, use `--static <output_path>` to write a standalone HTML file instead of starting a server. Feedback will be downloaded as a `feedback.json` file when the user clicks "Submit All Reviews". After download, copy `feedback.json` into the workspace directory for the next iteration to pick up.
+   **Headless / no-display environments:** If `webbrowser.open()` is not available or the environment has no display (remote server, CI), use `--static <output_path>` to write a standalone HTML file instead of starting a server. Feedback will be downloaded as a `feedback.json` file when the user clicks "Submit All Reviews". After download, copy `feedback.json` into the workspace directory for the next iteration to pick up.
 
 Note: please use generate_review.py to create the viewer; there's no need to write custom HTML.
 
@@ -332,7 +342,7 @@ This is optional, requires subagents, and most users won't need it. The human re
 
 ## Description Optimization
 
-The description field in SKILL.md frontmatter is the primary mechanism that determines whether Claude invokes a skill. After creating or improving a skill, offer to optimize the description for better triggering accuracy.
+The description field in SKILL.md frontmatter is the primary mechanism that determines whether pi invokes a skill. After creating or improving a skill, offer to optimize the description for better triggering accuracy.
 
 ### Step 1: Generate trigger eval queries
 
@@ -345,7 +355,7 @@ Create 20 eval queries — a mix of should-trigger and should-not-trigger. Save
 ]
 ```
 
-The queries must be realistic and something a Claude Code or Claude.ai user would actually type. Not abstract requests, but requests that are concrete and specific and have a good amount of detail. For instance, file paths, personal context about the user's job or situation, column names and values, company names, URLs. A little bit of backstory. Some might be in lowercase or contain abbreviations or typos or casual speech. Use a mix of different lengths, and focus on edge cases rather than making them clear-cut (the user will get a chance to sign off on them).
+The queries must be realistic and something a pi user would actually type. Not abstract requests, but requests that are concrete and specific and have a good amount of detail. For instance, file paths, personal context about the user's job or situation, column names and values, company names, URLs. A little bit of backstory. Some might be in lowercase or contain abbreviations or typos or casual speech. Use a mix of different lengths, and focus on edge cases rather than making them clear-cut (the user will get a chance to sign off on them).
 
 Bad: `"Format this data"`, `"Extract text from PDF"`, `"Create a chart"`
 
@@ -387,17 +397,17 @@ python -m scripts.run_loop \
   --verbose
 ```
 
-Use the model ID from your system prompt (the one powering the current session) so the triggering test matches what the user actually experiences.
+Use the model ID from your system prompt (the one powering the current session) so the triggering test matches what the user actually experiences. For pi this is a model pattern like `anthropic/claude-sonnet-4-20250514` or whatever you're running as (with an optional `:thinking` suffix).
 
 While it runs, periodically tail the output to give the user updates on which iteration it's on and what the scores look like.
 
-This handles the full optimization loop automatically. It splits the eval set into 60% train and 40% held-out test, evaluates the current description (running each query 3 times to get a reliable trigger rate), then calls Claude to propose improvements based on what failed. It re-evaluates each new description on both train and test, iterating up to 5 times. When it's done, it opens an HTML report in the browser showing the results per iteration and returns JSON with `best_description` — selected by test score rather than train score to avoid overfitting.
+This handles the full optimization loop automatically. It splits the eval set into 60% train and 40% held-out test, evaluates the current description (running each query 3 times to get a reliable trigger rate), then calls pi to propose improvements based on what failed. It re-evaluates each new description on both train and test, iterating up to 5 times. When it's done, it opens an HTML report in the browser showing the results per iteration and returns JSON with `best_description` — selected by test score rather than train score to avoid overfitting.
 
 ### How skill triggering works
 
-Understanding the triggering mechanism helps design better eval queries. Skills appear in Claude's `available_skills` list with their name + description, and Claude decides whether to consult a skill based on that description. The important thing to know is that Claude only consults skills for tasks it can't easily handle on its own — simple, one-step queries like "read this PDF" may not trigger a skill even if the description matches perfectly, because Claude can handle them directly with basic tools. Complex, multi-step, or specialized queries reliably trigger skills when the description matches.
+Understanding the triggering mechanism helps design better eval queries. Skills appear in pi's `available_skills` list (in the system prompt) with their name + description, and the agent decides whether to consult a skill based on that description. The important thing to know is that the agent only consults skills for tasks it can't easily handle on its own — simple, one-step queries like "read this PDF" may not trigger a skill even if the description matches perfectly, because the agent can handle them directly with basic tools. Complex, multi-step, or specialized queries reliably trigger skills when the description matches.
 
-This means your eval queries should be substantive enough that Claude would actually benefit from consulting a skill. Simple queries like "read file X" are poor test cases — they won't trigger skills regardless of description quality.
+This means your eval queries should be substantive enough that the agent would actually benefit from consulting a skill. Simple queries like "read file X" are poor test cases — they won't trigger skills regardless of description quality.
 
 ### Step 4: Apply the result
 
@@ -417,45 +427,31 @@ After packaging, direct the user to the resulting `.skill` file path so they can
 
 ---
 
-## Claude.ai-specific instructions
+## Running without subagents
 
-In Claude.ai, the core workflow is the same (draft → test → review → improve → repeat), but because Claude.ai doesn't have subagents, some mechanics change. Here's what to adapt:
+The core workflow is the same (draft → test → review → improve → repeat), but if your harness has no subagent tool, some mechanics change. Here's what to adapt:
 
 **Running test cases**: No subagents means no parallel execution. For each test case, read the skill's SKILL.md, then follow its instructions to accomplish the test prompt yourself. Do them one at a time. This is less rigorous than independent subagents (you wrote the skill and you're also running it, so you have full context), but it's a useful sanity check — and the human review step compensates. Skip the baseline runs — just use the skill to complete the task as requested.
 
-**Reviewing results**: If you can't open a browser (e.g., Claude.ai's VM has no display, or you're on a remote server), skip the browser reviewer entirely. Instead, present results directly in the conversation. For each test case, show the prompt and the output. If the output is a file the user needs to see (like a .docx or .xlsx), save it to the filesystem and tell them where it is so they can download and inspect it. Ask for feedback inline: "How does this look? Anything you'd change?"
+**Reviewing results**: If you can't open a browser (e.g., a remote server with no display), skip the browser reviewer entirely. Instead, present results directly in the conversation. For each test case, show the prompt and the output. If the output is a file the user needs to see (like a .docx or .xlsx), save it to the filesystem and tell them where it is so they can inspect it. Ask for feedback inline: "How does this look? Anything you'd change?"
 
 **Benchmarking**: Skip the quantitative benchmarking — it relies on baseline comparisons which aren't meaningful without subagents. Focus on qualitative feedback from the user.
 
-**The iteration loop**: Same as before — improve the skill, rerun the test cases, ask for feedback — just without the browser reviewer in the middle. You can still organize results into iteration directories on the filesystem if you have one.
+**The iteration loop**: Same as before — improve the skill, rerun the test cases, ask for feedback — just without the browser reviewer in the middle. You can still organize results into iteration directories on the filesystem.
 
-**Description optimization**: This section requires the `claude` CLI tool (specifically `claude -p`) which is only available in Claude Code. Skip it if you're on Claude.ai.
+**Description optimization**: This requires the `pi` CLI (specifically `pi -p`) which the eval scripts call via subprocess. It works as long as `pi` is on PATH. If it isn't available in the environment, skip description optimization.
 
 **Blind comparison**: Requires subagents. Skip it.
 
-**Packaging**: The `package_skill.py` script works anywhere with Python and a filesystem. On Claude.ai, you can run it and the user can download the resulting `.skill` file.
+**Packaging**: The `package_skill.py` script works anywhere with Python and a filesystem.
 
 **Updating an existing skill**: The user might be asking you to update an existing skill, not create a new one. In this case:
 - **Preserve the original name.** Note the skill's directory name and `name` frontmatter field -- use them unchanged. E.g., if the installed skill is `research-helper`, output `research-helper.skill` (not `research-helper-v2`).
-- **Copy to a writeable location before editing.** The installed skill path may be read-only. Copy to `/tmp/skill-name/`, edit there, and package from the copy.
+- **Copy to a writeable location before editing.** An installed skill path may be read-only (e.g., a global `~/.pi/agent/skills/` install). Copy to `/tmp/skill-name/`, edit there, and package from the copy.
 - **If packaging manually, stage in `/tmp/` first**, then copy to the output directory -- direct writes may fail due to permissions.
 
 ---
 
-## Cowork-Specific Instructions
-
-If you're in Cowork, the main things to know are:
-
-- You have subagents, so the main workflow (spawn test cases in parallel, run baselines, grade, etc.) all works. (However, if you run into severe problems with timeouts, it's OK to run the test prompts in series rather than parallel.)
-- You don't have a browser or display, so when generating the eval viewer, use `--static <output_path>` to write a standalone HTML file instead of starting a server. Then proffer a link that the user can click to open the HTML in their browser.
-- For whatever reason, the Cowork setup seems to disincline Claude from generating the eval viewer after running the tests, so just to reiterate: whether you're in Cowork or in Claude Code, after running tests, you should always generate the eval viewer for the human to look at examples before revising the skill yourself and trying to make corrections, using `generate_review.py` (not writing your own boutique html code). Sorry in advance but I'm gonna go all caps here: GENERATE THE EVAL VIEWER *BEFORE* evaluating inputs yourself. You want to get them in front of the human ASAP!
-- Feedback works differently: since there's no running server, the viewer's "Submit All Reviews" button will download `feedback.json` as a file. You can then read it from there (you may have to request access first).
-- Packaging works — `package_skill.py` just needs Python and a filesystem.
-- Description optimization (`run_loop.py` / `run_eval.py`) should work in Cowork just fine since it uses `claude -p` via subprocess, not a browser, but please save it until you've fully finished making the skill and the user agrees it's in good shape.
-- **Updating an existing skill**: The user might be asking you to update an existing skill, not create a new one. Follow the update guidance in the claude.ai section above.
-
----
-
 ## Reference files
 
 The agents/ directory contains instructions for specialized subagents. Read them when you need to spawn the relevant subagent.
@@ -473,13 +469,13 @@ Repeating one more time the core loop here for emphasis:
 
 - Figure out what the skill is about
 - Draft or edit the skill
-- Run claude-with-access-to-the-skill on test prompts
+- Run pi-with-access-to-the-skill on test prompts
 - With the user, evaluate the outputs:
   - Create benchmark.json and run `eval-viewer/generate_review.py` to help the user review them
   - Run quantitative evals
 - Repeat until you and the user are satisfied
 - Package the final skill and return it to the user.
 
-Please add steps to your TodoList, if you have such a thing, to make sure you don't forget. If you're in Cowork, please specifically put "Create evals JSON and run `eval-viewer/generate_review.py` so human can review test cases" in your TodoList to make sure it happens.
+Please add steps to your TodoList, if you have such a thing, to make sure you don't forget. Specifically put "Create evals JSON and run `eval-viewer/generate_review.py` so human can review test cases" in your TodoList to make sure it happens.
 
 Good luck!

package/skills/skill-creator/eval-viewer/viewer.html

@@ -545,7 +545,7 @@
     <div class="header">
       <div>
         <h1>Eval Review: <span id="skill-name"></span></h1>
-        <div class="instructions">Review each output and leave feedback below. Navigate with arrow keys or buttons. When done, copy feedback and paste into Claude Code.</div>
+        <div class="instructions">Review each output and leave feedback below. Navigate with arrow keys or buttons. When done, copy feedback and paste into your pi session.</div>
       </div>
       <div class="progress" id="progress"></div>
     </div>
@@ -634,7 +634,7 @@
   <div class="done-overlay" id="done-overlay">
     <div class="done-card">
       <h2>Review Complete</h2>
-      <p>Your feedback has been saved. Go back to your Claude Code session and tell Claude you're done reviewing.</p>
+      <p>Your feedback has been saved. Go back to your pi session and tell the agent you're done reviewing.</p>
       <div class="btn-row">
         <button onclick="closeDoneDialog()">OK</button>
       </div>

package/skills/skill-creator/references/schemas.md

@@ -225,7 +225,7 @@ Output from Benchmark mode. Located at `benchmarks/<timestamp>/benchmark.json`.
   "metadata": {
     "skill_name": "pdf",
     "skill_path": "/path/to/pdf",
-    "executor_model": "claude-sonnet-4-20250514",
+    "executor_model": "anthropic/claude-sonnet-4-20250514",
     "analyzer_model": "most-capable-model",
     "timestamp": "2026-01-15T10:30:00Z",
     "evals_run": [1, 2, 3],

package/skills/skill-creator/scripts/generate_report.py

@@ -148,7 +148,7 @@ def generate_html(data: dict, auto_refresh: bool = False, skill_name: str = "")
 <body>
     <h1>""" + title_prefix + """Skill Description Optimization</h1>
     <div class="explainer">
-        <strong>Optimizing your skill's description.</strong> This page updates automatically as Claude tests different versions of your skill's description. Each row is an iteration — a new description attempt. The columns show test queries: green checkmarks mean the skill triggered correctly (or correctly didn't trigger), red crosses mean it got it wrong. The "Train" score shows performance on queries used to improve the description; the "Test" score shows performance on held-out queries the optimizer hasn't seen. When it's done, Claude will apply the best-performing description to your skill.
+        <strong>Optimizing your skill's description.</strong> This page updates automatically as pi tests different versions of your skill's description. Each row is an iteration — a new description attempt. The columns show test queries: green checkmarks mean the skill triggered correctly (or correctly didn't trigger), red crosses mean it got it wrong. The "Train" score shows performance on queries used to improve the description; the "Test" score shows performance on held-out queries the optimizer hasn't seen. When it's done, pi will apply the best-performing description to your skill.
     </div>
 """]
 

package/skills/skill-creator/scripts/improve_description.py

@@ -2,13 +2,12 @@
 """Improve a skill description based on eval results.
 
 Takes eval results (from run_eval.py) and generates an improved description
-by calling `claude -p` as a subprocess (same auth pattern as run_eval.py —
-uses the session's Claude Code auth, no separate ANTHROPIC_API_KEY needed).
+by calling `pi -p` as a subprocess (uses the session's pi auth/config, no
+separate API key needed).
 """
 
 import argparse
 import json
-import os
 import re
 import subprocess
 import sys
@@ -17,32 +16,26 @@ from pathlib import Path
 from scripts.utils import parse_skill_md
 
 
-def _call_claude(prompt: str, model: str | None, timeout: int = 300) -> str:
-    """Run `claude -p` with the prompt on stdin and return the text response.
+def _call_pi(prompt: str, model: str | None, timeout: int = 300) -> str:
+    """Run `pi -p` with the prompt on stdin and return the text response.
 
     Prompt goes over stdin (not argv) because it embeds the full SKILL.md
     body and can easily exceed comfortable argv length.
     """
-    cmd = ["claude", "-p", "--output-format", "text"]
+    cmd = ["pi", "-p", "--mode", "text", "--no-session"]
     if model:
         cmd.extend(["--model", model])
 
-    # Remove CLAUDECODE env var to allow nesting claude -p inside a
-    # Claude Code session. The guard is for interactive terminal conflicts;
-    # programmatic subprocess usage is safe. Same pattern as run_eval.py.
-    env = {k: v for k, v in os.environ.items() if k != "CLAUDECODE"}
-
     result = subprocess.run(
         cmd,
         input=prompt,
         capture_output=True,
         text=True,
-        env=env,
         timeout=timeout,
     )
     if result.returncode != 0:
         raise RuntimeError(
-            f"claude -p exited {result.returncode}\nstderr: {result.stderr}"
+            f"pi -p exited {result.returncode}\nstderr: {result.stderr}"
         )
     return result.stdout
 
@@ -58,7 +51,7 @@ def improve_description(
     log_dir: Path | None = None,
     iteration: int | None = None,
 ) -> str:
-    """Call Claude to improve the description based on eval results."""
+    """Call pi to improve the description based on eval results."""
     failed_triggers = [
         r for r in eval_results["results"]
         if r["should_trigger"] and not r["pass"]
@@ -68,7 +61,6 @@ def improve_description(
         if not r["should_trigger"] and not r["pass"]
     ]
 
-    # Build scores summary
     train_score = f"{eval_results['summary']['passed']}/{eval_results['summary']['total']}"
     if test_results:
         test_score = f"{test_results['summary']['passed']}/{test_results['summary']['total']}"
@@ -76,9 +68,9 @@ def improve_description(
     else:
         scores_summary = f"Train: {train_score}"
 
-    prompt = f"""You are optimizing a skill description for a Claude Code skill called "{skill_name}". A "skill" is sort of like a prompt, but with progressive disclosure -- there's a title and description that Claude sees when deciding whether to use the skill, and then if it does use the skill, it reads the .md file which has lots more details and potentially links to other resources in the skill folder like helper files and scripts and additional documentation or examples.
+    prompt = f"""You are optimizing a skill description for a pi skill called "{skill_name}". A "skill" is sort of like a prompt, but with progressive disclosure -- there's a title and description that the agent sees when deciding whether to use the skill, and then if it does use the skill, it reads the .md file which has lots more details and potentially links to other resources in the skill folder like helper files and scripts and additional documentation or examples.
 
-The description appears in Claude's "available_skills" list. When a user sends a query, Claude decides whether to invoke the skill based solely on the title and on this description. Your goal is to write a description that triggers for relevant queries, and doesn't trigger for irrelevant ones.
+The description appears in the agent's "available_skills" list. When a user sends a query, the agent decides whether to invoke the skill based solely on the title and on this description. Your goal is to write a description that triggers for relevant queries, and doesn't trigger for irrelevant ones.
 
 Here's the current description:
 <current_description>
@@ -134,14 +126,14 @@ Concretely, your description should not be more than about 100-200 words, even i
 Here are some tips that we've found to work well in writing these descriptions:
 - The skill should be phrased in the imperative -- "Use this skill for" rather than "this skill does"
 - The skill description should focus on the user's intent, what they are trying to achieve, vs. the implementation details of how the skill works.
-- The description competes with other skills for Claude's attention — make it distinctive and immediately recognizable.
+- The description competes with other skills for the agent's attention — make it distinctive and immediately recognizable.
 - If you're getting lots of failures after repeated attempts, change things up. Try different sentence structures or wordings.
 
 I'd encourage you to be creative and mix up the style in different iterations since you'll have multiple opportunities to try different approaches and we'll just grab the highest-scoring one at the end. 
 
 Please respond with only the new description text in <new_description> tags, nothing else."""
 
-    text = _call_claude(prompt, model)
+    text = _call_pi(prompt, model)
 
     match = re.search(r"<new_description>(.*?)</new_description>", text, re.DOTALL)
     description = match.group(1).strip().strip('"') if match else text.strip().strip('"')
@@ -157,9 +149,8 @@ Please respond with only the new description text in <new_description> tags, not
 
     # Safety net: the prompt already states the 1024-char hard limit, but if
     # the model blew past it anyway, make one fresh single-turn call that
-    # quotes the too-long version and asks for a shorter rewrite. (The old
-    # SDK path did this as a true multi-turn; `claude -p` is one-shot, so we
-    # inline the prior output into the new prompt instead.)
+    # quotes the too-long version and asks for a shorter rewrite. (pi -p is
+    # one-shot, so we inline the prior output into the new prompt instead.)
     if len(description) > 1024:
         shorten_prompt = (
             f"{prompt}\n\n"
@@ -171,7 +162,7 @@ Please respond with only the new description text in <new_description> tags, not
             f"important trigger words and intent coverage. Respond with only "
             f"the new description in <new_description> tags."
         )
-        shorten_text = _call_claude(shorten_prompt, model)
+        shorten_text = _call_pi(shorten_prompt, model)
         match = re.search(r"<new_description>(.*?)</new_description>", shorten_text, re.DOTALL)
         shortened = match.group(1).strip().strip('"') if match else shorten_text.strip().strip('"')
 
@@ -229,7 +220,6 @@ def main():
     if args.verbose:
         print(f"Improved: {new_description}", file=sys.stderr)
 
-    # Output as JSON with both the new description and updated history
     output = {
         "description": new_description,
         "history": history + [{

package/skills/skill-creator/scripts/run_eval.py

@@ -1,16 +1,19 @@
 #!/usr/bin/env python3
 """Run trigger evaluation for a skill description.
 
-Tests whether a skill's description causes Claude to trigger (read the skill)
+Tests whether a skill's description causes pi to trigger (read the skill)
 for a set of queries. Outputs results as JSON.
 """
 
 import argparse
 import json
 import os
+import re
 import select
+import shutil
 import subprocess
 import sys
+import tempfile
 import time
 import uuid
 from concurrent.futures import ProcessPoolExecutor, as_completed
@@ -20,82 +23,92 @@ from scripts.utils import parse_skill_md
 
 
 def find_project_root() -> Path:
-    """Find the project root by walking up from cwd looking for .claude/.
+    """Return the working directory pi should run in.
 
-    Mimics how Claude Code discovers its project root, so the command file
-    we create ends up where claude -p will look for it.
+    Unlike Claude Code, pi has no `.claude/` project marker that controls
+    skill discovery — skills are loaded explicitly via `--skill` (or from
+    pi's own skill locations). We simply use the current directory so the
+    agent sees the same relative paths the user would.
     """
-    current = Path.cwd()
-    for parent in [current, *current.parents]:
-        if (parent / ".claude").is_dir():
-            return parent
-    return current
+    return Path.cwd()
+
+
+def _safe_skill_name(raw: str, unique_id: str) -> str:
+    """Build a frontmatter-valid skill name (lowercase, hyphens, a-z0-9)."""
+    base = re.sub(r"[^a-z0-9]+", "-", (raw or "skill").lower()).strip("-") or "skill"
+    return f"{base}-{unique_id}"
 
 
 def run_single_query(
     query: str,
     skill_name: str,
     skill_description: str,
+    skill_body: str,
     timeout: int,
     project_root: str,
     model: str | None = None,
 ) -> bool:
     """Run a single query and return whether the skill was triggered.
 
-    Creates a command file in .claude/commands/ so it appears in Claude's
-    available_skills list, then runs `claude -p` with the raw query.
-    Uses --include-partial-messages to detect triggering early from
-    stream events (content_block_start) rather than waiting for the
-    full assistant message, which only arrives after tool execution.
+    Creates a throwaway skill directory whose SKILL.md carries the
+    description under test, then runs `pi -p --mode json --skill <dir>`.
+    We watch the JSON event stream for a `read` tool call targeting that
+    SKILL.md, which is how pi loads a skill once the model decides to use
+    it. As soon as we see it, we return True and kill the process so the
+    run doesn't keep executing the skill.
     """
     unique_id = uuid.uuid4().hex[:8]
-    clean_name = f"{skill_name}-skill-{unique_id}"
-    project_commands_dir = Path(project_root) / ".claude" / "commands"
-    command_file = project_commands_dir / f"{clean_name}.md"
+    clean_name = _safe_skill_name(skill_name, unique_id)
+    temp_skill_dir = Path(tempfile.mkdtemp(prefix=f"pi-skill-eval-{unique_id}-"))
+    skill_md_path = temp_skill_dir / "SKILL.md"
 
     try:
-        project_commands_dir.mkdir(parents=True, exist_ok=True)
-        # Use YAML block scalar to avoid breaking on quotes in description
+        # Write a SKILL.md with the description under test. The body is the
+        # real skill body so the model behaves naturally if it does read it,
+        # but the triggering decision is driven solely by the description.
         indented_desc = "\n  ".join(skill_description.split("\n"))
-        command_content = (
+        skill_md_content = (
             f"---\n"
+            f"name: {clean_name}\n"
             f"description: |\n"
             f"  {indented_desc}\n"
             f"---\n\n"
-            f"# {skill_name}\n\n"
-            f"This skill handles: {skill_description}\n"
+            f"{skill_body.strip()}\n"
         )
-        command_file.write_text(command_content)
+        skill_md_path.write_text(skill_md_content)
 
         cmd = [
-            "claude",
-            "-p", query,
-            "--output-format", "stream-json",
-            "--verbose",
-            "--include-partial-messages",
+            "pi",
+            "-p", "--mode", "json",
+            "--no-session",
+            # Only the skill under test should be available, so its
+            # description is what gets evaluated in isolation. Explicit
+            # --skill paths still load even with --no-skills.
+            "--no-skills",
+            "--skill", str(temp_skill_dir),
+            query,
         ]
         if model:
             cmd.extend(["--model", model])
 
-        # Remove CLAUDECODE env var to allow nesting claude -p inside a
-        # Claude Code session. The guard is for interactive terminal conflicts;
-        # programmatic subprocess usage is safe.
-        env = {k: v for k, v in os.environ.items() if k != "CLAUDECODE"}
-
         process = subprocess.Popen(
             cmd,
             stdout=subprocess.PIPE,
             stderr=subprocess.DEVNULL,
             cwd=project_root,
-            env=env,
         )
 
         triggered = False
         start_time = time.time()
         buffer = ""
-        # Track state for stream event detection
-        pending_tool_name = None
-        accumulated_json = ""
+
+        def _targets_skill(path: str) -> bool:
+            """True if a read target points at the temp skill's SKILL.md."""
+            if not path:
+                return False
+            # The temp dir name embeds unique_id, so this is unique per run
+            # and survives absolute/relative/tilde variations.
+            return unique_id in path or clean_name in path
 
         try:
             while time.time() - start_time < timeout:
@@ -125,66 +138,42 @@ def run_single_query(
                     except json.JSONDecodeError:
                         continue
 
-                    # Early detection via stream events
-                    if event.get("type") == "stream_event":
-                        se = event.get("event", {})
-                        se_type = se.get("type", "")
-
-                        if se_type == "content_block_start":
-                            cb = se.get("content_block", {})
-                            if cb.get("type") == "tool_use":
-                                tool_name = cb.get("name", "")
-                                if tool_name in ("Skill", "Read"):
-                                    pending_tool_name = tool_name
-                                    accumulated_json = ""
-                                else:
-                                    return False
-
-                        elif se_type == "content_block_delta" and pending_tool_name:
-                            delta = se.get("delta", {})
-                            if delta.get("type") == "input_json_delta":
-                                accumulated_json += delta.get("partial_json", "")
-                                if clean_name in accumulated_json:
+                    etype = event.get("type")
+
+                    # Fully-formed tool call (fires before execution).
+                    if etype == "message_update":
+                        ame = event.get("assistantMessageEvent", {})
+                        if ame.get("type") == "toolcall_end":
+                            tool_call = ame.get("toolCall", {})
+                            if tool_call.get("name") == "read":
+                                path = (tool_call.get("arguments") or {}).get("path", "")
+                                if _targets_skill(path):
                                     return True
 
-                        elif se_type in ("content_block_stop", "message_stop"):
-                            if pending_tool_name:
-                                return clean_name in accumulated_json
-                            if se_type == "message_stop":
-                                return False
-
-                    # Fallback: full assistant message
-                    elif event.get("type") == "assistant":
-                        message = event.get("message", {})
-                        for content_item in message.get("content", []):
-                            if content_item.get("type") != "tool_use":
-                                continue
-                            tool_name = content_item.get("name", "")
-                            tool_input = content_item.get("input", {})
-                            if tool_name == "Skill" and clean_name in tool_input.get("skill", ""):
-                                triggered = True
-                            elif tool_name == "Read" and clean_name in tool_input.get("file_path", ""):
-                                triggered = True
-                            return triggered
-
-                    elif event.get("type") == "result":
+                    # Tool actually started executing — redundant but robust.
+                    elif etype == "tool_execution_start":
+                        if event.get("toolName") == "read":
+                            path = (event.get("args") or {}).get("path", "")
+                            if _targets_skill(path):
+                                return True
+
+                    elif etype == "agent_end":
                         return triggered
         finally:
-            # Clean up process on any exit path (return, exception, timeout)
             if process.poll() is None:
                 process.kill()
                 process.wait()
 
         return triggered
     finally:
-        if command_file.exists():
-            command_file.unlink()
+        shutil.rmtree(temp_skill_dir, ignore_errors=True)
 
 
 def run_eval(
     eval_set: list[dict],
     skill_name: str,
     description: str,
+    skill_body: str,
     num_workers: int,
     timeout: int,
     project_root: Path,
@@ -204,6 +193,7 @@ def run_eval(
                     item["query"],
                     skill_name,
                     description,
+                    skill_body,
                     timeout,
                     str(project_root),
                     model,
@@ -256,6 +246,21 @@ def run_eval(
     }
 
 
+def extract_skill_body(skill_path: Path, full_content: str) -> str:
+    """Return the SKILL.md body (everything after the frontmatter)."""
+    lines = full_content.split("\n")
+    if not lines or lines[0].strip() != "---":
+        return full_content
+    end_idx = None
+    for i, line in enumerate(lines[1:], start=1):
+        if line.strip() == "---":
+            end_idx = i
+            break
+    if end_idx is None:
+        return full_content
+    return "\n".join(lines[end_idx + 1:])
+
+
 def main():
     parser = argparse.ArgumentParser(description="Run trigger evaluation for a skill description")
     parser.add_argument("--eval-set", required=True, help="Path to eval set JSON file")
@@ -265,7 +270,7 @@ def main():
     parser.add_argument("--timeout", type=int, default=30, help="Timeout per query in seconds")
     parser.add_argument("--runs-per-query", type=int, default=3, help="Number of runs per query")
     parser.add_argument("--trigger-threshold", type=float, default=0.5, help="Trigger rate threshold")
-    parser.add_argument("--model", default=None, help="Model to use for claude -p (default: user's configured model)")
+    parser.add_argument("--model", default=None, help="Model to use for pi -p (default: user's configured model)")
     parser.add_argument("--verbose", action="store_true", help="Print progress to stderr")
     args = parser.parse_args()
 
@@ -278,6 +283,7 @@ def main():
 
     name, original_description, content = parse_skill_md(skill_path)
     description = args.description or original_description
+    skill_body = extract_skill_body(skill_path, content)
     project_root = find_project_root()
 
     if args.verbose:
@@ -287,6 +293,7 @@ def main():
         eval_set=eval_set,
         skill_name=name,
         description=description,
+        skill_body=skill_body,
         num_workers=args.num_workers,
         timeout=args.timeout,
         project_root=project_root,