pi-prompt-template-model 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-03-19
+
+### Changed
+
+- Clarified the README chain examples so the optional ` -- ` shared-args separator is clearly distinct from loop flags like `--loop`, `--fresh`, and `--no-converge`.
+- Clarified in the README that chain frontmatter declarations support per-step `--loop N` inside the `chain:` value.
+- Argument substitution now accepts `@$` as an alias for `$@` for compatibility with commonly-typed placeholder variants.
+- Skill injection now uses a next-turn context message from `before_agent_start` instead of mutating the turn system prompt.
+- Non-chain templates can now omit `model` and inherit the current session model, so inline `<if-model ...>` rendering and skill injection still work without explicit model frontmatter.
+- Chain steps without `model` now inherit a fixed chain-start model snapshot, so model-less chain steps behave as if that model were declared in frontmatter while remaining deterministic across step switches.
+
+### Fixed
+
+- Chain step execution now avoids implicit previous-step model bleed for model-less templates by resolving them against the chain-start model snapshot instead of whichever model was active after the prior step.
+- Model-less prompt loading now skips plain templates that do not use extension features, preventing command collisions with other extension commands like `/review` and `/handover`.
+- Model-less prompt loading now also ignores no-op/invalid-only extension metadata (for example `restore`-only or invalid loop flags), so ineffective frontmatter does not unnecessarily claim command names.
+- Model-less prompt loading now recognizes invalid conditional closers like `</else>` as extension-relevant markup, so those templates stay in this extension path and surface proper conditional-parse warnings instead of silently bypassing extension handling.
+- Model-less prompt execution now tracks runtime model changes (`model_select` + internal switches/restores) and uses that tracked model instead of potentially stale command-context snapshots.
+- Prompt commands now fail fast when a configured `skill` file is missing or unreadable, instead of silently sending the prompt without skill context.
+- Skill resolution now returns a typed success/error outcome that callers handle explicitly, rather than emitting notifications from inside the resolver and returning sentinel `null` values.
+- Session start/switch now clear any queued skill context message so stale pending skill payloads cannot leak across session boundaries.
+- Session start/switch now also clear pending single-command restore state (`previousModel`/`previousThinking`) so restore writes cannot leak into a different session.
+- Skill frontmatter resolution now checks registered skill commands first (`pi.getCommands()` skill entries), accepts both `<name>` and `skill:<name>` values, searches additional standard pi skill locations (`.agents/skills` in project ancestors and `~/.agents/skills`), supports direct `<skill>.md` files alongside `SKILL.md` directories, and rejects traversal-like skill names for path fallback.
+- `extractLoopCount()` now strips repeated unquoted `--loop` tokens once looping is active, preventing stray loop flags from leaking into prompt arguments.
+- Chain frontmatter step parsing now strips repeated per-step `--loop` tokens once a valid per-step loop is resolved, and keeps the first valid value (including mixed invalid/valid numeric sequences like `--loop 1000 --loop 2`).
+- Loop-mode restore now tracks runtime model/thinking state per iteration instead of relying on command-context model snapshots, so model restoration remains correct even when command context values are stale.
+- Chain execution now restores model/thinking state in a `finally` path, so restore still runs after unexpected runtime errors during a chain step and chain cleanup state is still reset even when restore itself fails.
+- Loop and chain executions no longer report `Loop finished`/`Loop converged` when runtime errors abort execution mid-loop.
+- Loop and chain error propagation now preserves thrown falsy values (for example `throw 0`) instead of treating them as success, preventing swallowed errors and false completion notifications.
+
 ## [0.5.0] - 2026-03-17
 
 ### Added

package/README.md

@@ -15,7 +15,7 @@
 │  /debug-python  ──►  Extension detects model + skill                        │
 │       │                                                                     │
 │       ▼                                                                     │
-│  Switches to Sonnet  ──►  Injects tmux skill into system prompt             │
+│  Switches to Sonnet  ──►  Queues tmux skill context for next turn           │
 │       │                                                                     │
 │       ▼                                                                     │
 │  Agent responds with Sonnet + tmux expertise                                │
@@ -49,7 +49,7 @@ Restart pi to load the extension.
 
 ## Quick Start
 
-Add `model` and optionally `skill` to any prompt template:
+Add `model` (or omit it to inherit the current session model) and optionally `skill` to any prompt template:
 
 ```markdown
 ---
@@ -80,15 +80,15 @@ skill: surf
 $@
 ```
 
-Here `skill: surf` loads `~/.pi/agent/skills/surf/SKILL.md` and injects its content directly into the system prompt before the agent even sees your task. No decision-making, no read tool, just immediate expertise. It's a forcing function for when you know exactly what workflow the agent needs.
+Here `skill: surf` loads `~/.pi/agent/skills/surf/SKILL.md` and injects its content as a context message on the next turn before the agent handles your task. No decision-making, no read tool, just immediate expertise. It's a forcing function for when you know exactly what workflow the agent needs.
 
 ## Frontmatter Fields
 
 | Field | Required | Default | Description |
 |-------|----------|---------|-------------|
-| `model` | Conditional | - | Required for non-chain templates; ignored when `chain` is set |
+| `model` | No | `current` | Target model(s). If omitted on a non-chain template, execution inherits the current session model. Ignored when `chain` is set. |
 | `chain` | Conditional | - | Chain declaration (`step -> step --loop 2`) for orchestration templates; body is ignored |
-| `skill` | No | - | Skill name to inject into system prompt |
+| `skill` | No | - | Skill name to inject as next-turn context message |
 | `thinking` | No | - | Thinking level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |
 | `description` | No | - | Shown in autocomplete |
 | `restore` | No | `true` | Restore previous model and thinking level after response |
@@ -153,7 +153,7 @@ Do a deeper pass and call out subtle risks.
 </if-model>
 ```
 
-Conditionals are evaluated against the model that actually runs the command after fallback resolution. That means the same template can render differently depending on which candidate was selected.
+Conditionals are evaluated against the model that actually runs the command. For fallback prompts, that means after candidate resolution; for prompts without `model`, that means the current session model. The same template can render differently depending on which model is active.
 
 Supported matches inside `is="..."`:
 
@@ -183,6 +183,7 @@ Prompt bodies support argument placeholders that expand to command arguments:
 |-------------|-------------|
 | `$1`, `$2`, ... | Positional argument (1-indexed) |
 | `$@` | All arguments joined with spaces |
+| `@$` | Alias for `$@` |
 | `$ARGUMENTS` | Same as `$@` |
 | `${@:N}` | All arguments from position N onward |
 | `${@:N:L}` | L arguments starting from position N |
@@ -203,17 +204,22 @@ Running `/analyze src/main.ts performance edge cases error handling` expands to:
 
 ## Skill Resolution
 
-The `skill` field matches the skill's directory name:
+The `skill` field accepts either a bare skill name or a slash-command style name:
 
 ```yaml
 skill: tmux
+# also valid
+skill: skill:tmux
 ```
 
-Resolves to (checked in order):
-1. `<cwd>/.pi/skills/tmux/SKILL.md` (project)
-2. `~/.pi/agent/skills/tmux/SKILL.md` (user)
+Resolution order:
+1. Registered skill commands from `pi.getCommands()` (`source: "skill"`), matched by `skill:name` or `name`
+2. `<cwd>/.pi/skills/<name>/SKILL.md` or `<cwd>/.pi/skills/<name>.md`
+3. `.agents/skills` in `cwd` and ancestor directories (up to git repo root)
+4. `~/.pi/agent/skills/<name>/SKILL.md` or `~/.pi/agent/skills/<name>.md`
+5. `~/.agents/skills/<name>/SKILL.md` or `~/.agents/skills/<name>.md`
 
-This matches pi's precedence - project skills override user skills.
+If the configured skill file is missing or unreadable, the command fails fast and does not send the prompt body to the model.
 
 ## Subdirectories
 
@@ -310,13 +316,13 @@ Switched to Haiku. How can I help?
 
 ## Chaining Templates
 
-The `/chain-prompts` command runs multiple templates sequentially. Each step switches to its own model, renders any inline model conditionals against that step’s resolved model, injects its own skill, and the conversation context carries forward between steps.
+The `/chain-prompts` command runs multiple templates sequentially. Each step switches to its own model (or, if the step has no `model`, to the chain-start model snapshot), renders inline model conditionals against that resolved step model, injects its own skill context message, and conversation context carries forward between steps.
 
 ```
 /chain-prompts analyze-code -> fix-plan -> summarize -- src/main.ts
 ```
 
-This runs `analyze-code` first, then `fix-plan` (which sees the analysis in conversation context), then `summarize`. The `-- src/main.ts` provides shared args substituted into every template's `$@`.
+This runs `analyze-code` first, then `fix-plan` (which sees the analysis in conversation context), then `summarize`. The ` -- src/main.ts` part is optional. The literal ` -- ` separator means "shared args start here": everything after it is passed to each step as `$@`, unless that step already has its own inline args.
 
 Each step can also receive its own args, overriding the shared args for that step:
 
@@ -348,7 +354,7 @@ chain: double-check --loop 2 -> deslop --loop 2
 ignored — chain templates don't use the body
 ```
 
-This registers `/review-then-clean` as a command that runs `double-check` twice, then `deslop` twice. Each step references a separate prompt template with its own `model`. The chain template itself doesn't need a `model` field — each step uses whatever model its template specifies.
+This registers `/review-then-clean` as a command that runs `double-check` twice, then `deslop` twice. Each step references a separate prompt template. Steps with `model` use their configured model; steps without `model` inherit the chain-start model snapshot (the model active when the chain command began), so behavior stays deterministic even if earlier steps switch models.
 
 Per-step `--loop N` repeats that step N times before moving to the next. Per-step convergence applies: if a step makes no file changes on an iteration, its inner loop stops early (unless the step's template has `converge: false`).
 
@@ -440,14 +446,15 @@ Review the codebase and improve code quality. $@
 Chains support the same looping forms:
 
 ```
+/chain-prompts analyze -> fix --loop 3
+/chain-prompts analyze -> fix --loop=3
+/chain-prompts analyze -> fix --loop
+/chain-prompts analyze -> fix --loop 3 --fresh
+/chain-prompts analyze -> fix --loop 3 --no-converge
 /chain-prompts analyze -> fix --loop 3 -- src/main.ts
-/chain-prompts analyze -> fix --loop=3 -- src/main.ts
-/chain-prompts analyze -> fix --loop -- src/main.ts
-/chain-prompts analyze -> fix --loop 3 --fresh -- src/main.ts
-/chain-prompts analyze -> fix --loop 3 --no-converge -- src/main.ts
 ```
 
-This runs the full chain (analyze → fix) three times. Convergence detection applies across all steps in each iteration — if no step made file changes, the loop stops. Each iteration re-reads prompts from disk, so template edits take effect between iterations. The status bar shows `loop 2/3` during execution.
+This runs the full chain (analyze → fix) three times. The final example adds optional shared args: ` -- src/main.ts` means "pass `src/main.ts` to any step that doesn't already have its own args." If you don't need shared args, leave that part out entirely. Convergence detection applies across all steps in each iteration — if no step made file changes, the loop stops. Each iteration re-reads prompts from disk, so template edits take effect between iterations. The status bar shows `loop 2/3` during execution. Chain frontmatter declarations also support per-step `--loop N` inside the `chain:` value (for example `chain: double-check --loop 3 -> simplify -> deslop`).
 
 ## Agent Tool
 
@@ -499,11 +506,12 @@ These commands work in print mode too:
 pi -p "/debug-python my code crashes on line 42"
 ```
 
-The model switches, skill injects, agent responds, and output prints to stdout. Useful for scripting or piping to other tools.
+The model switches, a skill context message is injected, the agent responds, and output prints to stdout. Useful for scripting or piping to other tools.
 
 ## Limitations
 
 - Prompt files are reloaded on session start and whenever an extension-owned prompt command runs. If you add a brand-new prompt file while already inside a session, run another extension-owned command such as `/chain-prompts`, start a new session, or reload pi so the new slash command is registered.
 - Model restore state is in-memory. Closing pi mid-response loses restore state.
-- Chain steps must reference templates with a `model` field. Chain templates themselves use `chain` and do not execute their own body.
+- Model-less templates are only managed by this extension when they use extension features (for example `skill`, `thinking`, loop flags, or inline `<if-model ...>`). Plain prompt templates without extension features stay with pi's default prompt loader to avoid command conflicts.
+- In chains, model-less steps inherit the chain-start model snapshot, not the immediately previous step model. This is intentional for deterministic behavior.
 - The `run-prompt` tool must be explicitly enabled with `/prompt-tool on` before the agent can use it.

package/args.ts

@@ -17,6 +17,7 @@ export function extractLoopCount(argsString: string): LoopExtraction | null {
 	let fresh = false;
 	let noConverge = false;
 	const tokensToRemove: Array<{ start: number; end: number }> = [];
+	const loopTokenRanges: Array<{ start: number; end: number }> = [];
 
 	let i = 0;
 	while (i < argsString.length) {
@@ -39,45 +40,46 @@ export function extractLoopCount(argsString: string): LoopExtraction | null {
 		while (i < argsString.length && !/\s/.test(argsString[i])) i++;
 		const token = argsString.slice(tokenStart, i);
 
-		if (!loopFound && (token === "--loop" || token.startsWith("--loop="))) {
-			if (token.startsWith("--loop=")) {
-				const value = token.slice("--loop=".length);
-				if (/^\d+$/.test(value)) {
-					const parsed = parseInt(value, 10);
-					if (parsed >= 1 && parsed <= 999) {
-						loopFound = true;
-						loopCount = parsed;
-						tokensToRemove.push({ start: tokenStart, end: i });
-					}
+		if (token.startsWith("--loop=")) {
+			loopTokenRanges.push({ start: tokenStart, end: i });
+			const value = token.slice("--loop=".length);
+			if (/^\d+$/.test(value)) {
+				const parsed = parseInt(value, 10);
+				if (parsed >= 1 && parsed <= 999 && !loopFound) {
+					loopFound = true;
+					loopCount = parsed;
 				}
-			} else {
-				let lookahead = i;
-				while (lookahead < argsString.length && /\s/.test(argsString[lookahead])) lookahead++;
-
-				if (lookahead < argsString.length && argsString[lookahead] !== '"' && argsString[lookahead] !== "'") {
-					const nextTokenStart = lookahead;
-					while (lookahead < argsString.length && !/\s/.test(argsString[lookahead])) lookahead++;
-					const nextToken = argsString.slice(nextTokenStart, lookahead);
-
-					if (/^\d+$/.test(nextToken)) {
-						const parsed = parseInt(nextToken, 10);
-						if (parsed >= 1 && parsed <= 999) {
-							loopFound = true;
-							loopCount = parsed;
-							tokensToRemove.push({ start: tokenStart, end: i }, { start: nextTokenStart, end: lookahead });
-							i = lookahead;
-						}
-					} else {
+			}
+			continue;
+		}
+
+		if (token === "--loop") {
+			let lookahead = i;
+			while (lookahead < argsString.length && /\s/.test(argsString[lookahead])) lookahead++;
+
+			if (lookahead < argsString.length && argsString[lookahead] !== '"' && argsString[lookahead] !== "'") {
+				const nextTokenStart = lookahead;
+				while (lookahead < argsString.length && !/\s/.test(argsString[lookahead])) lookahead++;
+				const nextToken = argsString.slice(nextTokenStart, lookahead);
+
+				if (/^\d+$/.test(nextToken)) {
+					loopTokenRanges.push({ start: tokenStart, end: i }, { start: nextTokenStart, end: lookahead });
+					const parsed = parseInt(nextToken, 10);
+					if (parsed >= 1 && parsed <= 999 && !loopFound) {
 						loopFound = true;
-						loopCount = null;
-						tokensToRemove.push({ start: tokenStart, end: i });
+						loopCount = parsed;
 					}
-				} else {
-					loopFound = true;
-					loopCount = null;
-					tokensToRemove.push({ start: tokenStart, end: i });
+					i = lookahead;
+					continue;
 				}
 			}
+
+			loopTokenRanges.push({ start: tokenStart, end: i });
+			if (!loopFound) {
+				loopFound = true;
+				loopCount = null;
+			}
+			continue;
 		}
 
 		if (token === "--fresh") {
@@ -91,15 +93,16 @@ export function extractLoopCount(argsString: string): LoopExtraction | null {
 		}
 	}
 
-	if (loopCount === null && !loopFound) return null;
+	if (!loopFound) return null;
 
-	tokensToRemove.sort((a, b) => b.start - a.start);
+	const allRanges = [...tokensToRemove, ...loopTokenRanges];
+	allRanges.sort((a, b) => b.start - a.start);
 	let cleaned = argsString;
-	for (const { start, end } of tokensToRemove) {
+	for (const { start, end } of allRanges) {
 		cleaned = cleaned.slice(0, start) + cleaned.slice(end);
 	}
 
-	const converge = loopFound && loopCount === null ? true : !noConverge;
+	const converge = loopCount === null ? true : !noConverge;
 	return { args: cleaned.trim(), loopCount, fresh, converge };
 }
 
@@ -227,6 +230,7 @@ export function substituteArgs(content: string, args: string[]): string {
 	const allArgs = args.join(" ");
 	result = result.replace(/\$ARGUMENTS/g, allArgs);
 	result = result.replace(/\$@/g, allArgs);
+	result = result.replace(/@\$/g, allArgs);
 
 	return result;
 }

package/chain-parser.ts

@@ -76,19 +76,20 @@ function scanSegmentTokens(segment: string): SegmentToken[] {
 
 function extractStepLoopCount(segment: string): { cleanedSegment: string; loopCount?: number } {
 	const tokens = scanSegmentTokens(segment);
+	const loopTokenRanges: Array<{ start: number; end: number }> = [];
+	let loopCount: number | undefined;
 
 	for (let i = 1; i < tokens.length; i++) {
 		const token = tokens[i];
 		if (token.quoted) continue;
 
 		if (token.value.startsWith("--loop=")) {
+			loopTokenRanges.push({ start: token.start, end: token.end });
 			const value = token.value.slice("--loop=".length);
-			if (/^\d+$/.test(value)) {
-				const parsed = parseInt(value, 10);
-				if (parsed >= 1 && parsed <= 999) {
-					const cleanedSegment = `${segment.slice(0, token.start)}${segment.slice(token.end)}`.trim();
-					return { cleanedSegment, loopCount: parsed };
-				}
+			if (!/^\d+$/.test(value)) continue;
+			const parsed = parseInt(value, 10);
+			if (parsed >= 1 && parsed <= 999 && loopCount === undefined) {
+				loopCount = parsed;
 			}
 			continue;
 		}
@@ -96,16 +97,28 @@ function extractStepLoopCount(segment: string): { cleanedSegment: string; loopCo
 		if (token.value === "--loop" && i + 1 < tokens.length) {
 			const next = tokens[i + 1];
 			if (!next.quoted && /^\d+$/.test(next.value)) {
+				loopTokenRanges.push({ start: token.start, end: token.end }, { start: next.start, end: next.end });
 				const parsed = parseInt(next.value, 10);
-				if (parsed >= 1 && parsed <= 999) {
-					const cleanedSegment = `${segment.slice(0, token.start)}${segment.slice(next.end)}`.trim();
-					return { cleanedSegment, loopCount: parsed };
+				if (parsed >= 1 && parsed <= 999 && loopCount === undefined) {
+					loopCount = parsed;
 				}
+				i++;
+				continue;
 			}
 		}
 	}
 
-	return { cleanedSegment: segment };
+	if (loopCount === undefined || loopTokenRanges.length === 0) {
+		return { cleanedSegment: segment };
+	}
+
+	loopTokenRanges.sort((a, b) => b.start - a.start);
+	let cleanedSegment = segment;
+	for (const { start, end } of loopTokenRanges) {
+		cleanedSegment = `${cleanedSegment.slice(0, start)}${cleanedSegment.slice(end)}`;
+	}
+
+	return { cleanedSegment: cleanedSegment.trim(), loopCount };
 }
 
 export function parseChainSteps(args: string): ParsedChainSteps {

package/index.ts

@@ -22,11 +22,29 @@ interface FreshCollapse {
 	totalIterations: number | null;
 }
 
+interface PendingSkillMessage {
+	customType: "skill-loaded";
+	content: string;
+	display: true;
+	details: SkillLoadedDetails;
+}
+
+type SkillMessageResolution =
+	| { kind: "none" }
+	| { kind: "ready"; message: PendingSkillMessage }
+	| { kind: "error"; error: string };
+
+interface ExecutionErrorState {
+	hasError: boolean;
+	error: unknown;
+}
+
 export default function promptModelExtension(pi: ExtensionAPI) {
 	let prompts = new Map<string, PromptWithModel>();
 	let previousModel: Model<any> | undefined;
 	let previousThinking: ThinkingLevel | undefined;
-	let pendingSkill: { name: string; cwd: string } | undefined;
+	let pendingSkillMessage: PendingSkillMessage | undefined;
+	let runtimeModel: Model<any> | undefined;
 	let chainActive = false;
 	let loopState: LoopState | null = null;
 	let freshCollapse: FreshCollapse | null = null;
@@ -49,6 +67,10 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 		return a.provider === b.provider && a.id === b.id;
 	}
 
+	function getCurrentModel(ctx: Pick<ExtensionContext, "model">): Model<any> | undefined {
+		return runtimeModel ?? ctx.model;
+	}
+
 	pi.registerMessageRenderer<SkillLoadedDetails>("skill-loaded", renderSkillLoaded);
 
 	function registerPromptCommand(name: string) {
@@ -76,6 +98,74 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 		lastDiagnostics = fingerprint;
 	}
 
+	function consumePendingSkillMessage() {
+		if (!pendingSkillMessage) return undefined;
+		const message = pendingSkillMessage;
+		pendingSkillMessage = undefined;
+		return message;
+	}
+
+	function normalizeSkillName(skillName: string): string {
+		return skillName.startsWith("skill:") ? skillName.slice("skill:".length) : skillName;
+	}
+
+	function isPathResolvableSkillName(skillName: string): boolean {
+		if (skillName === "." || skillName === "..") return false;
+		if (skillName.includes("/")) return false;
+		if (skillName.includes("\\")) return false;
+		return true;
+	}
+
+	function resolveRegisteredSkillPath(skillName: string): string | undefined {
+		const normalizedSkillName = normalizeSkillName(skillName);
+		if (!normalizedSkillName) return undefined;
+		const candidates = new Set([normalizedSkillName, `skill:${normalizedSkillName}`]);
+
+		for (const command of pi.getCommands()) {
+			if (command.source !== "skill") continue;
+			if (!command.path) continue;
+			if (!candidates.has(command.name)) continue;
+			return command.path;
+		}
+
+		return undefined;
+	}
+
+	function resolveSkillMessage(skillName: string | undefined, cwd: string): SkillMessageResolution {
+		if (!skillName) {
+			return { kind: "none" };
+		}
+
+		const normalizedSkillName = normalizeSkillName(skillName);
+		if (!normalizedSkillName) {
+			return { kind: "error", error: `Skill "${skillName}" not found` };
+		}
+
+		const skillPath =
+			resolveRegisteredSkillPath(skillName) ?? (isPathResolvableSkillName(normalizedSkillName) ? resolveSkillPath(normalizedSkillName, cwd) : undefined);
+		if (!skillPath) {
+			return { kind: "error", error: `Skill "${skillName}" not found` };
+		}
+
+		try {
+			const skillContent = readSkillContent(skillPath);
+			return {
+				kind: "ready",
+				message: {
+					customType: "skill-loaded",
+					content: `<skill name="${normalizedSkillName}">\n${skillContent}\n</skill>`,
+					display: true,
+					details: { skillName: normalizedSkillName, skillContent, skillPath },
+				},
+			};
+		} catch (error) {
+			return {
+				kind: "error",
+				error: `Failed to read skill "${skillName}": ${error instanceof Error ? error.message : String(error)}`,
+			};
+		}
+	}
+
 	async function waitForTurnStart(ctx: ExtensionContext) {
 		while (ctx.isIdle()) {
 			await new Promise((resolve) => setTimeout(resolve, 10));
@@ -90,19 +180,19 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 		currentThinking?: ThinkingLevel,
 	) {
 		const restoredParts: string[] = [];
-		const shouldRestoreModel = originalModel !== undefined && !sameModel(originalModel, currentModel);
 		const shouldRestoreThinking =
 			originalThinking !== undefined && (currentThinking === undefined || currentThinking !== originalThinking);
 
-		if (shouldRestoreModel && originalModel) {
+		if (originalModel && !sameModel(originalModel, currentModel)) {
 			const restoredModel = await pi.setModel(originalModel);
 			if (restoredModel) {
+				runtimeModel = originalModel;
 				restoredParts.push(originalModel.id);
 			} else {
 				notify(ctx, `Failed to restore model ${originalModel.provider}/${originalModel.id}`, "error");
 			}
 		}
-		if (shouldRestoreThinking && originalThinking !== undefined) {
+		if (shouldRestoreThinking) {
 			restoredParts.push(`thinking:${originalThinking}`);
 			pi.setThinkingLevel(originalThinking);
 		}
@@ -111,6 +201,63 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 		}
 	}
 
+	async function restoreAfterExecution(
+		ctx: ExtensionContext,
+		shouldRestore: boolean,
+		originalModel: Model<any> | undefined,
+		originalThinking: ThinkingLevel | undefined,
+		currentModel: Model<any> | undefined,
+		currentThinking: ThinkingLevel | undefined,
+		errorState: ExecutionErrorState,
+		phase: "loop" | "chain",
+	): Promise<ExecutionErrorState> {
+		if (!shouldRestore) return errorState;
+
+		try {
+			await restoreSessionState(ctx, originalModel, originalThinking, currentModel, currentThinking);
+		} catch (error) {
+			if (errorState.hasError) {
+				notify(
+					ctx,
+					`Failed to restore session state after ${phase} error: ${error instanceof Error ? error.message : String(error)}`,
+					"error",
+				);
+				return errorState;
+			}
+			return { hasError: true, error };
+		}
+
+		return errorState;
+	}
+
+	function notifyLoopCompletion(
+		ctx: ExtensionContext,
+		completedIterations: number,
+		totalIterations: number | null,
+		effectiveMax: number,
+		converged: boolean,
+		requireMultipleIterations: boolean,
+	) {
+		if (converged) {
+			const convergedLabel = totalIterations !== null ? `${completedIterations}/${totalIterations}` : `${completedIterations}`;
+			notify(ctx, `Loop converged at ${convergedLabel} (no changes)`, "info");
+			return;
+		}
+
+		if (completedIterations === 0) return;
+		if (requireMultipleIterations && effectiveMax <= 1) return;
+
+		if (totalIterations !== null) {
+			notify(ctx, `Loop finished: ${completedIterations}/${totalIterations} iterations`, "info");
+			return;
+		}
+		if (completedIterations === effectiveMax) {
+			notify(ctx, `Loop finished: ${completedIterations} iterations (cap reached)`, "info");
+			return;
+		}
+		notify(ctx, `Loop finished: ${completedIterations} iterations`, "info");
+	}
+
 	function updateLoopStatus(ctx: ExtensionContext) {
 		if (!ctx.hasUI) return;
 		if (loopState) {
@@ -152,8 +299,10 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 			return;
 		}
 
-		const savedModel = ctx.model;
+		const savedModel = getCurrentModel(ctx);
 		const savedThinking = pi.getThinkingLevel();
+		let currentModel = savedModel;
+		let currentThinking = savedThinking;
 		const shouldRestore = initialPrompt.restore;
 		const useFresh = freshFlag || initialPrompt.fresh === true;
 		const effectiveMax = totalIterations ?? UNLIMITED_LOOP_CAP;
@@ -166,6 +315,7 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 		updateLoopStatus(ctx);
 		let completedIterations = 0;
 		let converged = false;
+		let loopErrorState: ExecutionErrorState = { hasError: false, error: undefined };
 
 		try {
 			for (let i = 0; i < effectiveMax; i++) {
@@ -181,7 +331,7 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 					break;
 				}
 
-				const prepared = await preparePromptExecution(prompt, parseCommandArgs(cleanedArgs), ctx.model, ctx.modelRegistry);
+				const prepared = await preparePromptExecution(prompt, parseCommandArgs(cleanedArgs), currentModel, ctx.modelRegistry);
 				if (!prepared) {
 					notify(ctx, `No available model from: ${prompt.models.join(", ")}`, "error");
 					break;
@@ -195,19 +345,29 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 					notify(ctx, prepared.warning, "warning");
 				}
 
+				const skillResolution = resolveSkillMessage(prompt.skill, ctx.cwd);
+				if (skillResolution.kind === "error") {
+					notify(ctx, skillResolution.error, "error");
+					break;
+				}
+
 				if (!prepared.selectedModel.alreadyActive) {
 					const switched = await pi.setModel(prepared.selectedModel.model);
 					if (!switched) {
 						notify(ctx, `Failed to switch to model ${prepared.selectedModel.model.provider}/${prepared.selectedModel.model.id}`, "error");
 						break;
 					}
+					runtimeModel = prepared.selectedModel.model;
 				}
+				currentModel = prepared.selectedModel.model;
+				currentThinking = pi.getThinkingLevel();
 
 				if (prompt.thinking) {
 					pi.setThinkingLevel(prompt.thinking);
+					currentThinking = pi.getThinkingLevel();
 				}
 
-				pendingSkill = prompt.skill ? { name: prompt.skill, cwd: ctx.cwd } : undefined;
+				pendingSkillMessage = skillResolution.kind === "ready" ? skillResolution.message : undefined;
 				const iterationStartId = ctx.sessionManager.getLeafId();
 
 				pi.sendUserMessage(prepared.content);
@@ -230,29 +390,33 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 					}
 				}
 			}
+		} catch (error) {
+			loopErrorState = { hasError: true, error };
 		} finally {
+			loopErrorState = await restoreAfterExecution(
+				ctx,
+				shouldRestore,
+				savedModel,
+				savedThinking,
+				currentModel,
+				currentThinking,
+				loopErrorState,
+				"loop",
+			);
+
 			loopState = null;
-			pendingSkill = undefined;
+			pendingSkillMessage = undefined;
 			freshCollapse = null;
 			accumulatedSummaries = [];
 			updateLoopStatus(ctx);
 
-			if (converged) {
-				const convergedLabel = totalIterations !== null ? `${completedIterations}/${totalIterations}` : `${completedIterations}`;
-				notify(ctx, `Loop converged at ${convergedLabel} (no changes)`, "info");
-			} else if (completedIterations > 0) {
-				if (totalIterations !== null) {
-					notify(ctx, `Loop finished: ${completedIterations}/${totalIterations} iterations`, "info");
-				} else if (completedIterations === effectiveMax) {
-					notify(ctx, `Loop finished: ${completedIterations} iterations (cap reached)`, "info");
-				} else {
-					notify(ctx, `Loop finished: ${completedIterations} iterations`, "info");
-				}
+			if (!loopErrorState.hasError) {
+				notifyLoopCompletion(ctx, completedIterations, totalIterations, effectiveMax, converged, false);
 			}
+		}
 
-			if (shouldRestore) {
-				await restoreSessionState(ctx, savedModel, savedThinking, ctx.model, pi.getThinkingLevel());
-			}
+		if (loopErrorState.hasError) {
+			throw loopErrorState.error;
 		}
 	}
 
@@ -273,7 +437,9 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 			}
 
 			for (const step of steps) {
-				if (prompts.get(step.name)?.chain) {
+				const stepPrompt = prompts.get(step.name);
+				if (!stepPrompt) continue;
+				if (stepPrompt.chain) {
 					notify(ctx, `Step "${step.name}" is a chain template. Chain nesting is not supported.`, "error");
 					return false;
 				}
@@ -284,12 +450,13 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 
 		if (!validateChainSteps()) return;
 
-		const originalModel = ctx.model;
+		const originalModel = getCurrentModel(ctx);
+		const chainInheritedModel = getCurrentModel(ctx);
 		const originalThinking = pi.getThinkingLevel();
 		let currentModel = originalModel;
 		let currentThinking = originalThinking;
 		chainActive = true;
-		pendingSkill = undefined;
+		pendingSkillMessage = undefined;
 		const effectiveMax = totalIterations ?? UNLIMITED_LOOP_CAP;
 		const isUnlimited = totalIterations === null;
 		const useConverge = isUnlimited ? true : converge;
@@ -298,6 +465,7 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 		const chainStepNames = steps.map((step) => step.name).join(" -> ");
 		let completedIterations = 0;
 		let converged = false;
+		let chainErrorState: ExecutionErrorState = { hasError: false, error: undefined };
 		if (effectiveMax > 1) {
 			loopState = { currentIteration: 1, totalIterations };
 			accumulatedSummaries = [];
@@ -347,7 +515,9 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 							const iterSuffix = stepLoop > 1 ? ` (iter ${stepIteration + 1}/${stepLoop})` : "";
 							notify(ctx, `${loopPrefix}Step ${stepNumber}/${templates.length}: ${template.name}${iterSuffix} ${buildPromptCommandDescription(template)}`, "info");
 
-							const prepared = await preparePromptExecution(template, effectiveArgs, currentModel, ctx.modelRegistry);
+							const prepared = await preparePromptExecution(template, effectiveArgs, currentModel, ctx.modelRegistry, {
+								inheritedModel: chainInheritedModel,
+							});
 							if (!prepared) {
 								notify(
 									ctx,
@@ -367,6 +537,13 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 								notify(ctx, prepared.warning, "warning");
 							}
 
+							const skillResolution = resolveSkillMessage(template.skill, ctx.cwd);
+							if (skillResolution.kind === "error") {
+								notify(ctx, `Step ${stepNumber}/${templates.length} failed: ${skillResolution.error}`, "error");
+								aborted = true;
+								break;
+							}
+
 							if (!prepared.selectedModel.alreadyActive) {
 								const switched = await pi.setModel(prepared.selectedModel.model);
 								if (!switched) {
@@ -378,6 +555,7 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 									aborted = true;
 									break;
 								}
+								runtimeModel = prepared.selectedModel.model;
 							}
 
 							currentModel = prepared.selectedModel.model;
@@ -386,7 +564,7 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 								pi.setThinkingLevel(template.thinking);
 								currentThinking = pi.getThinkingLevel();
 							}
-							pendingSkill = template.skill ? { name: template.skill, cwd: ctx.cwd } : undefined;
+							pendingSkillMessage = skillResolution.kind === "ready" ? skillResolution.message : undefined;
 
 							const stepIterationStartId = ctx.sessionManager.getLeafId();
 							pi.sendUserMessage(prepared.content);
@@ -426,30 +604,35 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 				}
 			}
 
-			if (shouldRestore) {
-				await restoreSessionState(ctx, originalModel, originalThinking, currentModel, currentThinking);
-			}
+		} catch (error) {
+			chainErrorState = { hasError: true, error };
 		} finally {
-			pendingSkill = undefined;
+			chainErrorState = await restoreAfterExecution(
+				ctx,
+				shouldRestore,
+				originalModel,
+				originalThinking,
+				currentModel,
+				currentThinking,
+				chainErrorState,
+				"chain",
+			);
+
+			pendingSkillMessage = undefined;
 			chainActive = false;
 			loopState = null;
 			freshCollapse = null;
 			accumulatedSummaries = [];
 			updateLoopStatus(ctx);
 
-			if (converged) {
-				const convergedLabel = totalIterations !== null ? `${completedIterations}/${totalIterations}` : `${completedIterations}`;
-				notify(ctx, `Loop converged at ${convergedLabel} (no changes)`, "info");
-			} else if (effectiveMax > 1 && completedIterations > 0) {
-				if (totalIterations !== null) {
-					notify(ctx, `Loop finished: ${completedIterations}/${totalIterations} iterations`, "info");
-				} else if (completedIterations === effectiveMax) {
-					notify(ctx, `Loop finished: ${completedIterations} iterations (cap reached)`, "info");
-				} else {
-					notify(ctx, `Loop finished: ${completedIterations} iterations`, "info");
-				}
+			if (!chainErrorState.hasError) {
+				notifyLoopCompletion(ctx, completedIterations, totalIterations, effectiveMax, converged, true);
 			}
 		}
+
+		if (chainErrorState.hasError) {
+			throw chainErrorState.error;
+		}
 	}
 
 	async function runPromptCommand(name: string, args: string, ctx: ExtensionCommandContext) {
@@ -514,7 +697,7 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 			return;
 		}
 
-		const savedModel = ctx.model;
+		const savedModel = getCurrentModel(ctx);
 		const savedThinking = pi.getThinkingLevel();
 		const prepared = await preparePromptExecution(prompt, parseCommandArgs(args), savedModel, ctx.modelRegistry);
 		if (!prepared) {
@@ -530,12 +713,19 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 			notify(ctx, prepared.warning, "warning");
 		}
 
+		const skillResolution = resolveSkillMessage(prompt.skill, ctx.cwd);
+		if (skillResolution.kind === "error") {
+			notify(ctx, skillResolution.error, "error");
+			return;
+		}
+
 		if (!prepared.selectedModel.alreadyActive) {
 			const switched = await pi.setModel(prepared.selectedModel.model);
 			if (!switched) {
 				notify(ctx, `Failed to switch to model ${prepared.selectedModel.model.provider}/${prepared.selectedModel.model.id}`, "error");
 				return;
 			}
+			runtimeModel = prepared.selectedModel.model;
 		}
 
 		if (prompt.restore && !prepared.selectedModel.alreadyActive) {
@@ -548,26 +738,36 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 			}
 			pi.setThinkingLevel(prompt.thinking);
 		}
-		pendingSkill = prompt.skill ? { name: prompt.skill, cwd: ctx.cwd } : undefined;
+		pendingSkillMessage = skillResolution.kind === "ready" ? skillResolution.message : undefined;
 
 		pi.sendUserMessage(prepared.content);
 		await waitForTurnStart(ctx);
 		await ctx.waitForIdle();
 	}
 
-	pi.on("session_start", async (_event, ctx) => {
+	function resetSessionScopedState(ctx: ExtensionContext) {
 		storedCommandCtx = null;
+		pendingSkillMessage = undefined;
+		previousModel = undefined;
+		previousThinking = undefined;
+		runtimeModel = ctx.model;
 		toolManager.clearQueue();
 		refreshPrompts(ctx.cwd, ctx);
+	}
+
+	pi.on("session_start", async (_event, ctx) => {
+		resetSessionScopedState(ctx);
 	});
 
 	pi.on("session_switch", async (_event, ctx) => {
-		storedCommandCtx = null;
-		toolManager.clearQueue();
-		refreshPrompts(ctx.cwd, ctx);
+		resetSessionScopedState(ctx);
+	});
+
+	pi.on("model_select", async (event) => {
+		runtimeModel = event.model;
 	});
 
-	pi.on("before_agent_start", async (event, ctx) => {
+	pi.on("before_agent_start", async (event) => {
 		let systemPrompt = event.systemPrompt;
 
 		if (toolManager.isEnabled() && !loopState && !chainActive) {
@@ -586,38 +786,22 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 			systemPrompt += `\n\nYou are on ${iterText} of the same prompt. Previous iterations and their results are visible in the conversation above. Build on that work — focus on what remains to improve.`;
 		}
 
-		if (pendingSkill) {
-			const { name: skillName, cwd } = pendingSkill;
-			pendingSkill = undefined;
-
-			const skillPath = resolveSkillPath(skillName, cwd);
-			if (skillPath) {
-				try {
-					const skillContent = readSkillContent(skillPath);
-					pi.sendMessage<SkillLoadedDetails>({
-						customType: "skill-loaded",
-						content: `Loaded skill: ${skillName}`,
-						display: true,
-						details: { skillName, skillContent, skillPath },
-					});
-					systemPrompt += `\n\n<skill name="${skillName}">\n${skillContent}\n</skill>`;
-				} catch (error) {
-					notify(ctx, `Failed to read skill "${skillName}": ${error instanceof Error ? error.message : String(error)}`, "error");
-				}
-			} else {
-				notify(ctx, `Skill "${skillName}" not found`, "error");
-			}
-		}
+		const skillMessage = consumePendingSkillMessage();
+		const hasSystemPromptOverride = systemPrompt !== event.systemPrompt;
+		if (!hasSystemPromptOverride && !skillMessage) return;
 
-		if (systemPrompt !== event.systemPrompt) {
-			return { systemPrompt };
-		}
+		return {
+			...(hasSystemPromptOverride ? { systemPrompt } : {}),
+			...(skillMessage ? { message: skillMessage } : {}),
+		};
 	});
 
 	pi.on("agent_end", async (_event, ctx) => {
 		if (chainActive) return;
 		if (loopState) return;
 
+		runtimeModel = ctx.model;
+
 		const restoreModel = previousModel;
 		const restoreThinking = previousThinking;
 		previousModel = undefined;
@@ -625,7 +809,7 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 
 		const restoreFn = async () => {
 			if (restoreModel || restoreThinking !== undefined) {
-				await restoreSessionState(ctx, restoreModel, restoreThinking, ctx.model, pi.getThinkingLevel());
+				await restoreSessionState(ctx, restoreModel, restoreThinking, getCurrentModel(ctx), pi.getThinkingLevel());
 			}
 		};
 		const processed = await toolManager.processQueue(ctx, restoreFn);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-prompt-template-model",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "Prompt template model selector extension for pi coding agent",
   "author": "Nico Bailon",

package/prompt-execution.ts

@@ -16,14 +16,40 @@ export interface EmptyPromptAbort {
 	warning?: string;
 }
 
+interface PromptExecutionOptions {
+	inheritedModel?: Model<any>;
+}
+
+function sameModel(a: Model<any> | undefined, b: Model<any> | undefined): boolean {
+	if (!a || !b) return a === b;
+	return a.provider === b.provider && a.id === b.id;
+}
+
 export async function preparePromptExecution(
 	prompt: Pick<PromptWithModel, "name" | "content" | "models">,
 	args: string[],
 	currentModel: Model<any> | undefined,
 	modelRegistry: Pick<ModelRegistry, "find" | "getAll" | "getAvailable" | "getApiKey" | "isUsingOAuth">,
+	options?: PromptExecutionOptions,
 ): Promise<PreparedPromptExecution | EmptyPromptAbort | undefined> {
-	const selectedModel = await selectModelCandidate(prompt.models, currentModel, modelRegistry);
+	const selectedModel =
+		prompt.models.length === 0
+			? (() => {
+				const hasInheritedModel = options !== undefined && Object.hasOwn(options, "inheritedModel");
+				const inheritedModel = hasInheritedModel ? options.inheritedModel : currentModel;
+				if (!inheritedModel) {
+					return {
+						message: `Prompt \`${prompt.name}\` has no \`model\` configured and there is no active session model to inherit.`,
+					};
+				}
+				return {
+					model: inheritedModel,
+					alreadyActive: sameModel(currentModel, inheritedModel),
+				};
+			})()
+			: await selectModelCandidate(prompt.models, currentModel, modelRegistry);
 	if (!selectedModel) return undefined;
+	if ("message" in selectedModel) return selectedModel;
 
 	const rendered = renderTemplateConditionals(prompt.content, getResolvedModelRef(selectedModel.model), prompt.name);
 	const content = substituteArgs(rendered.content, args);

package/prompt-loader.ts

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import type { ThinkingLevel } from "@mariozechner/pi-agent-core";
 import { parseFrontmatter } from "@mariozechner/pi-coding-agent";
 
@@ -436,8 +436,10 @@ function loadPromptsWithModelFromDir(
 				if (!frontmatter) continue;
 				const { body } = parsed;
 				const chain = normalizeChain(frontmatter.chain, fullPath, source, diagnostics);
-				const models = chain ? [] : normalizeModelSpecs(frontmatter.model, fullPath, source, diagnostics);
-				if (!chain && !models) continue;
+				const hasModelField = Object.hasOwn(frontmatter, "model");
+				const parsedModels = chain ? [] : normalizeModelSpecs(frontmatter.model, fullPath, source, diagnostics);
+				if (!chain && hasModelField && !parsedModels) continue;
+				const models = chain ? [] : (parsedModels ?? []);
 
 				const name = entry.name.slice(0, -3);
 				if (RESERVED_COMMAND_NAMES.has(name)) {
@@ -459,6 +461,17 @@ function loadPromptsWithModelFromDir(
 				const fresh = normalizeFresh(frontmatter.fresh, fullPath, source, diagnostics);
 				const loop = normalizeLoop(frontmatter.loop, fullPath, source, diagnostics);
 				const converge = normalizeConverge(frontmatter.converge, fullPath, source, diagnostics);
+				const hasModelConditionalDirectives = /<if-model(?:\s|>)|<else(?:\s|>)|<\/if-model\s*>|<\/else(?:\s|>)/.test(body);
+				const hasExtensionSpecificConfig =
+					skill !== undefined ||
+					thinking !== undefined ||
+					fresh === true ||
+					loop !== undefined ||
+					converge === false ||
+					hasModelConditionalDirectives;
+				if (!chain && !hasModelField && !hasExtensionSpecificConfig) {
+					continue;
+				}
 
 				prompts.push({
 					name,
@@ -550,7 +563,7 @@ export function buildPromptCommandDescription(prompt: PromptWithModel): string {
 		const details = `[chain: ${prompt.chain}] ${sourceLabel}`;
 		return prompt.description ? `${prompt.description} ${details}` : details;
 	}
-	const modelLabel = prompt.models.map((model) => model.split("/").pop() || model).join("|");
+	const modelLabel = prompt.models.length > 0 ? prompt.models.map((model) => model.split("/").pop() || model).join("|") : "current";
 	const skillLabel = prompt.skill ? ` +${prompt.skill}` : "";
 	const thinkingLabel = prompt.thinking ? ` ${prompt.thinking}` : "";
 	const loopLabel = prompt.loop ? ` loop:${prompt.loop}` : "";
@@ -558,16 +571,53 @@ export function buildPromptCommandDescription(prompt: PromptWithModel): string {
 	return prompt.description ? `${prompt.description} ${details}` : details;
 }
 
-export function resolveSkillPath(skillName: string, cwd: string): string | undefined {
-	const projectPath = resolve(cwd, ".pi", "skills", skillName, "SKILL.md");
-	if (existsSync(projectPath)) return projectPath;
+function getSkillCandidates(baseDir: string, skillName: string): string[] {
+	return [join(baseDir, skillName, "SKILL.md"), join(baseDir, `${skillName}.md`)];
+}
 
-	const userPath = join(homedir(), ".pi", "agent", "skills", skillName, "SKILL.md");
-	if (existsSync(userPath)) return userPath;
+function* walkAncestors(startDir: string, stopDir?: string): Generator<string> {
+	let current = startDir;
+	while (true) {
+		yield current;
+		if (stopDir && current === stopDir) return;
+		const parent = dirname(current);
+		if (parent === current) return;
+		current = parent;
+	}
+}
 
+function findRepoRoot(startDir: string): string | undefined {
+	for (const dir of walkAncestors(startDir)) {
+		if (existsSync(join(dir, ".git"))) return dir;
+	}
 	return undefined;
 }
 
+function findFirstExisting(paths: string[]): string | undefined {
+	for (const path of paths) {
+		if (existsSync(path)) return path;
+	}
+	return undefined;
+}
+
+export function resolveSkillPath(skillName: string, cwd: string): string | undefined {
+	const projectDir = resolve(cwd);
+
+	const projectPiSkill = findFirstExisting(getSkillCandidates(resolve(projectDir, ".pi", "skills"), skillName));
+	if (projectPiSkill) return projectPiSkill;
+
+	const repoRoot = findRepoRoot(projectDir);
+	for (const dir of walkAncestors(projectDir, repoRoot)) {
+		const projectAgentsSkill = findFirstExisting(getSkillCandidates(join(dir, ".agents", "skills"), skillName));
+		if (projectAgentsSkill) return projectAgentsSkill;
+	}
+
+	const globalPiSkill = findFirstExisting(getSkillCandidates(join(homedir(), ".pi", "agent", "skills"), skillName));
+	if (globalPiSkill) return globalPiSkill;
+
+	return findFirstExisting(getSkillCandidates(join(homedir(), ".agents", "skills"), skillName));
+}
+
 export function readSkillContent(skillPath: string): string {
 	const raw = readFileSync(skillPath, "utf-8");
 	return parseFrontmatter(raw).body;