pi-subagents 0.4.1 → 0.5.1

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-01-27
+
+### Fixed
+- Google API compatibility: Use `Type.Any()` for mixed-type unions (`SkillOverride`, `output`, `reads`, `ChainItem`) to avoid unsupported `anyOf`/`const` JSON Schema patterns
+
+## [0.5.0] - 2026-01-27
+
+### Added
+- **Skill support** - Agents can declare skills in frontmatter that get injected into system prompts
+  - Agent frontmatter: `skill: tmux, chrome-devtools` (comma-separated)
+  - Runtime override: `skill: "name"` or `skill: false` to disable all skills
+  - Chain-level skills additive to agent skills, step-level override supported
+  - Skills injected as XML: `<skill name="...">content</skill>` after agent system prompt
+  - Missing skills warn but continue execution (warning shown in result summary)
+- **TUI skill selector** - Press `[s]` to browse and select skills for any step
+  - Multi-select with space bar
+  - Fuzzy search by name or description
+  - Shows skill source (project/user) and description
+  - Project skills (`.pi/skills/`) override user skills (`~/.pi/agent/skills/`)
+- **Skill display** - Skills shown in TUI, progress tracking, summary, artifacts, and async status
+- **Parallel task skills** - Each parallel task can specify its own skills via `skill` parameter
+
+### Fixed
+- **Chain summary formatting** - Fixed extra blank line when no skills are present
+- **Duplicate skill deduplication** - `skill: "foo,foo"` now correctly deduplicates to `["foo"]`
+- **Consistent skill tracking in async mode** - Both chain and single modes now track only resolved skills
+
+## [0.4.1] - 2026-01-26
+
 ### Changed
 - Added `pi-package` keyword for npm discoverability (pi v0.50.0 package system)
 

package/README.md

@@ -11,10 +11,10 @@ https://github.com/user-attachments/assets/702554ec-faaf-4635-80aa-fb5d6e292fd1
 ## Installation
 
 ```bash
-npx pi-subagents
+pi install npm:pi-subagents
 ```
 
-This clones the extension to `~/.pi/agent/extensions/subagent/`. To update, run the same command. To remove:
+To remove:
 
 ```bash
 npx pi-subagents --remove
@@ -22,9 +22,10 @@ npx pi-subagents --remove
 
 ## Features (beyond base)
 
+- **Skill Injection**: Agents declare skills in frontmatter; skills get injected into system prompts
 - **Parallel-in-Chain**: Fan-out/fan-in patterns with `{ parallel: [...] }` steps within chains
 - **Chain Clarification TUI**: Interactive preview/edit of chain templates and behaviors before execution
-- **Agent Frontmatter Extensions**: Agents declare default chain behavior (`output`, `defaultReads`, `defaultProgress`)
+- **Agent Frontmatter Extensions**: Agents declare default chain behavior (`output`, `defaultReads`, `defaultProgress`, `skill`)
 - **Chain Artifacts**: Shared directory at `/tmp/pi-chain-runs/{runId}/` for inter-step files
 - **Solo Agent Output**: Agents with `output` write to temp dir and return path to caller
 - **Live Progress Display**: Real-time visibility during sync execution showing current tool, recent output, tokens, and duration
@@ -66,6 +67,7 @@ Single and parallel modes also support the clarify TUI for previewing/editing pa
 - `e` - Edit task/template (all modes)
 - `m` - Select model (all modes)
 - `t` - Select thinking level (all modes)
+- `s` - Select skills (all modes)
 - `w` - Edit writes/output file (single, chain only)
 - `r` - Edit reads list (chain only)
 - `p` - Toggle progress tracking (chain only)
@@ -81,6 +83,13 @@ Single and parallel modes also support the clarify TUI for previewing/editing pa
 - `Enter` - Select level
 - `Esc` - Cancel (keep current level)
 
+*Skill selector mode:*
+- `↑↓` - Navigate skill list
+- `Space` - Toggle skill selection
+- `Enter` - Confirm selection
+- `Esc` - Cancel (keep current skills)
+- Type to filter (fuzzy search by name or description)
+
 *Edit mode (full-screen editor with word wrapping):*
 - `Esc` - Save changes and exit
 - `Ctrl+C` - Discard changes and exit
@@ -100,6 +109,7 @@ name: scout
 description: Fast codebase recon
 tools: read, grep, find, ls, bash
 model: claude-haiku-4-5
+skill: safe-bash, chrome-devtools  # comma-separated skills to inject
 output: context.md           # writes to {chain_dir}/context.md
 defaultReads: context.md     # comma-separated files to read
 defaultProgress: true        # maintain progress.md
@@ -109,6 +119,44 @@ interactive: true            # (parsed but not enforced in v1)
 
 **Resolution priority:** step override > agent frontmatter > disabled
 
+## Skills
+
+Skills are specialized instructions loaded from SKILL.md files and injected into the agent's system prompt.
+
+**Skill locations:**
+- Project: `.pi/skills/{name}/SKILL.md` (higher priority)
+- User: `~/.pi/agent/skills/{name}/SKILL.md`
+
+**Usage:**
+```typescript
+// Agent with skills from frontmatter
+{ agent: "scout", task: "..." }  // uses agent's default skills
+
+// Override skills at runtime
+{ agent: "scout", task: "...", skill: "tmux, safe-bash" }
+
+// Disable all skills (including agent defaults)
+{ agent: "scout", task: "...", skill: false }
+
+// Chain with chain-level skills (additive to agent skills)
+{ chain: [...], skill: "code-review" }
+
+// Chain step with skill override
+{ chain: [
+  { agent: "scout", skill: "safe-bash" },  // only safe-bash
+  { agent: "worker", skill: false }        // no skills at all
+]}
+```
+
+**Skill injection format:**
+```xml
+<skill name="safe-bash">
+[skill content from SKILL.md, frontmatter stripped]
+</skill>
+```
+
+**Missing skills:** If a skill cannot be found, execution continues with a warning shown in the result summary.
+
 ## Usage
 
 **subagent tool:**
@@ -172,7 +220,8 @@ interactive: true            # (parsed but not enforced in v1)
 | `agent` | string | - | Agent name (single mode) |
 | `task` | string | - | Task string (single mode) |
 | `output` | `string \| false` | agent default | Override output file for single agent |
-| `tasks` | `{agent, task, cwd?}[]` | - | Parallel tasks (sync only) |
+| `skill` | `string \| string[] \| false` | agent default | Override skills (comma-separated string, array, or false to disable) |
+| `tasks` | `{agent, task, cwd?, skill?}[]` | - | Parallel tasks (sync only) |
 | `chain` | ChainItem[] | - | Sequential steps with behavior overrides (see below) |
 | `clarify` | boolean | true (chains) | Show TUI to preview/edit chain; implies sync mode |
 | `agentScope` | `"user" \| "project" \| "both"` | `user` | Agent discovery scope |
@@ -196,6 +245,7 @@ interactive: true            # (parsed but not enforced in v1)
 | `output` | `string \| false` | agent default | Override output filename or disable |
 | `reads` | `string[] \| false` | agent default | Override files to read from chain dir |
 | `progress` | boolean | agent default | Override progress.md tracking |
+| `skill` | `string \| string[] \| false` | agent default | Override skills or disable all |
 
 *Parallel step fields:*
 
@@ -215,6 +265,7 @@ interactive: true            # (parsed but not enforced in v1)
 | `output` | `string \| false` | agent default | Override output (namespaced to parallel-N/M-agent/) |
 | `reads` | `string[] \| false` | agent default | Override files to read |
 | `progress` | boolean | agent default | Override progress tracking |
+| `skill` | `string \| string[] \| false` | agent default | Override skills or disable all |
 
 Status tool:
 
@@ -318,9 +369,17 @@ Legacy events (still emitted):
 ```
 ├── index.ts           # Main extension (registerTool)
 ├── agents.ts          # Agent discovery + frontmatter parsing
+├── skills.ts          # Skill resolution, caching, and discovery
 ├── settings.ts        # Chain behavior resolution, templates, chain dir
 ├── chain-clarify.ts   # TUI component for chain clarification
+├── chain-execution.ts # Chain orchestration (sequential + parallel)
+├── async-execution.ts # Async/background execution support
+├── execution.ts       # Core runSync for single agent execution
+├── render.ts          # TUI rendering (widget, tool result display)
 ├── artifacts.ts       # Artifact management
+├── formatters.ts      # Output formatting utilities
+├── schemas.ts         # TypeBox parameter schemas
+├── utils.ts           # Shared utility functions
 ├── types.ts           # Shared types
 ├── subagent-runner.ts # Async runner
 └── notify.ts          # Async completion notifications

package/agents.ts

@@ -16,6 +16,7 @@ export interface AgentConfig {
 	systemPrompt: string;
 	source: "user" | "project";
 	filePath: string;
+	skills?: string[];
 	// Chain behavior fields
 	output?: string;
 	defaultReads?: string[];
@@ -101,6 +102,12 @@ function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig
 			.map((f) => f.trim())
 			.filter(Boolean);
 
+		const skillStr = frontmatter.skill || frontmatter.skills;
+		const skills = skillStr
+			?.split(",")
+			.map((s) => s.trim())
+			.filter(Boolean);
+
 		agents.push({
 			name: frontmatter.name,
 			description: frontmatter.description,
@@ -109,6 +116,7 @@ function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig
 			systemPrompt: body,
 			source,
 			filePath,
+			skills: skills && skills.length > 0 ? skills : undefined,
 			// Chain behavior fields
 			output: frontmatter.output,
 			defaultReads: defaultReads && defaultReads.length > 0 ? defaultReads : undefined,

package/async-execution.ts

@@ -10,7 +10,8 @@ import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import type { AgentConfig } from "./agents.js";
-import { isParallelStep, type ChainStep, type SequentialStep } from "./settings.js";
+import { isParallelStep, resolveStepBehavior, type ChainStep, type SequentialStep, type StepOverrides } from "./settings.js";
+import { buildSkillInjection, normalizeSkillInput, resolveSkills } from "./skills.js";
 import {
 	type ArtifactConfig,
 	type Details,
@@ -44,6 +45,7 @@ export interface AsyncChainParams {
 	artifactConfig: ArtifactConfig;
 	shareEnabled: boolean;
 	sessionRoot?: string;
+	chainSkills?: string[];
 }
 
 export interface AsyncSingleParams {
@@ -57,6 +59,7 @@ export interface AsyncSingleParams {
 	artifactConfig: ArtifactConfig;
 	shareEnabled: boolean;
 	sessionRoot?: string;
+	skills?: string[];
 }
 
 export interface AsyncExecutionResult {
@@ -99,6 +102,7 @@ export function executeAsyncChain(
 	params: AsyncChainParams,
 ): AsyncExecutionResult {
 	const { chain, agents, ctx, cwd, maxOutput, artifactsDir, artifactConfig, shareEnabled, sessionRoot } = params;
+	const chainSkills = params.chainSkills ?? [];
 	
 	// Async mode doesn't support parallel steps (v1 limitation)
 	const hasParallelInChain = chain.some(isParallelStep);
@@ -129,8 +133,19 @@ export function executeAsyncChain(
 		fs.mkdirSync(asyncDir, { recursive: true });
 	} catch {}
 
-	const steps = seqSteps.map((s, i) => {
+	const steps = seqSteps.map((s) => {
 		const a = agents.find((x) => x.name === s.agent)!;
+		const stepSkillInput = normalizeSkillInput(s.skill);
+		const stepOverrides: StepOverrides = { skills: stepSkillInput };
+		const behavior = resolveStepBehavior(a, stepOverrides, chainSkills);
+		const skillNames = behavior.skills === false ? [] : behavior.skills;
+		const { resolved: resolvedSkills } = resolveSkills(skillNames, ctx.cwd);
+
+		let systemPrompt = a.systemPrompt?.trim() || null;
+		if (resolvedSkills.length > 0) {
+			const injection = buildSkillInjection(resolvedSkills);
+			systemPrompt = systemPrompt ? `${systemPrompt}\n\n${injection}` : injection;
+		}
 		return {
 			agent: s.agent,
 			// First step validated to have task; others default to {previous} (replaced by runner)
@@ -138,7 +153,9 @@ export function executeAsyncChain(
 			cwd: s.cwd,
 			model: a.model,
 			tools: a.tools,
-			systemPrompt: a.systemPrompt?.trim() || null,
+			systemPrompt,
+			// Only track skills that were actually resolved (consistent with single mode)
+			skills: resolvedSkills.map((r) => r.name),
 		};
 	});
 
@@ -200,6 +217,13 @@ export function executeAsyncSingle(
 	params: AsyncSingleParams,
 ): AsyncExecutionResult {
 	const { agent, task, agentConfig, ctx, cwd, maxOutput, artifactsDir, artifactConfig, shareEnabled, sessionRoot } = params;
+	const skillNames = params.skills ?? agentConfig.skills ?? [];
+	const { resolved: resolvedSkills } = resolveSkills(skillNames, ctx.cwd);
+	let systemPrompt = agentConfig.systemPrompt?.trim() || null;
+	if (resolvedSkills.length > 0) {
+		const injection = buildSkillInjection(resolvedSkills);
+		systemPrompt = systemPrompt ? `${systemPrompt}\n\n${injection}` : injection;
+	}
 
 	const asyncDir = path.join(ASYNC_DIR, id);
 	try {
@@ -217,7 +241,9 @@ export function executeAsyncSingle(
 					cwd,
 					model: agentConfig.model,
 					tools: agentConfig.tools,
-					systemPrompt: agentConfig.systemPrompt?.trim() || null,
+					systemPrompt,
+					// Only track skills that were actually resolved
+					skills: resolvedSkills.map((r) => r.name),
 				},
 			],
 			resultPath: path.join(RESULTS_DIR, `${id}.json`),

package/chain-clarify.ts

@@ -27,6 +27,7 @@ export interface BehaviorOverride {
 	reads?: string[] | false;
 	progress?: boolean;
 	model?: string;  // Override agent's default model (format: "provider/id")
+	skills?: string[] | false;
 }
 
 export interface ChainClarifyResult {
@@ -36,7 +37,7 @@ export interface ChainClarifyResult {
 	behaviorOverrides: (BehaviorOverride | undefined)[];
 }
 
-type EditMode = "template" | "output" | "reads" | "model" | "thinking";
+type EditMode = "template" | "output" | "reads" | "model" | "thinking" | "skills";
 
 /** Valid thinking levels */
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
@@ -73,6 +74,12 @@ export class ChainClarifyComponent implements Component {
 	/** Thinking level selector state */
 	private thinkingSelectedIndex: number = 0;
 
+	/** Skill selector state */
+	private skillSearchQuery: string = "";
+	private skillSelectedNames: Set<string> = new Set();
+	private skillCursorIndex: number = 0;
+	private filteredSkills: Array<{ name: string; source: string; description?: string }> = [];
+
 	constructor(
 		private tui: TUI,
 		private theme: Theme,
@@ -82,11 +89,13 @@ export class ChainClarifyComponent implements Component {
 		private chainDir: string | undefined,  // undefined for single/parallel modes
 		private resolvedBehaviors: ResolvedStepBehavior[],
 		private availableModels: ModelInfo[],
+		private availableSkills: Array<{ name: string; source: string; description?: string }>,
 		private done: (result: ChainClarifyResult) => void,
 		private mode: ClarifyMode = 'chain',   // Mode: 'single', 'parallel', or 'chain'
 	) {
 		// Initialize filtered models
 		this.filteredModels = [...availableModels];
+		this.filteredSkills = [...availableSkills];
 	}
 
 	// ─────────────────────────────────────────────────────────────────────────────
@@ -290,6 +299,7 @@ export class ChainClarifyComponent implements Component {
 			output: override.output !== undefined ? override.output : base.output,
 			reads: override.reads !== undefined ? override.reads : base.reads,
 			progress: override.progress !== undefined ? override.progress : base.progress,
+			skills: override.skills !== undefined ? override.skills : base.skills,
 			model: override.model,
 		};
 	}
@@ -340,6 +350,8 @@ export class ChainClarifyComponent implements Component {
 				this.handleModelSelectorInput(data);
 			} else if (this.editMode === "thinking") {
 				this.handleThinkingSelectorInput(data);
+			} else if (this.editMode === "skills") {
+				this.handleSkillSelectorInput(data);
 			} else {
 				this.handleEditInput(data);
 			}
@@ -393,6 +405,22 @@ export class ChainClarifyComponent implements Component {
 			return;
 		}
 
+		// 's' to select skills (all modes)
+		if (data === "s") {
+			this.editingStep = this.selectedStep;
+			this.editMode = "skills";
+			this.skillSearchQuery = "";
+			this.skillCursorIndex = 0;
+			this.filteredSkills = [...this.availableSkills];
+			const current = this.getEffectiveBehavior(this.selectedStep).skills;
+			this.skillSelectedNames.clear();
+			if (current !== false && current.length > 0) {
+				current.forEach((skillName) => this.skillSelectedNames.add(skillName));
+			}
+			this.tui.requestRender();
+			return;
+		}
+
 		// 'w' to edit writes (single and chain only - not parallel)
 		if (data === "w" && this.mode !== 'parallel') {
 			this.enterEditMode("output");
@@ -607,6 +635,84 @@ export class ChainClarifyComponent implements Component {
 		this.updateBehavior(stepIndex, "model", newModel);
 	}
 
+	private filterSkills(): void {
+		const query = this.skillSearchQuery.toLowerCase();
+		if (!query) {
+			this.filteredSkills = [...this.availableSkills];
+		} else {
+			this.filteredSkills = this.availableSkills.filter((s) =>
+				s.name.toLowerCase().includes(query) ||
+				(s.description?.toLowerCase().includes(query) ?? false),
+			);
+		}
+		this.skillCursorIndex = Math.min(this.skillCursorIndex, Math.max(0, this.filteredSkills.length - 1));
+	}
+
+	private handleSkillSelectorInput(data: string): void {
+		if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) {
+			this.exitEditMode();
+			return;
+		}
+
+		if (matchesKey(data, "return")) {
+			const selected = [...this.skillSelectedNames];
+			this.updateBehavior(this.editingStep!, "skills", selected);
+			this.exitEditMode();
+			return;
+		}
+
+		if (data === " ") {
+			if (this.filteredSkills.length > 0) {
+				const skill = this.filteredSkills[this.skillCursorIndex];
+				if (skill) {
+					if (this.skillSelectedNames.has(skill.name)) {
+						this.skillSelectedNames.delete(skill.name);
+					} else {
+						this.skillSelectedNames.add(skill.name);
+					}
+				}
+			}
+			this.tui.requestRender();
+			return;
+		}
+
+		if (matchesKey(data, "up")) {
+			if (this.filteredSkills.length > 0) {
+				this.skillCursorIndex = this.skillCursorIndex === 0
+					? this.filteredSkills.length - 1
+					: this.skillCursorIndex - 1;
+			}
+			this.tui.requestRender();
+			return;
+		}
+
+		if (matchesKey(data, "down")) {
+			if (this.filteredSkills.length > 0) {
+				this.skillCursorIndex = this.skillCursorIndex === this.filteredSkills.length - 1
+					? 0
+					: this.skillCursorIndex + 1;
+			}
+			this.tui.requestRender();
+			return;
+		}
+
+		if (matchesKey(data, "backspace")) {
+			if (this.skillSearchQuery.length > 0) {
+				this.skillSearchQuery = this.skillSearchQuery.slice(0, -1);
+				this.filterSkills();
+			}
+			this.tui.requestRender();
+			return;
+		}
+
+		if (data.length === 1 && data.charCodeAt(0) >= 32) {
+			this.skillSearchQuery += data;
+			this.filterSkills();
+			this.tui.requestRender();
+			return;
+		}
+	}
+
 	private handleEditInput(data: string): void {
 		const textWidth = this.width - 4; // Must match render: innerW - 2 = (width - 2) - 2
 		const { lines: wrapped, starts } = this.wrapText(this.editBuffer, textWidth);
@@ -817,6 +923,9 @@ export class ChainClarifyComponent implements Component {
 			if (this.editMode === "thinking") {
 				return this.renderThinkingSelector();
 			}
+			if (this.editMode === "skills") {
+				return this.renderSkillSelector();
+			}
 			return this.renderFullEditMode();
 		}
 		// Mode-based navigation rendering
@@ -972,15 +1081,83 @@ export class ChainClarifyComponent implements Component {
 		return lines;
 	}
 
+	private renderSkillSelector(): string[] {
+		const innerW = this.width - 2;
+		const th = this.theme;
+		const lines: string[] = [];
+
+		const agentName = this.agentConfigs[this.editingStep!]?.name ?? "unknown";
+		const stepLabel = this.mode === 'single'
+			? agentName
+			: this.mode === 'parallel'
+				? `Task ${this.editingStep! + 1}: ${agentName}`
+				: `Step ${this.editingStep! + 1}: ${agentName}`;
+		lines.push(this.renderHeader(` Select Skills (${stepLabel}) `));
+		lines.push(this.row(""));
+
+		const cursor = "\x1b[7m \x1b[27m";
+		lines.push(this.row(` ${th.fg("dim", "Search: ")}${this.skillSearchQuery}${cursor}`));
+		lines.push(this.row(""));
+
+		const selected = [...this.skillSelectedNames].join(", ") || th.fg("dim", "(none)");
+		lines.push(this.row(` ${th.fg("dim", "Selected: ")}${truncateToWidth(selected, innerW - 12)}`));
+		lines.push(this.row(""));
+
+		const selectorHeight = 10;
+		if (this.filteredSkills.length === 0) {
+			lines.push(this.row(` ${th.fg("dim", "No matching skills")}`));
+		} else {
+			let startIdx = 0;
+			if (this.filteredSkills.length > selectorHeight) {
+				startIdx = Math.max(0, this.skillCursorIndex - Math.floor(selectorHeight / 2));
+				startIdx = Math.min(startIdx, this.filteredSkills.length - selectorHeight);
+			}
+			const endIdx = Math.min(startIdx + selectorHeight, this.filteredSkills.length);
+
+			if (startIdx > 0) {
+				lines.push(this.row(` ${th.fg("dim", `  ↑ ${startIdx} more`)}`));
+			}
+
+			for (let i = startIdx; i < endIdx; i++) {
+				const skill = this.filteredSkills[i]!;
+				const isCursor = i === this.skillCursorIndex;
+				const isSelected = this.skillSelectedNames.has(skill.name);
+
+				const prefix = isCursor ? th.fg("accent", "→ ") : "  ";
+				const checkbox = isSelected ? th.fg("success", "[x]") : "[ ]";
+				const nameText = isCursor ? th.fg("accent", skill.name) : skill.name;
+				const sourceBadge = th.fg("dim", ` [${skill.source}]`);
+				const desc = skill.description
+					? th.fg("dim", ` - ${truncateToWidth(skill.description, 25)}`)
+					: "";
+
+				lines.push(this.row(` ${prefix}${checkbox} ${nameText}${sourceBadge}${desc}`));
+			}
+
+			const remaining = this.filteredSkills.length - endIdx;
+			if (remaining > 0) {
+				lines.push(this.row(` ${th.fg("dim", `  ↓ ${remaining} more`)}`));
+			}
+		}
+
+		const targetHeight = 18;
+		for (let i = lines.length; i < targetHeight; i++) {
+			lines.push(this.row(""));
+		}
+
+		lines.push(this.renderFooter(" [Enter] Confirm • [Space] Toggle • [Esc] Cancel "));
+		return lines;
+	}
+
 	/** Get footer text based on mode */
 	private getFooterText(): string {
 		switch (this.mode) {
 			case 'single':
-				return ' [Enter] Run • [Esc] Cancel • [e]dit [m]odel [t]hinking [w]rites ';
+				return ' [Enter] Run • [Esc] Cancel • [e]dit [m]odel [t]hink [w]rite [s]kill ';
 			case 'parallel':
-				return ' [Enter] Run • [Esc] Cancel • [e]dit [m]odel [t]hinking • ↑↓ Navigate ';
+				return ' [Enter] Run • [Esc] Cancel • [e]dit [m]odel [t]hink [s]kill • ↑↓ Nav ';
 			case 'chain':
-				return ' [Enter] Run • [Esc] Cancel • [e]dit [m]odel [t]hinking [w]rites [r]eads [p]rogress ';
+				return ' [Enter] Run • [Esc] Cancel • e m t w r p s • ↑↓ Nav ';
 		}
 	}
 
@@ -1027,6 +1204,12 @@ export class ChainClarifyComponent implements Component {
 		const writesLabel = th.fg("dim", "writes: ");
 		lines.push(this.row(`     ${writesLabel}${truncateToWidth(writesValue, innerW - 14)}`));
 
+		const skillsValue = behavior.skills === false
+			? th.fg("dim", "(disabled)")
+			: (behavior.skills?.length ? behavior.skills.join(", ") : th.fg("dim", "(none)"));
+		const skillsLabel = th.fg("dim", "skills: ");
+		lines.push(this.row(`     ${skillsLabel}${truncateToWidth(skillsValue, innerW - 14)}`));
+
 		lines.push(this.row(""));
 
 		// Footer
@@ -1077,6 +1260,13 @@ export class ChainClarifyComponent implements Component {
 			const modelLabel = th.fg("dim", "model: ");
 			lines.push(this.row(`     ${modelLabel}${truncateToWidth(modelValue, innerW - 13)}`));
 
+			const behavior = this.getEffectiveBehavior(i);
+			const skillsValue = behavior.skills === false
+				? th.fg("dim", "(disabled)")
+				: (behavior.skills?.length ? behavior.skills.join(", ") : th.fg("dim", "(none)"));
+			const skillsLabel = th.fg("dim", "skills: ");
+			lines.push(this.row(`     ${skillsLabel}${truncateToWidth(skillsValue, innerW - 14)}`));
+
 			lines.push(this.row(""));
 		}
 
@@ -1168,6 +1358,12 @@ export class ChainClarifyComponent implements Component {
 			const readsLabel = th.fg("dim", "reads: ");
 			lines.push(this.row(`     ${readsLabel}${truncateToWidth(readsValue, innerW - 13)}`));
 
+			const skillsValue = behavior.skills === false
+				? th.fg("dim", "(disabled)")
+				: (behavior.skills?.length ? behavior.skills.join(", ") : th.fg("dim", "(none)"));
+			const skillsLabel = th.fg("dim", "skills: ");
+			lines.push(this.row(`     ${skillsLabel}${truncateToWidth(skillsValue, innerW - 14)}`));
+
 			// Progress line - show when chain-wide progress is enabled
 			// First step creates & updates, subsequent steps read & update
 			if (progressEnabled) {

package/chain-execution.ts

@@ -24,6 +24,7 @@ import {
 	type ParallelTaskResult,
 	type ResolvedTemplates,
 } from "./settings.js";
+import { discoverAvailableSkills, normalizeSkillInput } from "./skills.js";
 import { runSync } from "./execution.js";
 import { buildChainSummary } from "./formatters.js";
 import { getFinalOutput, mapConcurrent } from "./utils.js";
@@ -72,6 +73,7 @@ export interface ChainExecutionParams {
 	includeProgress?: boolean;
 	clarify?: boolean;
 	onUpdate?: (r: AgentToolResult<Details>) => void;
+	chainSkills?: string[];
 }
 
 export interface ChainExecutionResult {
@@ -98,7 +100,9 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 		includeProgress,
 		clarify,
 		onUpdate,
+		chainSkills: chainSkillsParam,
 	} = params;
+	const chainSkills = chainSkillsParam ?? [];
 
 	const allProgress: AgentProgress[] = [];
 	const allArtifactPaths: ArtifactPaths[] = [];
@@ -138,6 +142,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 		id: m.id,
 		fullId: `${m.provider}/${m.id}`,
 	}));
+	const availableSkills = discoverAvailableSkills(ctx.cwd);
 
 	if (shouldClarify) {
 		// Sequential-only chain: use existing TUI
@@ -163,11 +168,12 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 			output: step.output,
 			reads: step.reads,
 			progress: step.progress,
+			skills: normalizeSkillInput(step.skill),
 		}));
 
 		// Pre-resolve behaviors for TUI display
 		const resolvedBehaviors = agentConfigs.map((config, i) =>
-			resolveStepBehavior(config, stepOverrides[i]!),
+			resolveStepBehavior(config, stepOverrides[i]!, chainSkills),
 		);
 
 		// Flatten templates for TUI (all strings for sequential)
@@ -184,6 +190,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 					chainDir,
 					resolvedBehaviors,
 					availableModels,
+					availableSkills,
 					done,
 				),
 			{
@@ -226,7 +233,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 			createParallelDirs(chainDir, stepIndex, step.parallel.length, agentNames);
 
 			// Resolve behaviors for parallel tasks
-			const parallelBehaviors = resolveParallelBehaviors(step.parallel, agents, stepIndex);
+			const parallelBehaviors = resolveParallelBehaviors(step.parallel, agents, stepIndex, chainSkills);
 
 			// If any parallel task has progress enabled and progress.md hasn't been created,
 			// create it now to avoid race conditions
@@ -293,6 +300,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 						artifactsDir: artifactConfig.enabled ? artifactsDir : undefined,
 						artifactConfig,
 						modelOverride: effectiveModel,
+						skills: behavior.skills === false ? [] : behavior.skills,
 						onUpdate: onUpdate
 							? (p) => {
 									// Use concat instead of spread for better performance
@@ -390,8 +398,12 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				output: tuiOverride?.output !== undefined ? tuiOverride.output : seqStep.output,
 				reads: tuiOverride?.reads !== undefined ? tuiOverride.reads : seqStep.reads,
 				progress: tuiOverride?.progress !== undefined ? tuiOverride.progress : seqStep.progress,
+				skills:
+					tuiOverride?.skills !== undefined
+						? tuiOverride.skills
+						: normalizeSkillInput(seqStep.skill),
 			};
-			const behavior = resolveStepBehavior(agentConfig, stepOverride);
+			const behavior = resolveStepBehavior(agentConfig, stepOverride, chainSkills);
 
 			// Determine if this is the first agent to create progress.md
 			const isFirstProgress = behavior.progress && !progressCreated;
@@ -431,6 +443,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				artifactsDir: artifactConfig.enabled ? artifactsDir : undefined,
 				artifactConfig,
 				modelOverride: effectiveModel,
+				skills: behavior.skills === false ? [] : behavior.skills,
 				onUpdate: onUpdate
 					? (p) => {
 							// Use concat instead of spread for better performance