@johnnywu/pi-subagents 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [1.4.0](https://github.com/jwu/pi-subagents/compare/v1.3.0...v1.4.0) (2026-06-02)
+
+
+### Features
+
+* support wildcard skills ([962eaa4](https://github.com/jwu/pi-subagents/commit/962eaa486cd73342629cfecf4e7bcc8a1ceb4710))
+
 # [1.3.0](https://github.com/jwu/pi-subagents/compare/v1.2.0...v1.3.0) (2026-06-02)
 
 

package/README.md

@@ -95,12 +95,15 @@ Agents are Markdown files with YAML frontmatter.
 | `model` | no | parent's model | Provider/model-id (`anthropic/claude-sonnet-4-6`) |
 | `thinking` | no | `off` | Reasoning level: `off`, `low`, `medium`, `high` |
 | `systemPrompt` | no | `append` | How the body is applied: `append` (append to pi default system prompt and project context) or `replace` (replace default prompt and skip project context) |
+| `skills` | no | _none_ | Comma-separated skill names or simple wildcard patterns (`*`, `obsidian-*`) to load (resolved from project `.agents/skills/`, `.pi/skills/`, global `~/.pi/agent/skills/`, or npm packages) |
 | `allowedAgents` | no | _all_ | Comma-separated list of sub-agents this agent may spawn |
 | `maxDepth` | no | `10` | Maximum recursion depth (`0` = no sub-agents, `1` = one level, etc.) |
 | `debug` | no | `false` | When `true`, export the effective runtime system prompt to `debug-system-prompt.md` |
 
 The Markdown body after the frontmatter is the agent's system prompt.
 
+`skills` entries match the skill frontmatter `name`. Use `skills: *` to load all available skills, or prefix-style patterns such as `skills: obsidian-*` to load matching skills. Only `*` is supported as a wildcard; glob features like `?` or `{a,b}` are not supported.
+
 ### Example with all fields
 
 ```markdown
@@ -111,6 +114,7 @@ tools: subagent, read, grep, find
 model: anthropic/claude-sonnet-4-6
 thinking: high
 systemPrompt: append
+skills: tdd, obsidian-*
 allowedAgents: code-reviewer, refactor, test-writer
 maxDepth: 2
 debug: false

package/extensions/skill-resolver.ts

@@ -17,6 +17,7 @@ export interface ResolvedSkill {
 export interface SkillResolverFs {
   exists(filePath: string): boolean;
   readFile(filePath: string): string;
+  listFiles?(dir: string): string[];
 }
 
 export interface ResolveSkillsOptions {
@@ -31,6 +32,7 @@ export interface ResolveSkillsResult {
   resolved: ResolvedSkill[];
   missing: string[];
   skippedPackages: string[];
+  warnings: string[];
 }
 
 const defaultSkillFs: SkillResolverFs = {
@@ -40,6 +42,16 @@ const defaultSkillFs: SkillResolverFs = {
   readFile(filePath) {
     return fs.readFileSync(filePath, 'utf-8');
   },
+  listFiles(dir) {
+    try {
+      return fs
+        .readdirSync(dir, { withFileTypes: true })
+        .map((entry) => path.join(dir, entry.name))
+        .sort();
+    } catch {
+      return [];
+    }
+  },
 };
 
 function defaultGlobalSkillsDir(): string {
@@ -89,33 +101,7 @@ function parseSkillFrontmatter(content: string): { name: string; description: st
   }
   delete data._currentBlockKey;
 
-  if (!data.description || !data.description.trim()) return undefined;
-  return { name: data.name || '', description: data.description.trim() };
-}
-
-function findLocalSkillFile(
-  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;
+  return { name: data.name || '', description: (data.description ?? '').trim() };
 }
 
 async function resolvePackageSkillFiles(options: ResolveSkillsOptions): Promise<{
@@ -150,79 +136,165 @@ async function resolvePackageSkillFiles(options: ResolveSkillsOptions): Promise<
   };
 }
 
-function readSkill(
-  filePath: string,
-  requestedName: string,
-  fileSystem: SkillResolverFs,
-  requireNameMatch: boolean,
-): ResolvedSkill | undefined {
+interface ReadSkillResult {
+  skill?: ResolvedSkill;
+  warning?: string;
+}
+
+function readSkill(filePath: string, fileSystem: SkillResolverFs): ReadSkillResult | undefined {
   const content = fileSystem.readFile(filePath);
   const frontmatter = parseSkillFrontmatter(content);
   if (!frontmatter) return undefined;
 
-  const fileSkillName = frontmatter.name || path.basename(path.dirname(filePath));
-  const markdownName = path.basename(filePath, '.md');
-  if (requireNameMatch && fileSkillName !== requestedName && markdownName !== requestedName) {
-    return undefined;
+  const fileSkillName = frontmatter.name.trim();
+  if (!fileSkillName) {
+    return { warning: `skill missing required field: name: ${filePath}` };
   }
+  if (!frontmatter.description) return undefined;
 
   return {
-    name: fileSkillName || requestedName,
-    description: frontmatter.description,
-    location: filePath,
+    skill: {
+      name: fileSkillName,
+      description: frontmatter.description,
+      location: filePath,
+    },
   };
 }
 
+interface CollectedSkills {
+  byName: Map<string, ResolvedSkill>;
+  warnings: string[];
+  skippedPackages: string[];
+}
+
+const collectedSkillsCache = new Map<string, Promise<CollectedSkills>>();
+
+function listSkillFilesInDir(dir: string, fileSystem: SkillResolverFs): string[] {
+  if (!fileSystem.listFiles) return [];
+
+  return fileSystem
+    .listFiles(dir)
+    .map((entry) => path.join(entry, 'SKILL.md'))
+    .filter((filePath) => fileSystem.exists(filePath));
+}
+
+function addSkillFile(
+  filePath: string,
+  fileSystem: SkillResolverFs,
+  byName: Map<string, ResolvedSkill>,
+  warnings: string[],
+): void {
+  try {
+    const result = readSkill(filePath, fileSystem);
+    if (!result) return;
+    if (result.warning) warnings.push(result.warning);
+    if (result.skill && !byName.has(result.skill.name)) byName.set(result.skill.name, result.skill);
+  } catch (error) {
+    warnings.push(
+      `skill could not be read: ${filePath}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
+async function collectSkills(options: ResolveSkillsOptions): Promise<CollectedSkills> {
+  const cwd = options.cwd;
+  const globalDir = options.globalDir ?? defaultGlobalSkillsDir();
+  const fileSystem = options.fs ?? defaultSkillFs;
+  const byName = new Map<string, ResolvedSkill>();
+  const warnings: string[] = [];
+
+  for (const dir of [
+    path.join(cwd, '.agents', 'skills'),
+    path.join(cwd, '.pi', 'skills'),
+    globalDir,
+    path.join(os.homedir(), '.agents', 'skills'),
+  ]) {
+    for (const filePath of listSkillFilesInDir(dir, fileSystem)) {
+      addSkillFile(filePath, fileSystem, byName, warnings);
+    }
+  }
+
+  const packageSkills = await resolvePackageSkillFiles(options);
+  for (const filePath of packageSkills.files) {
+    addSkillFile(filePath, fileSystem, byName, warnings);
+  }
+
+  return { byName, warnings, skippedPackages: packageSkills.skippedPackages };
+}
+
+function skillsCacheKey(options: ResolveSkillsOptions): string | undefined {
+  if (options.fs) return undefined;
+  return JSON.stringify({
+    cwd: options.cwd,
+    agentDir: options.agentDir,
+    globalDir: options.globalDir ?? defaultGlobalSkillsDir(),
+    packageSkillFiles: options.packageSkillFiles,
+  });
+}
+
+async function getCollectedSkills(options: ResolveSkillsOptions): Promise<CollectedSkills> {
+  const cacheKey = skillsCacheKey(options);
+  if (!cacheKey) return collectSkills(options);
+
+  let cached = collectedSkillsCache.get(cacheKey);
+  if (!cached) {
+    cached = collectSkills(options);
+    collectedSkillsCache.set(cacheKey, cached);
+  }
+  return cached;
+}
+
+function wildcardToRegex(pattern: string): RegExp {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+  return new RegExp(`^${escaped}$`);
+}
+
+function hasWildcard(pattern: string): boolean {
+  return pattern.includes('*');
+}
+
 export async function resolveSkills(
   skillNames: string[],
   options: ResolveSkillsOptions,
 ): Promise<ResolveSkillsResult> {
-  const cwd = options.cwd;
-  const globalDir = options.globalDir ?? defaultGlobalSkillsDir();
-  const fileSystem = options.fs ?? defaultSkillFs;
+  const requestedNames = skillNames.map((name) => name.trim()).filter(Boolean);
+  if (requestedNames.length === 0) {
+    return { resolved: [], missing: [], skippedPackages: [], warnings: [] };
+  }
+
+  const collected = await getCollectedSkills(options);
   const resolved: ResolvedSkill[] = [];
   const missing: string[] = [];
-  const pendingPackageResolution: string[] = [];
-
-  for (const name of skillNames) {
-    const trimmed = name.trim();
-    if (!trimmed) continue;
-
-    const localFilePath = findLocalSkillFile(trimmed, cwd, globalDir, fileSystem);
-    if (localFilePath) {
-      try {
-        const skill = readSkill(localFilePath, trimmed, fileSystem, false);
-        if (skill) {
-          resolved.push(skill);
-          continue;
-        }
-      } catch {
-        // Try package skills before marking the skill as missing.
-      }
-    }
+  const seen = new Set<string>();
 
-    pendingPackageResolution.push(trimmed);
+  function addSkill(skill: ResolvedSkill): void {
+    if (seen.has(skill.name)) return;
+    seen.add(skill.name);
+    resolved.push(skill);
   }
 
-  const packageSkills =
-    pendingPackageResolution.length > 0
-      ? await resolvePackageSkillFiles(options)
-      : { files: [], skippedPackages: [] };
-
-  for (const trimmed of pendingPackageResolution) {
-    let packageSkill: ResolvedSkill | undefined;
-    for (const filePath of packageSkills.files) {
-      try {
-        packageSkill = readSkill(filePath, trimmed, fileSystem, true);
-        if (packageSkill) break;
-      } catch {
-        // Try the next package skill file.
+  for (const requestedName of requestedNames) {
+    if (hasWildcard(requestedName)) {
+      const regex = wildcardToRegex(requestedName);
+      let matched = false;
+      for (const skill of collected.byName.values()) {
+        if (!regex.test(skill.name)) continue;
+        matched = true;
+        addSkill(skill);
       }
+      if (!matched) missing.push(requestedName);
+      continue;
     }
 
-    if (packageSkill) resolved.push(packageSkill);
-    else missing.push(trimmed);
+    const skill = collected.byName.get(requestedName);
+    if (skill) addSkill(skill);
+    else missing.push(requestedName);
   }
 
-  return { resolved, missing, skippedPackages: packageSkills.skippedPackages };
+  return {
+    resolved,
+    missing,
+    skippedPackages: collected.skippedPackages,
+    warnings: collected.warnings,
+  };
 }

package/extensions/subagent-executor.ts

@@ -98,6 +98,7 @@ export interface BuildSubagentSystemPromptResult {
   prompt: string;
   missingSkills: string[];
   skippedSkillPackages: string[];
+  skillWarnings: string[];
 }
 
 const TASK_FILE_THRESHOLD = 8000;
@@ -367,6 +368,7 @@ export async function buildSubagentSystemPrompt(
 
   const missingSkills: string[] = [];
   const skippedSkillPackages: string[] = [];
+  const skillWarnings: string[] = [];
   const skillNames = options.agent.skills;
   if (skillNames && skillNames.length > 0) {
     const resolvedSkills = await resolveSkills(skillNames, {
@@ -375,6 +377,7 @@ export async function buildSubagentSystemPrompt(
     });
     missingSkills.push(...resolvedSkills.missing);
     skippedSkillPackages.push(...resolvedSkills.skippedPackages);
+    skillWarnings.push(...resolvedSkills.warnings);
 
     const skillInjection = formatSkillsForPrompt(resolvedSkills.resolved);
     if (skillInjection) {
@@ -382,7 +385,7 @@ export async function buildSubagentSystemPrompt(
     }
   }
 
-  return { prompt, missingSkills, skippedSkillPackages };
+  return { prompt, missingSkills, skippedSkillPackages, skillWarnings };
 }
 
 function progressFromPartialResult(partialResult: unknown): AgentProgress | undefined {
@@ -437,6 +440,9 @@ export async function runSubagent(options: RunSubagentOptions): Promise<AgentRes
     for (const source of promptResult.skippedSkillPackages) {
       console.warn(`[pi-subagents] package not installed, skipping skills: ${source}`);
     }
+    for (const warning of promptResult.skillWarnings) {
+      console.warn(`[pi-subagents] ${warning}`);
+    }
     for (const name of promptResult.missingSkills) {
       console.warn(`[pi-subagents] skill not found: ${name}`);
     }

package/package.json

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