fix(pi): normalize skill names and avoid subagent tool conflicts

- Normalize Pi skill names to lowercase-hyphen form (ce:plan → ce-plan)
- Truncate normalized names to 60 chars to stay within Pi's 64-char limit
- Rename CE compat tool from subagent to ce_subagent to avoid pi-subagents collision
- Rewrite Task calls, slash commands, and tool refs in copied/synced Pi content
- Support zero-argument Task calls (Task agent() with no args)
- Resolve Task, /skill:, and slash refs against deduped name maps in converter and sync
- Two-pass name allocation for skills, agents, and prompts to handle collisions
- Sort skills, agents, and commands before dedup for deterministic allocation across runs
- Use locale-independent codepoint sort for cross-platform stability
- Pass prompt maps from sync orchestrator into skill sync for cross-reference resolution
- Fall through /skill: refs to agent map since Pi uses a flat skills/ namespace
- Thread name maps through writer path so copied skills use deduped names
- Rewrite frontmatterless skill bodies during Pi copy
- Fallback-rewrite malformed-frontmatter skill bodies (body only, preserving broken YAML)
- Apply MCPorter compatibility note only to prompts, not agent skill files
- Handle dangling symlinks during skill dir cleanup using lstat instead of access
- Back up existing skill dirs before overwrite, retain most recent backup
- Skip symlinks during backup cleanup to prevent unintended deletions
- Strip doubled quotes from Task args and tighten subagent regex to avoid false positives
- Use sentinel comment for MCPorter note idempotency
- Write compat extension during skills-only sync
- Guard parseFrontmatter calls against malformed YAML with warnings

Author: dragosdm

src/converters/claude-to-pi.ts

@@ -1,4 +1,5 @@
 import { formatFrontmatter } from "../utils/frontmatter"
+import { appendCompatibilityNoteIfNeeded, normalizePiSkillName, transformPiBodyContent, uniquePiSkillName, type PiNameMaps } from "../utils/pi-skills"
 import type { ClaudeAgent, ClaudeCommand, ClaudeMcpServer, ClaudePlugin } from "../types/claude"
 import type {
   PiBundle,
@@ -18,13 +19,41 @@ export function convertClaudeToPi(
   _options: ClaudeToPiOptions,
 ): PiBundle {
   const promptNames = new Set<string>()
-  const usedSkillNames = new Set<string>(plugin.skills.map((skill) => normalizeName(skill.name)))
+  const usedSkillNames = new Set<string>()
 
-  const prompts = plugin.commands
+  const sortedSkills = [...plugin.skills].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)
+  const sortedAgents = [...plugin.agents].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)
+
+  const skillDirs = sortedSkills.map((skill) => ({
+    name: uniquePiSkillName(normalizePiSkillName(skill.name), usedSkillNames),
+    sourceDir: skill.sourceDir,
+  }))
+
+  const agentNames = sortedAgents.map((agent) =>
+    uniquePiSkillName(normalizePiSkillName(agent.name), usedSkillNames),
+  )
+
+  const agentMap: Record<string, string> = {}
+  sortedAgents.forEach((agent, i) => { agentMap[agent.name] = agentNames[i] })
+
+  const skillMap: Record<string, string> = {}
+  sortedSkills.forEach((skill, i) => { skillMap[skill.name] = skillDirs[i].name })
+
+  const convertibleCommands = [...plugin.commands]
     .filter((command) => !command.disableModelInvocation)
-    .map((command) => convertPrompt(command, promptNames))
+    .sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)
+  const promptTargetNames = convertibleCommands.map((command) =>
+    uniquePiSkillName(normalizePiSkillName(command.name), promptNames),
+  )
 
-  const generatedSkills = plugin.agents.map((agent) => convertAgent(agent, usedSkillNames))
+  const promptMap: Record<string, string> = {}
+  convertibleCommands.forEach((command, i) => { promptMap[command.name] = promptTargetNames[i] })
+
+  const nameMaps: PiNameMaps = { agents: agentMap, skills: skillMap, prompts: promptMap }
+
+  const prompts = convertibleCommands.map((command, i) => convertPrompt(command, promptTargetNames[i], nameMaps))
+
+  const generatedSkills = sortedAgents.map((agent, i) => convertAgent(agent, agentNames[i], nameMaps))
 
   const extensions = [
     {
@@ -35,34 +64,29 @@ export function convertClaudeToPi(
 
   return {
     prompts,
-    skillDirs: plugin.skills.map((skill) => ({
-      name: skill.name,
-      sourceDir: skill.sourceDir,
-    })),
+    skillDirs,
     generatedSkills,
     extensions,
     mcporterConfig: plugin.mcpServers ? convertMcpToMcporter(plugin.mcpServers) : undefined,
+    nameMaps,
   }
 }
 
-function convertPrompt(command: ClaudeCommand, usedNames: Set<string>) {
-  const name = uniqueName(normalizeName(command.name), usedNames)
+function convertPrompt(command: ClaudeCommand, name: string, nameMaps: PiNameMaps) {
   const frontmatter: Record<string, unknown> = {
     description: command.description,
     "argument-hint": command.argumentHint,
   }
 
-  let body = transformContentForPi(command.body)
-  body = appendCompatibilityNoteIfNeeded(body)
+  const body = appendCompatibilityNoteIfNeeded(transformPiBodyContent(command.body, nameMaps))
 
   return {
     name,
     content: formatFrontmatter(frontmatter, body.trim()),
   }
 }
 
-function convertAgent(agent: ClaudeAgent, usedNames: Set<string>): PiGeneratedSkill {
-  const name = uniqueName(normalizeName(agent.name), usedNames)
+function convertAgent(agent: ClaudeAgent, name: string, nameMaps: PiNameMaps): PiGeneratedSkill {
   const description = sanitizeDescription(
     agent.description ?? `Converted from Claude agent ${agent.name}`,
   )
@@ -77,77 +101,19 @@ function convertAgent(agent: ClaudeAgent, usedNames: Set<string>): PiGeneratedSk
     sections.push(`## Capabilities\n${agent.capabilities.map((capability) => `- ${capability}`).join("\n")}`)
   }
 
-  const body = [
+  const body = transformPiBodyContent([
     ...sections,
     agent.body.trim().length > 0
       ? agent.body.trim()
       : `Instructions converted from the ${agent.name} agent.`,
-  ].join("\n\n")
+  ].join("\n\n"), nameMaps)
 
   return {
     name,
     content: formatFrontmatter(frontmatter, body),
   }
 }
 
-export function transformContentForPi(body: string): string {
-  let result = body
-
-  // Task repo-research-analyst(feature_description) or Task compound-engineering:research:repo-research-analyst(args)
-  // -> Run subagent with agent="repo-research-analyst" and task="feature_description"
-  const taskPattern = /^(\s*-?\s*)Task\s+([a-z][a-z0-9:-]*)\(([^)]*)\)/gm
-  result = result.replace(taskPattern, (_match, prefix: string, agentName: string, args: string) => {
-    const finalSegment = agentName.includes(":") ? agentName.split(":").pop()! : agentName
-    const skillName = normalizeName(finalSegment)
-    const trimmedArgs = args.trim().replace(/\s+/g, " ")
-    return trimmedArgs
-      ? `${prefix}Run subagent with agent=\"${skillName}\" and task=\"${trimmedArgs}\".`
-      : `${prefix}Run subagent with agent=\"${skillName}\".`
-  })
-
-  // Claude-specific tool references
-  result = result.replace(/\bAskUserQuestion\b/g, "ask_user_question")
-  result = result.replace(/\bTodoWrite\b/g, "file-based todos (todos/ + /skill:todo-create)")
-  result = result.replace(/\bTodoRead\b/g, "file-based todos (todos/ + /skill:todo-create)")
-
-  // /command-name or /workflows:command-name -> /workflows-command-name
-  const slashCommandPattern = /(?<![:\w])\/([a-z][a-z0-9_:-]*?)(?=[\s,."')\]}`]|$)/gi
-  result = result.replace(slashCommandPattern, (match, commandName: string) => {
-    if (commandName.includes("/")) return match
-    if (["dev", "tmp", "etc", "usr", "var", "bin", "home"].includes(commandName)) {
-      return match
-    }
-
-    if (commandName.startsWith("skill:")) {
-      const skillName = commandName.slice("skill:".length)
-      return `/skill:${normalizeName(skillName)}`
-    }
-
-    const withoutPrefix = commandName.startsWith("prompts:")
-      ? commandName.slice("prompts:".length)
-      : commandName
-
-    return `/${normalizeName(withoutPrefix)}`
-  })
-
-  return result
-}
-
-function appendCompatibilityNoteIfNeeded(body: string): string {
-  if (!/\bmcp\b/i.test(body)) return body
-
-  const note = [
-    "",
-    "## Pi + MCPorter note",
-    "For MCP access in Pi, use MCPorter via the generated tools:",
-    "- `mcporter_list` to inspect available MCP tools",
-    "- `mcporter_call` to invoke a tool",
-    "",
-  ].join("\n")
-
-  return body + note
-}
-
 function convertMcpToMcporter(servers: Record<string, ClaudeMcpServer>): PiMcporterConfig {
   const mcpServers: Record<string, PiMcporterServer> = {}
 
@@ -173,36 +139,9 @@ function convertMcpToMcporter(servers: Record<string, ClaudeMcpServer>): PiMcpor
   return { mcpServers }
 }
 
-function normalizeName(value: string): string {
-  const trimmed = value.trim()
-  if (!trimmed) return "item"
-  const normalized = trimmed
-    .toLowerCase()
-    .replace(/[\\/]+/g, "-")
-    .replace(/[:\s]+/g, "-")
-    .replace(/[^a-z0-9_-]+/g, "-")
-    .replace(/-+/g, "-")
-    .replace(/^-+|-+$/g, "")
-  return normalized || "item"
-}
-
 function sanitizeDescription(value: string, maxLength = PI_DESCRIPTION_MAX_LENGTH): string {
   const normalized = value.replace(/\s+/g, " ").trim()
   if (normalized.length <= maxLength) return normalized
   const ellipsis = "..."
   return normalized.slice(0, Math.max(0, maxLength - ellipsis.length)).trimEnd() + ellipsis
 }
-
-function uniqueName(base: string, used: Set<string>): string {
-  if (!used.has(base)) {
-    used.add(base)
-    return base
-  }
-  let index = 2
-  while (used.has(`${base}-${index}`)) {
-    index += 1
-  }
-  const name = `${base}-${index}`
-  used.add(name)
-  return name
-}

src/sync/pi-skills.ts

@@ -0,0 +1,45 @@
+import path from "path"
+import type { ClaudeSkill } from "../types/claude"
+import { ensureDir } from "../utils/files"
+import { copySkillDirForPi, normalizePiSkillName, skillFileMatchesPiTarget, uniquePiSkillName, type PiNameMaps } from "../utils/pi-skills"
+import { forceSymlink, isValidSkillName } from "../utils/symlink"
+
+export async function syncPiSkills(
+  skills: ClaudeSkill[],
+  skillsDir: string,
+  extraNameMaps?: PiNameMaps,
+): Promise<void> {
+  await ensureDir(skillsDir)
+
+  const validSkills = skills
+    .filter((skill) => {
+      if (!isValidSkillName(skill.name)) {
+        console.warn(`Skipping skill with unsafe name: ${skill.name}`)
+        return false
+      }
+      return true
+    })
+    .sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)
+
+  const usedNames = new Set<string>()
+  const targetNames = validSkills.map((skill) =>
+    uniquePiSkillName(normalizePiSkillName(skill.name), usedNames),
+  )
+
+  const skillMap: Record<string, string> = {}
+  validSkills.forEach((skill, i) => { skillMap[skill.name] = targetNames[i] })
+  const nameMaps: PiNameMaps = { skills: skillMap, prompts: extraNameMaps?.prompts }
+
+  for (const [i, skill] of validSkills.entries()) {
+    const targetName = targetNames[i]
+    const target = path.join(skillsDir, targetName)
+    const alreadyPiCompatible = await skillFileMatchesPiTarget(skill.skillPath, targetName, nameMaps)
+
+    if (skill.name === targetName && alreadyPiCompatible) {
+      await forceSymlink(skill.sourceDir, target)
+      continue
+    }
+
+    await copySkillDirForPi(skill.sourceDir, target, targetName, nameMaps)
+  }
+}

src/sync/pi.ts

@@ -1,10 +1,12 @@
 import path from "path"
 import type { ClaudeHomeConfig } from "../parsers/claude-home"
 import type { ClaudeMcpServer } from "../types/claude"
-import { ensureDir } from "../utils/files"
+import { ensureDir, writeText } from "../utils/files"
+import { normalizePiSkillName, uniquePiSkillName } from "../utils/pi-skills"
+import { PI_COMPAT_EXTENSION_SOURCE } from "../templates/pi/compat-extension"
 import { syncPiCommands } from "./commands"
 import { mergeJsonConfigAtKey } from "./json-config"
-import { syncSkills } from "./skills"
+import { syncPiSkills } from "./pi-skills"
 
 type McporterServer = {
   baseUrl?: string
@@ -24,9 +26,26 @@ export async function syncToPi(
 ): Promise<void> {
   const mcporterPath = path.join(outputRoot, "compound-engineering", "mcporter.json")
 
-  await syncSkills(config.skills, path.join(outputRoot, "skills"))
+  const commands = [...(config.commands ?? [])].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)
+  const promptNames = new Set<string>()
+  const promptMap: Record<string, string> = {}
+  for (const command of commands) {
+    if (command.disableModelInvocation) continue
+    const targetName = uniquePiSkillName(normalizePiSkillName(command.name), promptNames)
+    promptMap[command.name] = targetName
+  }
+
+  await syncPiSkills(config.skills, path.join(outputRoot, "skills"), { prompts: promptMap })
   await syncPiCommands(config, outputRoot)
 
+  if (config.skills.length > 0) {
+    await ensureDir(path.join(outputRoot, "extensions"))
+    await writeText(
+      path.join(outputRoot, "extensions", "compound-engineering-compat.ts"),
+      PI_COMPAT_EXTENSION_SOURCE + "\n",
+    )
+  }
+
   if (Object.keys(config.mcpServers).length > 0) {
     await ensureDir(path.dirname(mcporterPath))
     const converted = convertMcpToMcporter(config.mcpServers)

src/targets/pi.ts

@@ -1,14 +1,13 @@
 import path from "path"
 import {
   backupFile,
-  copySkillDir,
   ensureDir,
   pathExists,
   readText,
   writeJson,
   writeText,
 } from "../utils/files"
-import { transformContentForPi } from "../converters/claude-to-pi"
+import { copySkillDirForPi } from "../utils/pi-skills"
 import type { PiBundle } from "../types/pi"
 
 const PI_AGENTS_BLOCK_START = "<!-- BEGIN COMPOUND PI TOOL MAP -->"
@@ -19,8 +18,8 @@ const PI_AGENTS_BLOCK_BODY = `## Compound Engineering (Pi compatibility)
 This block is managed by compound-plugin.
 
 Compatibility notes:
-- Claude Task(agent, args) maps to the subagent extension tool
-- For parallel agent runs, batch multiple subagent calls with multi_tool_use.parallel
+- Claude Task(agent, args) maps to the ce_subagent extension tool
+- Use ce_subagent for Compound Engineering workflows even when another extension also provides a generic subagent tool
 - AskUserQuestion maps to the ask_user_question extension tool
 - MCP access uses MCPorter via mcporter_list and mcporter_call extension tools
 - MCPorter config path: .pi/compound-engineering/mcporter.json (project) or ~/.pi/agent/compound-engineering/mcporter.json (global)
@@ -38,7 +37,7 @@ export async function writePiBundle(outputRoot: string, bundle: PiBundle): Promi
   }
 
   for (const skill of bundle.skillDirs) {
-    await copySkillDir(skill.sourceDir, path.join(paths.skillsDir, skill.name), transformContentForPi)
+    await copySkillDirForPi(skill.sourceDir, path.join(paths.skillsDir, skill.name), skill.name, bundle.nameMaps)
   }
 
   for (const skill of bundle.generatedSkills) {

src/templates/pi/compat-extension.ts

@@ -245,9 +245,9 @@ export default function (pi: ExtensionAPI) {
   })
 
   pi.registerTool({
-    name: "subagent",
-    label: "Subagent",
-    description: "Run one or more skill-based subagent tasks. Supports single, parallel, and chained execution.",
+    name: "ce_subagent",
+    label: "Compound Engineering Subagent",
+    description: "Run one or more Compound Engineering skill-based subagent tasks. Supports single, parallel, and chained execution.",
     parameters: Type.Object({
       agent: Type.Optional(Type.String({ description: "Single subagent name" })),
       task: Type.Optional(Type.String({ description: "Single subagent task" })),

src/types/pi.ts

@@ -37,4 +37,5 @@ export type PiBundle = {
   generatedSkills: PiGeneratedSkill[]
   extensions: PiExtensionFile[]
   mcporterConfig?: PiMcporterConfig
+  nameMaps?: import("../utils/pi-skills").PiNameMaps
 }