@johnnywu/pi-subagents 1.0.1 → 1.2.0

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+# [1.2.0](https://github.com/jwu/pi-subagents/compare/v1.1.0...v1.2.0) (2026-06-02)
+
+
+### Features
+
+* agent skills frontmatter support ([e479b0c](https://github.com/jwu/pi-subagents/commit/e479b0cc57c8097a89f73b491c32a099ba56bc77))
+* expose available subagents in prompts ([047035a](https://github.com/jwu/pi-subagents/commit/047035a49e9749dc719a97f2556be9f60551cf97))
+
+# [1.1.0](https://github.com/jwu/pi-subagents/compare/v1.0.1...v1.1.0) (2026-05-31)
+
+
+### Features
+
+* **subagent:** list available agents in system prompt Guidelines ([317ed58](https://github.com/jwu/pi-subagents/commit/317ed5845379d3edd535bc03dab8460b29a82164))
+
 ## [1.0.1](https://github.com/jwu/pi-subagents/compare/v1.0.0...v1.0.1) (2026-05-31)
 
 

package/README.md

@@ -48,6 +48,23 @@ Or instruct pi to delegate:
 Run the code-reviewer agent on the last three commits
 ```
 
+### Available subagents in the prompt
+
+The extension exposes discovered sub-agents to the model in two places:
+
+- The `subagent` tool keeps a one-line prompt guideline:
+  `Available subagents: code-reviewer, refactor, test-writer`
+- The system prompt also gets an independent block:
+
+```text
+Available subagents:
+- code-reviewer
+- refactor
+- test-writer
+```
+
+For sub-agents launched with `systemPrompt: replace` or `systemPrompt: append`, the same block is written into the prompt passed via `--system-prompt` or `--append-system-prompt` when that agent has the `subagent` tool.
+
 ## Agent configuration
 
 Agents are Markdown files with YAML frontmatter.
@@ -102,6 +119,8 @@ Sub-agents can spawn their own sub-agents (if the `subagent` tool is in their wh
 
 **`allowedAgents`** — Whitelist enforced by the parent before spawning. A child process never sees agent names outside its parent's whitelist.
 
+The available-subagents prompt entries respect the same filtering: parent sessions use the currently visible agents, and child sessions only list agents allowed by their parent.
+
 These are passed via environment variables (`PI_SUBAGENT_DEPTH`, `PI_SUBAGENT_MAX_DEPTH`, `PI_SUBAGENT_ALLOWED`).
 
 ## Session storage

package/extensions/agent-loader.ts

@@ -15,6 +15,7 @@ export interface AgentConfig {
   systemPromptMode: SystemPromptMode;
   allowedAgents?: string[];
   maxDepth: number;
+  skills?: string[];
   prompt: string;
   source: AgentSource;
   filePath: string;
@@ -117,11 +118,13 @@ function parseAgentFile(content: string, filePath: string, source: AgentSource):
   }
 
   const allowedAgents = splitCsv(data.allowedAgents);
+  const skills = splitCsv(data.skills);
 
   return {
     name: data.name,
     description: data.description,
     tools: splitCsv(data.tools),
+    skills: skills.length > 0 ? skills : undefined,
     model: data.model || undefined,
     thinking,
     systemPromptMode,

package/extensions/env-utils.ts

@@ -0,0 +1,26 @@
+export type RecursionEnv = Partial<
+  Record<'PI_SUBAGENT_ALLOWED' | 'PI_SUBAGENT_DEPTH' | 'PI_SUBAGENT_MAX_DEPTH', string>
+>;
+
+export function parseEnvNumber(value: string | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+export function allowedAgentNames(env: RecursionEnv): Set<string> | undefined {
+  const raw = env?.PI_SUBAGENT_ALLOWED;
+  if (!raw) return undefined;
+  return new Set(
+    raw
+      .split(',')
+      .map((name) => name.trim())
+      .filter(Boolean),
+  );
+}
+
+export function isPastMaxDepth(env: RecursionEnv): boolean {
+  const depth = parseEnvNumber(env?.PI_SUBAGENT_DEPTH);
+  const maxDepth = parseEnvNumber(env?.PI_SUBAGENT_MAX_DEPTH);
+  return depth !== undefined && maxDepth !== undefined && depth > maxDepth;
+}

package/extensions/index.ts

@@ -1,5 +1,7 @@
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { loadAgentDefinitions } from './agent-loader.ts';
+import { allowedAgentNames, isPastMaxDepth } from './env-utils.ts';
+import { appendAvailableSubagentsBlock } from './subagent-prompt.ts';
 import { registerSubagentTool } from './subagent-tool.ts';
 
 export default async function (pi: ExtensionAPI) {
@@ -9,5 +11,17 @@ export default async function (pi: ExtensionAPI) {
     console.warn(`[pi-subagents] skipped ${warning.filePath}: ${warning.message}`);
   }
 
+  const allowed = allowedAgentNames(process.env);
+  const agents = allowed
+    ? result.agents.filter((candidate) => allowed.has(candidate.name))
+    : result.agents;
+  const agentNames = agents.map((agent) => agent.name);
+
+  if (!isPastMaxDepth(process.env) && agentNames.length > 0) {
+    pi.on('before_agent_start', (event) => ({
+      systemPrompt: appendAvailableSubagentsBlock(event.systemPrompt, agentNames),
+    }));
+  }
+
   registerSubagentTool(pi, { agents: result.agents });
 }

package/extensions/skill-resolver.ts

@@ -0,0 +1,146 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+export interface ResolvedSkill {
+  name: string;
+  description: string;
+  location: string;
+}
+
+export interface SkillResolverFs {
+  exists(filePath: string): boolean;
+  readFile(filePath: string): string;
+}
+
+export interface ResolveSkillsOptions {
+  cwd: string;
+  globalDir?: string;
+  fs?: SkillResolverFs;
+}
+
+const defaultSkillFs: SkillResolverFs = {
+  exists(filePath) {
+    return fs.existsSync(filePath);
+  },
+  readFile(filePath) {
+    return fs.readFileSync(filePath, 'utf-8');
+  },
+};
+
+function defaultGlobalSkillsDir(): string {
+  return path.join(os.homedir(), '.pi', 'agent', 'skills');
+}
+
+function parseSkillFrontmatter(content: string): { name: string; description: string } | undefined {
+  const normalized = content.replace(/\r\n/g, '\n');
+  if (!normalized.startsWith('---')) return undefined;
+
+  const endIndex = normalized.indexOf('\n---', 3);
+  if (endIndex === -1) return undefined;
+
+  const frontmatterBlock = normalized.slice(4, endIndex);
+  const lines = frontmatterBlock.split('\n');
+  const data: Record<string, string> = {};
+
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    // Check if this is a YAML block scalar continuation (| or >)
+    if (
+      data._currentBlockKey !== undefined &&
+      (lines[i].startsWith('  ') || lines[i].startsWith('\t'))
+    ) {
+      const current = data[data._currentBlockKey] ?? '';
+      data[data._currentBlockKey] = current ? `${current} ${trimmed}` : trimmed;
+      continue;
+    }
+    delete data._currentBlockKey;
+
+    const separator = trimmed.indexOf(':');
+    if (separator === -1) continue;
+    const key = trimmed.slice(0, separator).trim();
+    let value = trimmed.slice(separator + 1).trim();
+
+    // Handle YAML block scalar indicators (| and >)
+    if (value === '|' || value === '>') {
+      data._currentBlockKey = key;
+      data[key] = '';
+      continue;
+    }
+
+    value = value.replace(/^['"]|['"]$/g, '');
+    if (key) data[key] = value;
+  }
+  delete data._currentBlockKey;
+
+  if (!data.description || !data.description.trim()) return undefined;
+  return { name: data.name || '', description: data.description.trim() };
+}
+
+function findSkillFile(
+  skillName: string,
+  cwd: string,
+  globalDir: string,
+  fileSystem: SkillResolverFs,
+): string | undefined {
+  // Priority 1: Project .agents/skills/<name>/SKILL.md
+  const projectAgentsPath = path.join(cwd, '.agents', 'skills', skillName, 'SKILL.md');
+  if (fileSystem.exists(projectAgentsPath)) return projectAgentsPath;
+
+  // Priority 1: Project .pi/skills/<name>/SKILL.md
+  const projectPiPath = path.join(cwd, '.pi', 'skills', skillName, 'SKILL.md');
+  if (fileSystem.exists(projectPiPath)) return projectPiPath;
+
+  // Priority 4: Global ~/.pi/agent/skills/<name>/SKILL.md
+  const globalPiPath = path.join(globalDir, skillName, 'SKILL.md');
+  if (fileSystem.exists(globalPiPath)) return globalPiPath;
+
+  // Priority 4: Global ~/.agents/skills/<name>/SKILL.md
+  const globalAgentsPath = path.join(os.homedir(), '.agents', 'skills', skillName, 'SKILL.md');
+  if (fileSystem.exists(globalAgentsPath)) return globalAgentsPath;
+
+  return undefined;
+}
+
+export function resolveSkills(
+  skillNames: string[],
+  options: ResolveSkillsOptions,
+): { resolved: ResolvedSkill[]; missing: string[] } {
+  const cwd = options.cwd;
+  const globalDir = options.globalDir ?? defaultGlobalSkillsDir();
+  const fileSystem = options.fs ?? defaultSkillFs;
+  const resolved: ResolvedSkill[] = [];
+  const missing: string[] = [];
+
+  for (const name of skillNames) {
+    const trimmed = name.trim();
+    if (!trimmed) continue;
+
+    const filePath = findSkillFile(trimmed, cwd, globalDir, fileSystem);
+    if (!filePath) {
+      missing.push(trimmed);
+      continue;
+    }
+
+    try {
+      const content = fileSystem.readFile(filePath);
+      const frontmatter = parseSkillFrontmatter(content);
+      if (!frontmatter) {
+        missing.push(trimmed);
+        continue;
+      }
+
+      resolved.push({
+        name: frontmatter.name || trimmed,
+        description: frontmatter.description,
+        location: filePath,
+      });
+    } catch {
+      missing.push(trimmed);
+    }
+  }
+
+  return { resolved, missing };
+}

package/extensions/subagent-executor.ts

@@ -5,6 +5,8 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import type { AgentConfig } from './agent-loader.ts';
+import { formatAvailableSubagentsBlock } from './subagent-prompt.ts';
+import { resolveSkills } from './skill-resolver.ts';
 
 export interface AgentUsage {
   input: number;
@@ -77,6 +79,7 @@ export interface RunSubagentOptions {
   signal?: AbortSignal;
   onProgress?: (progress: AgentProgress) => void;
   depth?: number;
+  availableAgents?: string[];
   tempRoot?: string;
   outputArchiveDir?: string;
   agentDir?: string;
@@ -274,6 +277,40 @@ function buildTaskArgument(task: string, taskFilePath: string | undefined): stri
   return taskFilePath ? `Task: @${taskFilePath}` : `Task: ${task}`;
 }
 
+function escapeXml(text: string): string {
+  return text
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+function formatSkillsForPrompt(
+  skills: Array<{ name: string; description: string; location: string }>,
+): string {
+  if (skills.length === 0) return '';
+
+  const lines = [
+    '\n\nThe following skills provide specialized instructions for specific tasks.',
+    "Use the read tool to load a skill's file when the task matches its description.",
+    'When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md / dirname of the path) and use that absolute path in tool commands.',
+    '',
+    '<available_skills>',
+  ];
+
+  for (const skill of skills) {
+    lines.push('  <skill>');
+    lines.push(`    <name>${escapeXml(skill.name)}</name>`);
+    lines.push(`    <description>${escapeXml(skill.description)}</description>`);
+    lines.push(`    <location>${escapeXml(skill.location)}</location>`);
+    lines.push('  </skill>');
+  }
+
+  lines.push('</available_skills>');
+  return lines.join('\n');
+}
+
 function byteLength(text: string): number {
   return Buffer.byteLength(text, 'utf8');
 }
@@ -339,7 +376,29 @@ export async function runSubagent(options: RunSubagentOptions): Promise<AgentRes
 
   try {
     const promptFilePath = path.join(tempDir, 'system-prompt.md');
-    await fileSystem.writeFile(promptFilePath, options.agent.prompt);
+
+    let promptContent = options.agent.prompt;
+    if (options.agent.tools.includes('subagent')) {
+      const availableSubagentsBlock = formatAvailableSubagentsBlock(
+        options.availableAgents ?? options.agent.allowedAgents ?? [],
+      );
+      if (availableSubagentsBlock) {
+        promptContent = `${promptContent.trimEnd()}\n\n${availableSubagentsBlock}`;
+      }
+    }
+
+    const skillNames = options.agent.skills;
+    if (skillNames && skillNames.length > 0) {
+      const { resolved, missing } = resolveSkills(skillNames, { cwd: options.cwd });
+      for (const name of missing) {
+        console.warn(`[pi-subagents] skill not found: ${name}`);
+      }
+      const skillInjection = formatSkillsForPrompt(resolved);
+      if (skillInjection) {
+        promptContent = `${promptContent}${skillInjection}`;
+      }
+    }
+    await fileSystem.writeFile(promptFilePath, promptContent);
 
     let taskFilePath: string | undefined;
     if (options.task.length > TASK_FILE_THRESHOLD) {

package/extensions/subagent-prompt.ts

@@ -0,0 +1,13 @@
+export function formatAvailableSubagentsBlock(agentNames: string[]): string | undefined {
+  const names = [...new Set(agentNames.map((name) => name.trim()).filter(Boolean))].sort();
+  if (names.length === 0) return undefined;
+
+  return ['Available subagents:', ...names.map((name) => `- ${name}`)].join('\n');
+}
+
+export function appendAvailableSubagentsBlock(systemPrompt: string, agentNames: string[]): string {
+  const block = formatAvailableSubagentsBlock(agentNames);
+  if (!block || systemPrompt.includes(block)) return systemPrompt;
+
+  return `${systemPrompt.trimEnd()}\n\n${block}`;
+}

package/extensions/subagent-tool.ts

@@ -17,6 +17,7 @@ import {
   type SubagentResultLine,
 } from './subagent-render.ts';
 import { numberArg, preview, shortenPath, stringArg } from './tool-args.ts';
+import { allowedAgentNames, isPastMaxDepth, type RecursionEnv } from './env-utils.ts';
 
 const SubagentParams = {
   type: 'object',
@@ -36,10 +37,6 @@ type SubagentParamsType = {
 };
 
 type RegisterablePi = Pick<ExtensionAPI, 'registerTool'>;
-type RecursionEnv = Partial<
-  Record<'PI_SUBAGENT_ALLOWED' | 'PI_SUBAGENT_DEPTH' | 'PI_SUBAGENT_MAX_DEPTH', string>
->;
-
 export interface RegisterSubagentToolOptions {
   agents: AgentConfig[];
   run?: typeof runSubagent;
@@ -70,29 +67,6 @@ function toProgressResult(progress: AgentProgress) {
   };
 }
 
-function parseEnvNumber(value: string | undefined): number | undefined {
-  if (value === undefined) return undefined;
-  const parsed = Number(value);
-  return Number.isFinite(parsed) ? parsed : undefined;
-}
-
-function allowedAgentNames(env: RecursionEnv): Set<string> | undefined {
-  const raw = env?.PI_SUBAGENT_ALLOWED;
-  if (!raw) return undefined;
-  return new Set(
-    raw
-      .split(',')
-      .map((name) => name.trim())
-      .filter(Boolean),
-  );
-}
-
-function isPastMaxDepth(env: RecursionEnv): boolean {
-  const depth = parseEnvNumber(env?.PI_SUBAGENT_DEPTH);
-  const maxDepth = parseEnvNumber(env?.PI_SUBAGENT_MAX_DEPTH);
-  return depth !== undefined && maxDepth !== undefined && depth > maxDepth;
-}
-
 type CollapsedTheme = {
   fg: (name: ThemeColor, text: string) => string;
   bold: (text: string) => string;
@@ -243,11 +217,17 @@ export function registerSubagentTool(
     : options.agents;
   const runner = options.run ?? runSubagent;
 
+  const availableSubagents = agents.map((agent) => agent.name);
+  const agentNames = [...availableSubagents].sort().join(', ');
+  const promptGuidelines =
+    agentNames.length > 0 ? [`Available subagents: ${agentNames}`] : undefined;
+
   pi.registerTool({
     name: 'subagent',
     label: 'Subagent',
     description: 'Delegate a task to a named sub-agent running in an isolated pi process.',
     promptSnippet: 'Delegate isolated tasks with subagent({ agent, task, cwd? }).',
+    promptGuidelines,
     parameters: SubagentParams,
 
     async execute(
@@ -270,6 +250,7 @@ export function registerSubagentTool(
         cwd: params.cwd ?? ctx.cwd,
         signal,
         depth: Number(env.PI_SUBAGENT_DEPTH ?? '0') + 1,
+        availableAgents: availableSubagents,
         onProgress: (progress) => onUpdate?.(toProgressResult(progress)),
       });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnnywu/pi-subagents",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Sub-agents extension for pi coding agent.",
   "homepage": "https://github.com/jwu/pi-subagents#readme",
   "repository": {