@supercorks/skills-installer 1.11.1 → 1.12.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,13 +18,23 @@ 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. The installer labels each option with harness, scope, and available count, for example `.github/skills/ (copilot | local | 24 skills)`.
+
+   Skills:
+   - `.github/skills/` (copilot | local)
+   - `~/.copilot/skills/` (copilot | global)
+   - `.agents/skills/` (codex | local)
+   - `~/.agents/skills/` (codex | global)
+   - `.claude/skills/` (claude | local)
+   - `~/.claude/skills/` (claude | global)
+
+   Agents:
+   - `.github/agents/` (copilot | local)
+   - `~/.copilot/agents/` (copilot | global)
+   - `.claude/agents/` (claude | local)
+   - `~/.claude/agents/` (claude | global)
+   - `.codex/agents/` (codex | local, installed as converted TOML agents)
+   - `~/.codex/agents/` (codex | global, 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`
@@ -36,7 +46,9 @@ npx @supercorks/skills-installer install
    - 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 +60,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
+- **Codex agent conversion** - Converts Markdown subagents into Codex TOML custom agents for `.codex/agents/` targets
 - **Recursive directory creation** - Custom paths are created automatically
 
 ## Requirements

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();
@@ -92,6 +94,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,7 +240,7 @@ 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];
@@ -380,7 +400,7 @@ 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];
@@ -400,15 +420,16 @@ async function runSubagentsInstall() {
 async function runSubagentsInstallForTarget(subagents, 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 +439,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 {
@@ -475,9 +507,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 +528,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,73 @@
+/**
+ * Supported install targets for skills and agents.
+ */
+
+export const SKILL_INSTALL_TARGETS = [
+  { path: '.github/skills/', harness: 'copilot', scope: 'local' },
+  { path: '~/.copilot/skills/', harness: 'copilot', scope: 'global' },
+  { path: '.agents/skills/', harness: 'codex', scope: 'local' },
+  { path: '~/.agents/skills/', harness: 'codex', scope: 'global' },
+  { path: '.claude/skills/', harness: 'claude', scope: 'local' },
+  { path: '~/.claude/skills/', harness: 'claude', scope: 'global' }
+];
+
+export const LEGACY_SKILL_INSTALL_TARGETS = [
+  {
+    path: '~/.codex/skills/',
+    harness: 'codex',
+    scope: 'legacy global'
+  }
+];
+
+export const AGENT_INSTALL_TARGETS = [
+  { path: '.github/agents/', harness: 'copilot', scope: 'local', installMode: 'sparse-git' },
+  { path: '~/.copilot/agents/', harness: 'copilot', scope: 'global', installMode: 'sparse-git' },
+  { path: '.claude/agents/', harness: 'claude', scope: 'local', installMode: 'sparse-git' },
+  { path: '~/.claude/agents/', harness: 'claude', scope: 'global', installMode: 'sparse-git' },
+  { path: '.codex/agents/', harness: 'codex', scope: 'local', installMode: 'codex-toml' },
+  { path: '~/.codex/agents/', harness: 'codex', scope: 'global', installMode: 'codex-toml' }
+];
+
+export const LEGACY_AGENT_INSTALL_TARGETS = [
+  {
+    path: '.agents/agents/',
+    harness: 'codex',
+    scope: 'legacy local'
+  }
+];
+
+export function allSkillDetectionTargets() {
+  return [...SKILL_INSTALL_TARGETS, ...LEGACY_SKILL_INSTALL_TARGETS];
+}
+
+export function allAgentDetectionTargets() {
+  return [...AGENT_INSTALL_TARGETS, ...LEGACY_AGENT_INSTALL_TARGETS];
+}
+
+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,20 @@
 
 import inquirer from 'inquirer';
 import * as readline from 'readline';
+import {
+  AGENT_INSTALL_TARGETS,
+  SKILL_INSTALL_TARGETS,
+  allAgentDetectionTargets,
+  allSkillDetectionTargets,
+  formatTargetLabel,
+  getTargetByPath
+} 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,17 +63,22 @@ 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();
   
   // Add existing installations at the top
   if (existingInstalls.length > 0) {
     existingInstalls.forEach(install => {
+      const target = getTargetByPath(detectionTargets, install.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
       });
     });
@@ -79,15 +86,12 @@ export async function promptInstallPath(existingInstalls = []) {
   }
   
   // 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 });
+  SKILL_INSTALL_TARGETS.forEach(target => {
+    if (!existingPaths.includes(target.path)) {
+      choices.push({
+        name: formatTargetLabel(target, availableSkillCount, 'skill'),
+        value: target.path
+      });
     }
   });
   
@@ -144,17 +148,22 @@ 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();
   
   // Add existing installations at the top
   if (existingInstalls.length > 0) {
     existingInstalls.forEach(install => {
+      const target = getTargetByPath(detectionTargets, install.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
       });
     });
@@ -162,15 +171,13 @@ export async function promptAgentInstallPath(existingInstalls = []) {
   }
   
   // 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 });
+  AGENT_INSTALL_TARGETS.forEach(target => {
+    if (!existingPaths.includes(target.path)) {
+      choices.push({
+        name: formatTargetLabel(target, availableAgentCount, 'agent'),
+        value: target.path,
+        disabled: target.disabledReason
+      });
     }
   });
   

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.12.0",
   "description": "Interactive CLI installer for AI agent skills and subagents",
   "type": "module",
   "bin": {