@supercorks/skills-installer 1.11.1 → 1.13.0

package/README.md

@@ -1,6 +1,6 @@
 # @supercorks/skills-installer
 
-Interactive CLI installer for AI agent skills and subagents. Selectively install resources for GitHub Copilot, Codex, Claude, and other AI assistants using Git sparse-checkout.
+Interactive CLI installer for AI agent skills and subagents. Selectively install resources for GitHub Copilot, Codex, Claude, and other AI assistants using Git sparse-checkout and Codex agent conversion where needed.
 
 ## Usage
 
@@ -18,25 +18,35 @@ npx @supercorks/skills-installer install
 
 1. **Choose installation type** - Install skills, subagents, or both.
 
-2. **Choose installation path(s)** - Select one or more locations where resources should be installed:
-   - `.github/skills/` (Copilot)
-   - `~/.codex/skills/` (Codex)
-   - `.claude/skills/` (Claude)
-   - `.github/agents/` (Copilot)
-   - `.agents/agents/` (Codex)
-   - `.claude/agents/` (Claude)
+2. **Choose installation path(s)** - Select one or more locations where resources should be installed. Global locations are shown before local locations. The installer labels each option with harness, scope, and available count, for example `~/.agents/skills/ (copilot/codex | global | 24 skills)`.
+
+   Skills:
+   - `~/.agents/skills/` (copilot/codex | global)
+   - `~/.claude/skills/` (claude | global)
+   - `.agents/skills/` (copilot/codex | local)
+   - `.claude/skills/` (claude | local)
+
+   Agents:
+   - `~/.agents/agents/` (copilot | global)
+   - `~/.claude/agents/` (claude | global)
+   - `~/.codex/agents/` (codex | global, installed as converted TOML agents)
+   - `.agents/agents/` (copilot | local)
+   - `.claude/agents/` (claude | local)
+   - `.codex/agents/` (codex | local, installed as converted TOML agents)
    - Custom path of your choice
 
 3. **Gitignore option** - If launched from inside a git repository, optionally add the installation path to `.gitignore`
 
-4. **Select skills/subagents** - Interactive checkbox to pick what to install:
+4. **Select skills/subagents** - Interactive checkbox to pick what to install. If multiple locations are selected, the installer asks once and applies the same selection to every selected location:
    - Use `↑`/`↓` to navigate
    - Use `SPACE` to toggle selection
    - Use `→` to expand and lazy-load descriptions
    - Use `A` to toggle all
    - Press `ENTER` to confirm
 
-5. **Sparse clone** - Only downloads selected skills/subagents using Git sparse-checkout, keeping the download minimal while preserving full git functionality.
+5. **Install backend**
+   - Skills and Markdown-based agents use Git sparse-checkout for minimal download while preserving full git functionality.
+   - Codex agents are generated as TOML files from the source Markdown agent definitions.
 
 ## Installed repositories
 
@@ -48,6 +58,8 @@ npx @supercorks/skills-installer install
 - **Minimal download** - Uses `git clone --filter=blob:none` for efficient cloning
 - **Push capable** - The sparse clone preserves the full git history, allowing you to commit and push changes
 - **Auto-discovery** - Fetches the latest skill list from the repository
+- **Global and local targets** - Offers documented project/user locations for Copilot, Codex, and Claude where the resource format is compatible, with shared generic `~/.agents/skills/` and `.agents/skills/` targets for Copilot/Codex skills
+- **Codex agent conversion** - Converts Markdown subagents into Codex TOML custom agents for `.codex/agents/` targets
 - **Recursive directory creation** - Custom paths are created automatically
 
 ## Requirements
@@ -60,7 +72,7 @@ npx @supercorks/skills-installer install
 Since the installation uses a sparse git checkout, you can pull updates:
 
 ```bash
-cd .github/skills  # or wherever you installed
+cd .agents/skills  # or wherever you installed
 git pull
 ```
 
@@ -69,7 +81,7 @@ git pull
 You can add more skills to an existing installation:
 
 ```bash
-cd .github/skills
+cd .agents/skills
 git sparse-checkout add new-skill-name
 ```
 

package/bin/install.js

@@ -37,13 +37,15 @@ import {
   checkSubagentsForUpdates
 } from '../lib/git.js';
 import { createRequire } from 'module';
+import { allAgentDetectionTargets, allSkillDetectionTargets, getAgentInstallMode } from '../lib/install-targets.js';
+import { checkCodexAgentUpdates, listInstalledCodexAgents, syncCodexAgents } from '../lib/codex-agents.js';
 
 const require = createRequire(import.meta.url);
 const { version: VERSION } = require('../package.json');
 
 // Common installation paths to check for existing installations
-const SKILL_PATHS = ['.github/skills/', '~/.codex/skills/', '.claude/skills/'];
-const AGENT_PATHS = ['.github/agents/', '.agents/agents/', '.claude/agents/'];
+const SKILL_PATHS = allSkillDetectionTargets().map(target => target.path);
+const AGENT_PATHS = allAgentDetectionTargets().map(target => target.path);
 
 function resolveInstallPath(path) {
   if (path === '~') return homedir();
@@ -55,6 +57,14 @@ function isHomePath(path) {
   return path === '~' || path.startsWith('~/');
 }
 
+function uniqueItems(items) {
+  return Array.from(new Set(items));
+}
+
+function unionSets(sets) {
+  return new Set(sets.flatMap(set => Array.from(set)));
+}
+
 /**
  * Detect existing skill installations in common paths
  * @returns {Promise<Array<{path: string, skillCount: number, skills: string[]}>>}
@@ -92,6 +102,24 @@ async function detectExistingAgentInstallations() {
   
   for (const path of AGENT_PATHS) {
     const absolutePath = resolveInstallPath(path);
+    const installMode = getAgentInstallMode(path);
+
+    if (installMode === 'codex-toml') {
+      try {
+        const agents = await listInstalledCodexAgents(absolutePath);
+        if (agents.length > 0) {
+          installations.push({
+            path,
+            agentCount: agents.length,
+            agents
+          });
+        }
+      } catch {
+        // Ignore errors reading existing installations
+      }
+      continue;
+    }
+
     const gitDir = join(absolutePath, '.git');
     
     if (existsSync(gitDir)) {
@@ -220,24 +248,41 @@ async function runSkillsInstall() {
   const existingInstalls = await detectExistingSkillInstallations();
 
   // Ask where to install (showing existing installations if any)
-  const installTargets = await promptInstallPath(existingInstalls);
+  const installTargets = await promptInstallPath(existingInstalls, skills.length);
 
-  for (let i = 0; i < installTargets.length; i++) {
-    const target = installTargets[i];
+  const targetContexts = [];
+  for (const [index, target] of installTargets.entries()) {
     if (installTargets.length > 1) {
-      console.log(`\n📍 Skills target ${i + 1}/${installTargets.length}: ${target.path}`);
+      console.log(`\n📍 Preparing skills target ${index + 1}/${installTargets.length}: ${target.path}`);
+    }
+    targetContexts.push(await prepareSkillsInstallTarget(existingInstalls, target));
+  }
+
+  const installedSkills = uniqueItems(targetContexts.flatMap(context => context.installedSkills));
+  const skillsNeedingUpdate = unionSets(targetContexts.map(context => context.skillsNeedingUpdate));
+
+  const selectedSkills = await promptSkillSelection(
+    skills,
+    installedSkills,
+    skillsNeedingUpdate,
+    (skillFolder) => fetchSkillMetadata(skillFolder)
+  );
+
+  for (let i = 0; i < targetContexts.length; i++) {
+    if (targetContexts.length > 1) {
+      console.log(`\n📍 Skills target ${i + 1}/${targetContexts.length}: ${targetContexts[i].installPath}`);
     }
-    await runSkillsInstallForTarget(skills, existingInstalls, target);
+    await runSkillsInstallForTarget(skills, targetContexts[i], selectedSkills);
   }
 }
 
 /**
- * Install/update skills for a specific target path
- * @param {Array<{name: string, description: string, folder: string}>} skills
+ * Prepare a specific skills target for installation/update.
  * @param {Array<{path: string, skillCount: number, skills: string[]}>} existingInstalls
  * @param {{path: string, isExisting: boolean}} target
+ * @returns {Promise<object>}
  */
-async function runSkillsInstallForTarget(skills, existingInstalls, target) {
+async function prepareSkillsInstallTarget(existingInstalls, target) {
   const { path: installPath, isExisting } = target;
   const absoluteInstallPath = resolveInstallPath(installPath);
   const gitDir = join(absoluteInstallPath, '.git');
@@ -291,13 +336,33 @@ async function runSkillsInstallForTarget(skills, existingInstalls, target) {
     shouldGitignore = await promptGitignore(installPath);
   }
 
-  // Select skills (pre-select installed skills in manage mode)
-  const selectedSkills = await promptSkillSelection(
-    skills,
+  return {
+    ...target,
+    installPath,
+    absoluteInstallPath,
     installedSkills,
-    skillsNeedingUpdate,
-    (skillFolder) => fetchSkillMetadata(skillFolder)
-  );
+    isManageMode,
+    shouldGitignore,
+    gitignorePath,
+    skillsNeedingUpdate
+  };
+}
+
+/**
+ * Install/update skills for a specific target path
+ * @param {Array<{name: string, description: string, folder: string}>} skills
+ * @param {object} targetContext
+ * @param {string[]} selectedSkills
+ */
+async function runSkillsInstallForTarget(skills, targetContext, selectedSkills) {
+  const {
+    installPath,
+    absoluteInstallPath,
+    installedSkills,
+    isManageMode,
+    shouldGitignore,
+    gitignorePath
+  } = targetContext;
 
   // Perform installation or update
   console.log('');
@@ -380,35 +445,53 @@ async function runSubagentsInstall() {
   const existingInstalls = await detectExistingAgentInstallations();
 
   // Ask where to install (showing existing installations if any)
-  const installTargets = await promptAgentInstallPath(existingInstalls);
+  const installTargets = await promptAgentInstallPath(existingInstalls, subagents.length);
 
-  for (let i = 0; i < installTargets.length; i++) {
-    const target = installTargets[i];
+  const targetContexts = [];
+  for (const [index, target] of installTargets.entries()) {
     if (installTargets.length > 1) {
-      console.log(`\n📍 Subagents target ${i + 1}/${installTargets.length}: ${target.path}`);
+      console.log(`\n📍 Preparing subagents target ${index + 1}/${installTargets.length}: ${target.path}`);
+    }
+    targetContexts.push(await prepareSubagentsInstallTarget(existingInstalls, target));
+  }
+
+  const installedAgents = uniqueItems(targetContexts.flatMap(context => context.installedAgents));
+  const subagentsNeedingUpdate = unionSets(targetContexts.map(context => context.subagentsNeedingUpdate));
+
+  const selectedAgents = await promptSubagentSelection(
+    subagents,
+    installedAgents,
+    subagentsNeedingUpdate,
+    (filename) => fetchSubagentMetadata(filename)
+  );
+
+  for (let i = 0; i < targetContexts.length; i++) {
+    if (targetContexts.length > 1) {
+      console.log(`\n📍 Subagents target ${i + 1}/${targetContexts.length}: ${targetContexts[i].installPath}`);
     }
-    await runSubagentsInstallForTarget(subagents, existingInstalls, target);
+    await runSubagentsInstallForTarget(subagents, targetContexts[i], selectedAgents);
   }
 }
 
 /**
- * Install/update subagents for a specific target path
- * @param {Array<{name: string, description: string, filename: string}>} subagents
+ * Prepare a specific subagent target for installation/update.
  * @param {Array<{path: string, agentCount: number, agents: string[]}>} existingInstalls
  * @param {{path: string, isExisting: boolean}} target
+ * @returns {Promise<object>}
  */
-async function runSubagentsInstallForTarget(subagents, existingInstalls, target) {
+async function prepareSubagentsInstallTarget(existingInstalls, target) {
   const { path: installPath, isExisting } = target;
   const absoluteInstallPath = resolveInstallPath(installPath);
+  const installMode = getAgentInstallMode(installPath);
   const gitDir = join(absoluteInstallPath, '.git');
-  const hasExistingRepo = existsSync(gitDir);
+  const hasExistingRepo = installMode === 'sparse-git' && existsSync(gitDir);
 
   // Get currently installed subagents if managing existing installation
   let installedAgents = [];
   if (isExisting) {
     const existingInstall = existingInstalls.find(i => i.path === installPath);
     installedAgents = existingInstall?.agents || [];
-  } else {
+  } else if (installMode === 'sparse-git') {
     // Check if manually entered path has an existing installation
     if (hasExistingRepo) {
       try {
@@ -418,16 +501,27 @@ async function runSubagentsInstallForTarget(subagents, existingInstalls, target)
         // Prompt will default to selecting all subagents.
       }
     }
+  } else {
+    try {
+      installedAgents = await listInstalledCodexAgents(absoluteInstallPath);
+    } catch {
+      // Ignore detection failures for custom Codex agent paths.
+    }
   }
 
-  const isManageMode = isExisting || hasExistingRepo || installedAgents.length > 0;
+  const isManageMode = installMode === 'sparse-git'
+    ? (isExisting || hasExistingRepo || installedAgents.length > 0)
+    : installedAgents.length > 0;
 
   // Check for updates if in manage mode
   let subagentsNeedingUpdate = new Set();
   if (isManageMode) {
     const updateSpinner = showSpinner('Checking for available updates...');
     try {
-      subagentsNeedingUpdate = await checkSubagentsForUpdates(absoluteInstallPath, installedAgents);
+      subagentsNeedingUpdate = installMode === 'sparse-git'
+        ? await checkSubagentsForUpdates(absoluteInstallPath, installedAgents)
+        : await checkCodexAgentUpdates(absoluteInstallPath, installedAgents);
+
       if (subagentsNeedingUpdate.size > 0) {
         updateSpinner.stop(`✅ Found ${subagentsNeedingUpdate.size} subagent${subagentsNeedingUpdate.size !== 1 ? 's' : ''} with updates available`);
       } else {
@@ -451,13 +545,35 @@ async function runSubagentsInstallForTarget(subagents, existingInstalls, target)
     shouldGitignore = await promptGitignore(installPath);
   }
 
-  // Select subagents (pre-select installed ones in manage mode)
-  const selectedAgents = await promptSubagentSelection(
-    subagents,
+  return {
+    ...target,
+    installPath,
+    absoluteInstallPath,
+    installMode,
     installedAgents,
-    subagentsNeedingUpdate,
-    (filename) => fetchSubagentMetadata(filename)
-  );
+    isManageMode,
+    shouldGitignore,
+    gitignorePath,
+    subagentsNeedingUpdate
+  };
+}
+
+/**
+ * Install/update subagents for a specific target path
+ * @param {Array<{name: string, description: string, filename: string}>} subagents
+ * @param {object} targetContext
+ * @param {string[]} selectedAgents
+ */
+async function runSubagentsInstallForTarget(subagents, targetContext, selectedAgents) {
+  const {
+    installPath,
+    absoluteInstallPath,
+    installMode,
+    installedAgents,
+    isManageMode,
+    shouldGitignore,
+    gitignorePath
+  } = targetContext;
 
   // Perform installation or update
   console.log('');
@@ -475,9 +591,15 @@ async function runSubagentsInstallForTarget(subagents, existingInstalls, target)
     const updateSpinner = showSpinner('Updating subagents installation...');
     
     try {
-      await updateSubagentsSparseCheckout(absoluteInstallPath, selectedAgents, (message) => {
-        updateSpinner.stop(`   ${message}`);
-      });
+      if (installMode === 'sparse-git') {
+        await updateSubagentsSparseCheckout(absoluteInstallPath, selectedAgents, (message) => {
+          updateSpinner.stop(`   ${message}`);
+        });
+      } else {
+        await syncCodexAgents(absoluteInstallPath, selectedAgents, (message) => {
+          updateSpinner.stop(`   ${message}`);
+        });
+      }
     } catch (error) {
       updateSpinner.stop('❌ Update failed');
       showError(error.message);
@@ -490,9 +612,15 @@ async function runSubagentsInstallForTarget(subagents, existingInstalls, target)
     const installSpinner = showSpinner('Installing selected subagents...');
     
     try {
-      await sparseCloneSubagents(installPath, selectedAgents, (message) => {
-        installSpinner.stop(`   ${message}`);
-      });
+      if (installMode === 'sparse-git') {
+        await sparseCloneSubagents(installPath, selectedAgents, (message) => {
+          installSpinner.stop(`   ${message}`);
+        });
+      } else {
+        await syncCodexAgents(absoluteInstallPath, selectedAgents, (message) => {
+          installSpinner.stop(`   ${message}`);
+        });
+      }
     } catch (error) {
       installSpinner.stop('❌ Installation failed');
       showError(error.message);

package/lib/codex-agents.js

@@ -0,0 +1,165 @@
+/**
+ * Convert Markdown subagent definitions into Codex TOML custom agents.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { join, resolve } from 'path';
+import { homedir } from 'os';
+import { fetchSubagentContent, humanizeAgentName, parseSubagentDefinition } from './subagents.js';
+
+const GENERATED_COMMENT_PREFIX = '# Generated by @supercorks/skills-installer from ';
+
+function resolvePath(path) {
+  if (path === '~') return homedir();
+  if (path.startsWith('~/')) return resolve(homedir(), path.slice(2));
+  return resolve(path);
+}
+
+export function codexTomlFilenameForAgent(agentFilename) {
+  return `${agentFilename.replace(/\.agent\.md$/i, '')}.toml`;
+}
+
+export function codexAgentNameForAgent(agentFilename, displayName = '') {
+  const preferred = displayName || agentFilename.replace(/\.agent\.md$/i, '');
+  return preferred
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '') || 'agent';
+}
+
+function escapeTomlBasicString(value) {
+  return String(value)
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, ' ')
+    .trim();
+}
+
+function formatDeveloperInstructions(body) {
+  const normalizedBody = (body || '').replace(/\r\n/g, '\n').trim();
+  if (!normalizedBody) {
+    return "developer_instructions = '''\nAct as the requested specialist and complete the assigned task.\n'''";
+  }
+
+  if (!normalizedBody.includes("'''")) {
+    return `developer_instructions = '''\n${normalizedBody}\n'''`;
+  }
+
+  const escaped = normalizedBody
+    .replace(/\\/g, '\\\\')
+    .replace(/"""/g, '\\"\\"\\"');
+
+  return `developer_instructions = """\n${escaped}\n"""`;
+}
+
+export function convertSubagentMarkdownToCodexToml(content, agentFilename) {
+  const definition = parseSubagentDefinition(content, agentFilename);
+  const outputFilename = codexTomlFilenameForAgent(agentFilename);
+  const codexName = codexAgentNameForAgent(agentFilename, definition.name);
+  const description = definition.description || `${humanizeAgentName(agentFilename)} custom agent`;
+
+  const toml = [
+    `${GENERATED_COMMENT_PREFIX}${agentFilename}`,
+    `name = "${escapeTomlBasicString(codexName)}"`,
+    `description = "${escapeTomlBasicString(description)}"`,
+    formatDeveloperInstructions(definition.body),
+    '',
+  ].join('\n');
+
+  return {
+    sourceFilename: agentFilename,
+    outputFilename,
+    name: definition.name,
+    description,
+    toml,
+  };
+}
+
+function parseGeneratedSourceFilename(tomlContent, outputFilename) {
+  const commentMatch = tomlContent.match(/^# Generated by @supercorks\/skills-installer from ([^\n]+)$/m);
+  if (commentMatch) {
+    return commentMatch[1].trim();
+  }
+
+  return null;
+}
+
+function listGeneratedCodexAgentEntries(targetPath) {
+  const absolutePath = resolvePath(targetPath);
+  if (!existsSync(absolutePath)) {
+    return [];
+  }
+
+  return readdirSync(absolutePath)
+    .filter(name => name.endsWith('.toml'))
+    .map(outputFilename => {
+      const absoluteFilePath = join(absolutePath, outputFilename);
+      const content = readFileSync(absoluteFilePath, 'utf8');
+      const sourceFilename = parseGeneratedSourceFilename(content, outputFilename);
+      if (!sourceFilename) {
+        return null;
+      }
+
+      return {
+        sourceFilename,
+        outputFilename,
+        absoluteFilePath,
+        content,
+      };
+    })
+    .filter(Boolean);
+}
+
+export async function listInstalledCodexAgents(targetPath) {
+  return listGeneratedCodexAgentEntries(targetPath).map(entry => entry.sourceFilename);
+}
+
+export async function checkCodexAgentUpdates(targetPath, agentFilenames) {
+  const installedEntries = listGeneratedCodexAgentEntries(targetPath);
+  const bySourceFilename = new Map(installedEntries.map(entry => [entry.sourceFilename, entry]));
+  const needsUpdate = new Set();
+
+  for (const agentFilename of agentFilenames) {
+    const entry = bySourceFilename.get(agentFilename);
+    if (!entry) {
+      continue;
+    }
+
+    try {
+      const content = await fetchSubagentContent(agentFilename);
+      const converted = convertSubagentMarkdownToCodexToml(content, agentFilename);
+      if (converted.toml !== entry.content) {
+        needsUpdate.add(agentFilename);
+      }
+    } catch {
+      // Skip update markers when the remote file cannot be fetched.
+    }
+  }
+
+  return needsUpdate;
+}
+
+export async function syncCodexAgents(targetPath, agentFilenames, onProgress = () => {}) {
+  const absolutePath = resolvePath(targetPath);
+  mkdirSync(absolutePath, { recursive: true });
+
+  const existingEntries = listGeneratedCodexAgentEntries(absolutePath);
+  const selectedSet = new Set(agentFilenames);
+
+  for (const entry of existingEntries) {
+    if (!selectedSet.has(entry.sourceFilename) && existsSync(entry.absoluteFilePath)) {
+      rmSync(entry.absoluteFilePath, { force: true });
+    }
+  }
+
+  for (let index = 0; index < agentFilenames.length; index += 1) {
+    const agentFilename = agentFilenames[index];
+    onProgress(`Converting ${index + 1}/${agentFilenames.length}: ${agentFilename}`);
+    const content = await fetchSubagentContent(agentFilename);
+    const converted = convertSubagentMarkdownToCodexToml(content, agentFilename);
+    writeFileSync(join(absolutePath, converted.outputFilename), converted.toml, 'utf8');
+  }
+
+  onProgress('Done!');
+}

package/lib/install-targets.js

@@ -0,0 +1,99 @@
+/**
+ * Supported install targets for skills and agents.
+ */
+
+export const SKILL_INSTALL_TARGETS = [
+  { path: '~/.agents/skills/', harness: 'copilot/codex', scope: 'global' },
+  { path: '~/.claude/skills/', harness: 'claude', scope: 'global' },
+  { path: '.agents/skills/', harness: 'copilot/codex', scope: 'local' },
+  { path: '.claude/skills/', harness: 'claude', scope: 'local' }
+];
+
+export const LEGACY_SKILL_INSTALL_TARGETS = [
+  {
+    path: '.github/skills/',
+    harness: 'copilot',
+    scope: 'legacy local'
+  },
+  {
+    path: '~/.copilot/skills/',
+    harness: 'copilot',
+    scope: 'legacy global'
+  },
+  {
+    path: '~/.codex/skills/',
+    harness: 'codex',
+    scope: 'legacy global'
+  }
+];
+
+export const AGENT_INSTALL_TARGETS = [
+  { path: '~/.agents/agents/', harness: 'copilot', scope: 'global', installMode: 'sparse-git' },
+  { path: '~/.claude/agents/', harness: 'claude', scope: 'global', installMode: 'sparse-git' },
+  { path: '~/.codex/agents/', harness: 'codex', scope: 'global', installMode: 'codex-toml' },
+  { path: '.agents/agents/', harness: 'copilot', scope: 'local', installMode: 'sparse-git' },
+  { path: '.claude/agents/', harness: 'claude', scope: 'local', installMode: 'sparse-git' },
+  { path: '.codex/agents/', harness: 'codex', scope: 'local', installMode: 'codex-toml' }
+];
+
+export const LEGACY_AGENT_INSTALL_TARGETS = [
+  {
+    path: '.github/agents/',
+    harness: 'copilot',
+    scope: 'legacy local'
+  },
+  {
+    path: '~/.copilot/agents/',
+    harness: 'copilot',
+    scope: 'legacy global'
+  }
+];
+
+export function allSkillDetectionTargets() {
+  return [...SKILL_INSTALL_TARGETS, ...LEGACY_SKILL_INSTALL_TARGETS];
+}
+
+export function allAgentDetectionTargets() {
+  return [...AGENT_INSTALL_TARGETS, ...LEGACY_AGENT_INSTALL_TARGETS];
+}
+
+export function orderTargetsGlobalFirst(targets) {
+  return [...targets].sort((left, right) => {
+    const leftGlobal = left.scope.includes('global') ? 0 : 1;
+    const rightGlobal = right.scope.includes('global') ? 0 : 1;
+
+    if (leftGlobal !== rightGlobal) {
+      return leftGlobal - rightGlobal;
+    }
+
+    return targets.indexOf(left) - targets.indexOf(right);
+  });
+}
+
+export function getAgentInstallMode(path) {
+  const exactTarget = getTargetByPath(AGENT_INSTALL_TARGETS, path);
+  if (exactTarget?.installMode) {
+    return exactTarget.installMode;
+  }
+
+  const normalizedPath = path.replace(/\\/g, '/').replace(/\/+$/, '');
+  if (normalizedPath.endsWith('/.codex/agents') || normalizedPath === '.codex/agents' || normalizedPath === '~/.codex/agents') {
+    return 'codex-toml';
+  }
+
+  return 'sparse-git';
+}
+
+export function getTargetByPath(targets, path) {
+  return targets.find(target => target.path === path);
+}
+
+export function formatTargetLabel(target, count, noun, { installed = false } = {}) {
+  const plural = count === 1 ? noun : `${noun}s`;
+  const countText = installed ? `${count} ${plural} installed` : `${count} ${plural}`;
+  const detail = target
+    ? `${target.harness} | ${target.scope} | ${countText}`
+    : countText;
+
+  return `${target?.path || ''} (${detail})`;
+}

package/lib/prompts.js

@@ -4,18 +4,21 @@
 
 import inquirer from 'inquirer';
 import * as readline from 'readline';
+import {
+  AGENT_INSTALL_TARGETS,
+  SKILL_INSTALL_TARGETS,
+  allAgentDetectionTargets,
+  allSkillDetectionTargets,
+  formatTargetLabel,
+  getTargetByPath,
+  orderTargetsGlobalFirst
+} from './install-targets.js';
 
 const SKILL_PATH_CHOICES = {
-  GITHUB: '.github/skills/',
-  CODEX_HOME: '~/.codex/skills/',
-  CLAUDE: '.claude/skills/',
   CUSTOM: '__custom__'
 };
 
 const AGENT_PATH_CHOICES = {
-  GITHUB: '.github/agents/',
-  CODEX: '.agents/agents/',
-  CLAUDE: '.claude/agents/',
   CUSTOM: '__custom__'
 };
 
@@ -61,36 +64,44 @@ export async function promptInstallType() {
 /**
  * Prompt user to select one or more installation paths, showing existing installations
  * @param {Array<{path: string, skillCount: number}>} existingInstalls - Detected existing installations
+ * @param {number} availableSkillCount - Number of skills available for new installations
  * @returns {Promise<Array<{path: string, isExisting: boolean}>>} Selected paths and whether each is existing
  */
-export async function promptInstallPath(existingInstalls = []) {
+export async function promptInstallPath(existingInstalls = [], availableSkillCount = 0) {
   const choices = [];
-  const existingPaths = existingInstalls.map(i => i.path);
+  const detectionTargets = allSkillDetectionTargets();
+  const existingByPath = new Map(existingInstalls.map(install => [install.path, install]));
+  const standardPaths = new Set(SKILL_INSTALL_TARGETS.map(target => target.path));
   
-  // Add existing installations at the top
-  if (existingInstalls.length > 0) {
-    existingInstalls.forEach(install => {
+  orderTargetsGlobalFirst(SKILL_INSTALL_TARGETS).forEach(target => {
+    const install = existingByPath.get(target.path);
+    choices.push({
+      name: install
+        ? formatTargetLabel(target, install.skillCount, 'skill', { installed: true })
+        : formatTargetLabel(target, availableSkillCount, 'skill'),
+      value: target.path
+    });
+  });
+
+  const existingLegacyOrCustom = existingInstalls.filter(install => !standardPaths.has(install.path));
+  if (existingLegacyOrCustom.length > 0) {
+    choices.push(new inquirer.Separator('── Existing legacy/custom installations ──'));
+    orderTargetsGlobalFirst(existingLegacyOrCustom.map(install => getTargetByPath(detectionTargets, install.path) || {
+      path: install.path,
+      harness: 'custom',
+      scope: 'existing'
+    })).forEach(target => {
+      const install = existingByPath.get(target.path);
       choices.push({
-        name: `${install.path} (${install.skillCount} skill${install.skillCount !== 1 ? 's' : ''} installed)`,
+        name: target
+          ? formatTargetLabel(target, install.skillCount, 'skill', { installed: true })
+          : `${install.path} (${install.skillCount} skill${install.skillCount !== 1 ? 's' : ''} installed)`,
         value: install.path
       });
     });
-    choices.push(new inquirer.Separator('── New installation ──'));
   }
-  
-  // Standard path options
-  const standardPaths = [
-    { path: SKILL_PATH_CHOICES.GITHUB, label: `${SKILL_PATH_CHOICES.GITHUB} (Copilot)` },
-    { path: SKILL_PATH_CHOICES.CODEX_HOME, label: `${SKILL_PATH_CHOICES.CODEX_HOME} (Codex)` },
-    { path: SKILL_PATH_CHOICES.CLAUDE, label: `${SKILL_PATH_CHOICES.CLAUDE} (Claude)` }
-  ];
-  
-  standardPaths.forEach(({ path, label }) => {
-    if (!existingPaths.includes(path)) {
-      choices.push({ name: label, value: path });
-    }
-  });
-  
+
+  choices.push(new inquirer.Separator('── Other ──'));
   choices.push({ name: 'Custom path...', value: SKILL_PATH_CHOICES.CUSTOM });
 
   const { pathChoices } = await inquirer.prompt([
@@ -116,7 +127,7 @@ export async function promptInstallPath(existingInstalls = []) {
   pathChoices
     .filter(path => path !== SKILL_PATH_CHOICES.CUSTOM)
     .forEach(path => {
-      selected.push({ path, isExisting: existingPaths.includes(path) });
+      selected.push({ path, isExisting: existingByPath.has(path) });
     });
 
   if (selectedSet.has(SKILL_PATH_CHOICES.CUSTOM)) {
@@ -144,36 +155,45 @@ export async function promptInstallPath(existingInstalls = []) {
 /**
  * Prompt user to select one or more subagent installation paths
  * @param {Array<{path: string, agentCount: number}>} existingInstalls - Detected existing installations
+ * @param {number} availableAgentCount - Number of agents available for new installations
  * @returns {Promise<Array<{path: string, isExisting: boolean}>>} Selected paths and whether each is existing
  */
-export async function promptAgentInstallPath(existingInstalls = []) {
+export async function promptAgentInstallPath(existingInstalls = [], availableAgentCount = 0) {
   const choices = [];
-  const existingPaths = existingInstalls.map(i => i.path);
+  const detectionTargets = allAgentDetectionTargets();
+  const existingByPath = new Map(existingInstalls.map(install => [install.path, install]));
+  const standardPaths = new Set(AGENT_INSTALL_TARGETS.map(target => target.path));
   
-  // Add existing installations at the top
-  if (existingInstalls.length > 0) {
-    existingInstalls.forEach(install => {
+  orderTargetsGlobalFirst(AGENT_INSTALL_TARGETS).forEach(target => {
+    const install = existingByPath.get(target.path);
+    choices.push({
+      name: install
+        ? formatTargetLabel(target, install.agentCount, 'agent', { installed: true })
+        : formatTargetLabel(target, availableAgentCount, 'agent'),
+      value: target.path,
+      disabled: target.disabledReason
+    });
+  });
+
+  const existingLegacyOrCustom = existingInstalls.filter(install => !standardPaths.has(install.path));
+  if (existingLegacyOrCustom.length > 0) {
+    choices.push(new inquirer.Separator('── Existing legacy/custom installations ──'));
+    orderTargetsGlobalFirst(existingLegacyOrCustom.map(install => getTargetByPath(detectionTargets, install.path) || {
+      path: install.path,
+      harness: 'custom',
+      scope: 'existing'
+    })).forEach(target => {
+      const install = existingByPath.get(target.path);
       choices.push({
-        name: `${install.path} (${install.agentCount} agent${install.agentCount !== 1 ? 's' : ''} installed)`,
+        name: target
+          ? formatTargetLabel(target, install.agentCount, 'agent', { installed: true })
+          : `${install.path} (${install.agentCount} agent${install.agentCount !== 1 ? 's' : ''} installed)`,
         value: install.path
       });
     });
-    choices.push(new inquirer.Separator('── New installation ──'));
   }
-  
-  // Standard path options
-  const standardPaths = [
-    { path: AGENT_PATH_CHOICES.GITHUB, label: `${AGENT_PATH_CHOICES.GITHUB} (Copilot)` },
-    { path: AGENT_PATH_CHOICES.CODEX, label: `${AGENT_PATH_CHOICES.CODEX} (Codex)` },
-    { path: AGENT_PATH_CHOICES.CLAUDE, label: `${AGENT_PATH_CHOICES.CLAUDE} (Claude)` }
-  ];
-  
-  standardPaths.forEach(({ path, label }) => {
-    if (!existingPaths.includes(path)) {
-      choices.push({ name: label, value: path });
-    }
-  });
-  
+
+  choices.push(new inquirer.Separator('── Other ──'));
   choices.push({ name: 'Custom path...', value: AGENT_PATH_CHOICES.CUSTOM });
 
   const { pathChoices } = await inquirer.prompt([
@@ -199,7 +219,7 @@ export async function promptAgentInstallPath(existingInstalls = []) {
   pathChoices
     .filter(path => path !== AGENT_PATH_CHOICES.CUSTOM)
     .forEach(path => {
-      selected.push({ path, isExisting: existingPaths.includes(path) });
+      selected.push({ path, isExisting: existingByPath.has(path) });
     });
 
   if (selectedSet.has(AGENT_PATH_CHOICES.CUSTOM)) {

package/lib/subagents.js

@@ -17,6 +17,29 @@ function humanizeAgentName(filename) {
     .join(' ');
 }
 
+function extractSubagentSections(content) {
+  const standardMatch = content.match(/^(---\s*\n[\s\S]*?\n---)(?:\s*\n)?/);
+  if (standardMatch) {
+    return {
+      frontmatter: standardMatch[1].replace(/^---\s*\n|\n---$/g, ''),
+      body: content.slice(standardMatch[0].length).trim(),
+    };
+  }
+
+  const chatAgentMatch = content.match(/^```chatagent\s*\n---\s*\n([\s\S]*?)\n---\s*\n```(?:\s*\n)?/);
+  if (chatAgentMatch) {
+    return {
+      frontmatter: chatAgentMatch[1],
+      body: content.slice(chatAgentMatch[0].length).trim(),
+    };
+  }
+
+  return {
+    frontmatter: '',
+    body: content.trim(),
+  };
+}
+
 /**
  * Fetch the list of subagent files from the repository
  * Subagents are .agent.md files at the repo root
@@ -54,6 +77,20 @@ export async function fetchAvailableSubagents() {
  * @returns {Promise<{name: string, description: string}>}
  */
 export async function fetchSubagentMetadata(filename) {
+  try {
+    const content = await fetchSubagentContent(filename);
+    return parseSubagentFrontmatter(content);
+  } catch (error) {
+    throw error;
+  }
+}
+
+/**
+ * Fetch the raw source for a subagent file
+ * @param {string} filename - The agent filename
+ * @returns {Promise<string>}
+ */
+export async function fetchSubagentContent(filename) {
   const fileUrl = `${GITHUB_API}/repos/${SUBAGENTS_REPO_OWNER}/${SUBAGENTS_REPO_NAME}/contents/${filename}`;
   
   try {
@@ -66,9 +103,7 @@ export async function fetchSubagentMetadata(filename) {
     }
 
     const data = await response.json();
-    const content = Buffer.from(data.content, 'base64').toString('utf-8');
-    
-    return parseSubagentFrontmatter(content);
+    return Buffer.from(data.content, 'base64').toString('utf-8');
   } catch (error) {
     throw error;
   }
@@ -81,13 +116,7 @@ export async function fetchSubagentMetadata(filename) {
  * @returns {{name: string, description: string}}
  */
 function parseSubagentFrontmatter(content) {
-  // Try to match standard --- frontmatter
-  const standardMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
-  
-  // Try to match ```chatagent fenced frontmatter
-  const chatAgentMatch = content.match(/```chatagent\s*\n---\s*\n([\s\S]*?)\n---/);
-  
-  const frontmatterContent = standardMatch?.[1] || chatAgentMatch?.[1];
+  const { frontmatter: frontmatterContent } = extractSubagentSections(content);
   
   if (!frontmatterContent) {
     return { name: '', description: '' };
@@ -102,6 +131,24 @@ function parseSubagentFrontmatter(content) {
   };
 }
 
+/**
+ * Parse a subagent file into metadata and body content.
+ * @param {string} content - The .agent.md file content
+ * @param {string} filename - The source filename for fallback naming
+ * @returns {{name: string, description: string, body: string, filename: string}}
+ */
+export function parseSubagentDefinition(content, filename = '') {
+  const metadata = parseSubagentFrontmatter(content);
+  const { body } = extractSubagentSections(content);
+
+  return {
+    filename,
+    name: metadata.name || humanizeAgentName(filename),
+    description: metadata.description || '',
+    body,
+  };
+}
+
 /**
  * Get the subagents repository clone URL
  * @returns {string}
@@ -110,4 +157,4 @@ export function getSubagentsRepoUrl() {
   return `https://github.com/${SUBAGENTS_REPO_OWNER}/${SUBAGENTS_REPO_NAME}.git`;
 }
 
-export { SUBAGENTS_REPO_OWNER, SUBAGENTS_REPO_NAME };
+export { SUBAGENTS_REPO_OWNER, SUBAGENTS_REPO_NAME, humanizeAgentName };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supercorks/skills-installer",
-  "version": "1.11.1",
+  "version": "1.13.0",
   "description": "Interactive CLI installer for AI agent skills and subagents",
   "type": "module",
   "bin": {