@supercorks/skills-installer 1.0.0 → 1.2.0

package/README.md

@@ -5,13 +5,13 @@ Interactive CLI installer for AI agent skills. Selectively install skills for Gi
 ## Usage
 
 ```bash
-npx @supercorks/skills-installer install
+npx @supercorks/skills-installer
 ```
 
-Or with the longer form:
+Or explicitly with the `install` command:
 
 ```bash
-npx --package=@supercorks/skills-installer skills-installer install
+npx @supercorks/skills-installer install
 ```
 
 ## What it does
@@ -74,7 +74,7 @@ npm install
 # Run locally
 npm start
 # or
-node bin/install.js install
+node bin/install.js
 ```
 
 ## License

package/bin/install.js

@@ -2,7 +2,7 @@
 
 /**
  * @supercorks/skills-installer
- * Interactive CLI installer for AI agent skills
+ * Interactive CLI installer for AI agent skills and subagents
  * 
  * Usage: npx @supercorks/skills-installer install
  */
@@ -10,17 +10,90 @@
 import { existsSync, appendFileSync, readFileSync, writeFileSync } from 'fs';
 import { resolve, join } from 'path';
 import { 
-  promptInstallPath, 
+  promptInstallType,
+  promptInstallPath,
+  promptAgentInstallPath, 
   promptGitignore, 
   promptSkillSelection,
+  promptSubagentSelection,
   showSpinner,
   showSuccess,
+  showSubagentSuccess,
   showError
 } from '../lib/prompts.js';
 import { fetchAvailableSkills } from '../lib/skills.js';
-import { sparseCloneSkills, isGitAvailable } from '../lib/git.js';
+import { fetchAvailableSubagents } from '../lib/subagents.js';
+import { 
+  sparseCloneSkills, 
+  isGitAvailable, 
+  listCheckedOutSkills, 
+  updateSparseCheckout,
+  sparseCloneSubagents,
+  listCheckedOutSubagents,
+  updateSubagentsSparseCheckout
+} from '../lib/git.js';
+
+const VERSION = '1.2.0';
 
-const VERSION = '1.0.0';
+// Common installation paths to check for existing installations
+const SKILL_PATHS = ['.github/skills/', '.claude/skills/'];
+const AGENT_PATHS = ['.github/agents/', '.claude/agents/'];
+
+/**
+ * Detect existing skill installations in common paths
+ * @returns {Promise<Array<{path: string, skillCount: number, skills: string[]}>>}
+ */
+async function detectExistingSkillInstallations() {
+  const installations = [];
+  
+  for (const path of SKILL_PATHS) {
+    const absolutePath = resolve(process.cwd(), path);
+    const gitDir = join(absolutePath, '.git');
+    
+    if (existsSync(gitDir)) {
+      try {
+        const skills = await listCheckedOutSkills(absolutePath);
+        installations.push({
+          path,
+          skillCount: skills.length,
+          skills
+        });
+      } catch {
+        // Ignore errors reading existing installations
+      }
+    }
+  }
+  
+  return installations;
+}
+
+/**
+ * Detect existing subagent installations in common paths
+ * @returns {Promise<Array<{path: string, agentCount: number, agents: string[]}>>}
+ */
+async function detectExistingAgentInstallations() {
+  const installations = [];
+  
+  for (const path of AGENT_PATHS) {
+    const absolutePath = resolve(process.cwd(), path);
+    const gitDir = join(absolutePath, '.git');
+    
+    if (existsSync(gitDir)) {
+      try {
+        const agents = await listCheckedOutSubagents(absolutePath);
+        installations.push({
+          path,
+          agentCount: agents.length,
+          agents
+        });
+      } catch {
+        // Ignore errors reading existing installations
+      }
+    }
+  }
+  
+  return installations;
+}
 
 /**
  * Print usage information
@@ -30,7 +103,7 @@ function printUsage() {
 @supercorks/skills-installer v${VERSION}
 
 Usage:
-  npx @supercorks/skills-installer            Install skills interactively (default)
+  npx @supercorks/skills-installer            Install skills/subagents interactively (default)
   npx @supercorks/skills-installer --help     Show this help message
   npx @supercorks/skills-installer --version  Show version
 
@@ -67,7 +140,7 @@ function addToGitignore(gitignorePath, pathToIgnore) {
  * Main installation flow
  */
 async function runInstall() {
-  console.log('\n🔧 AI Agent Skills Installer\n');
+  console.log('\n🔧 AI Agent Skills & Subagents Installer\n');
 
   // Check git availability
   if (!isGitAvailable()) {
@@ -75,7 +148,27 @@ async function runInstall() {
     process.exit(1);
   }
 
-  // Step 1: Fetch available skills
+  // Step 1: Ask what to install
+  const { skills: installSkills, subagents: installSubagents } = await promptInstallType();
+
+  // Install skills if selected
+  if (installSkills) {
+    await runSkillsInstall();
+  }
+
+  // Install subagents if selected
+  if (installSubagents) {
+    await runSubagentsInstall();
+  }
+}
+
+/**
+ * Skills installation flow
+ */
+async function runSkillsInstall() {
+  console.log('\n📦 Skills Installation\n');
+
+  // Fetch available skills
   let skills;
   const fetchSpinner = showSpinner('Fetching available skills from repository...');
   try {
@@ -92,48 +185,279 @@ async function runInstall() {
     process.exit(1);
   }
 
-  // Step 2: Ask where to install
-  const installPath = await promptInstallPath();
+  // Detect existing installations
+  const existingInstalls = await detectExistingSkillInstallations();
+
+  // Ask where to install (showing existing installations if any)
+  const { path: installPath, isExisting } = await promptInstallPath(existingInstalls);
   const absoluteInstallPath = resolve(process.cwd(), installPath);
 
-  // Check if path already exists with a git repo
-  if (existsSync(join(absoluteInstallPath, '.git'))) {
-    showError(`"${installPath}" already contains a git repository. Please remove it first or choose a different path.`);
-    process.exit(1);
+  // Get currently installed skills if managing existing installation
+  let installedSkills = [];
+  if (isExisting) {
+    const existingInstall = existingInstalls.find(i => i.path === installPath);
+    installedSkills = existingInstall?.skills || [];
+  } else {
+    // Check if manually entered path has an existing installation
+    const gitDir = join(absoluteInstallPath, '.git');
+    if (existsSync(gitDir)) {
+      try {
+        installedSkills = await listCheckedOutSkills(absoluteInstallPath);
+      } catch {
+        // If we can't read it, treat as fresh install
+      }
+    }
   }
 
-  // Step 3: Ask about .gitignore
-  const shouldGitignore = await promptGitignore(installPath);
+  const isManageMode = installedSkills.length > 0;
 
-  // Step 4: Select skills
-  const selectedSkills = await promptSkillSelection(skills);
+  // Ask about .gitignore (only for fresh installs)
+  let shouldGitignore = false;
+  if (!isManageMode) {
+    shouldGitignore = await promptGitignore(installPath);
+  }
+
+  // Select skills (pre-select installed skills in manage mode)
+  const selectedSkills = await promptSkillSelection(skills, installedSkills);
 
-  // Step 5: Perform installation
+  // Perform installation or update
   console.log('');
-  const installSpinner = showSpinner('Installing selected skills...');
   
+  if (isManageMode) {
+    // Calculate changes
+    const toAdd = selectedSkills.filter(s => !installedSkills.includes(s));
+    const toRemove = installedSkills.filter(s => !selectedSkills.includes(s));
+    const unchanged = selectedSkills.filter(s => installedSkills.includes(s));
+
+    if (toAdd.length === 0 && toRemove.length === 0) {
+      console.log('ℹ️  No changes to apply. Pulling latest updates...');
+    }
+
+    const updateSpinner = showSpinner('Updating skills installation...');
+    
+    try {
+      await updateSparseCheckout(absoluteInstallPath, selectedSkills, (message) => {
+        updateSpinner.stop(`   ${message}`);
+      });
+    } catch (error) {
+      updateSpinner.stop('❌ Update failed');
+      showError(error.message);
+      process.exit(1);
+    }
+
+    // Show summary of changes
+    showSkillManageSuccess(installPath, skills, toAdd, toRemove, unchanged);
+  } else {
+    const installSpinner = showSpinner('Installing selected skills...');
+    
+    try {
+      await sparseCloneSkills(installPath, selectedSkills, (message) => {
+        installSpinner.stop(`   ${message}`);
+      });
+    } catch (error) {
+      installSpinner.stop('❌ Installation failed');
+      showError(error.message);
+      process.exit(1);
+    }
+
+    // Update .gitignore if requested
+    if (shouldGitignore) {
+      const gitignorePath = resolve(process.cwd(), '.gitignore');
+      addToGitignore(gitignorePath, installPath);
+    }
+
+    // Show success
+    const installedSkillNames = skills
+      .filter(s => selectedSkills.includes(s.folder))
+      .map(s => s.name);
+    
+    showSuccess(installPath, installedSkillNames);
+  }
+}
+
+/**
+ * Subagents installation flow
+ */
+async function runSubagentsInstall() {
+  console.log('\n🤖 Subagents Installation\n');
+
+  // Fetch available subagents
+  let subagents;
+  const fetchSpinner = showSpinner('Fetching available subagents from repository...');
   try {
-    await sparseCloneSkills(installPath, selectedSkills, (message) => {
-      installSpinner.stop(`   ${message}`);
-    });
+    subagents = await fetchAvailableSubagents();
+    fetchSpinner.stop(`✅ Found ${subagents.length} available subagents`);
   } catch (error) {
-    installSpinner.stop('❌ Installation failed');
-    showError(error.message);
+    fetchSpinner.stop('❌ Failed to fetch subagents');
+    showError(`Could not fetch subagents list: ${error.message}`);
+    process.exit(1);
+  }
+
+  if (subagents.length === 0) {
+    showError('No subagents found in the repository');
     process.exit(1);
   }
 
-  // Step 6: Update .gitignore if requested
-  if (shouldGitignore) {
-    const gitignorePath = resolve(process.cwd(), '.gitignore');
-    addToGitignore(gitignorePath, installPath);
+  // Detect existing installations
+  const existingInstalls = await detectExistingAgentInstallations();
+
+  // Ask where to install (showing existing installations if any)
+  const { path: installPath, isExisting } = await promptAgentInstallPath(existingInstalls);
+  const absoluteInstallPath = resolve(process.cwd(), installPath);
+
+  // Get currently installed subagents if managing existing installation
+  let installedAgents = [];
+  if (isExisting) {
+    const existingInstall = existingInstalls.find(i => i.path === installPath);
+    installedAgents = existingInstall?.agents || [];
+  } else {
+    // Check if manually entered path has an existing installation
+    const gitDir = join(absoluteInstallPath, '.git');
+    if (existsSync(gitDir)) {
+      try {
+        installedAgents = await listCheckedOutSubagents(absoluteInstallPath);
+      } catch {
+        // If we can't read it, treat as fresh install
+      }
+    }
+  }
+
+  const isManageMode = installedAgents.length > 0;
+
+  // Ask about .gitignore (only for fresh installs)
+  let shouldGitignore = false;
+  if (!isManageMode) {
+    shouldGitignore = await promptGitignore(installPath);
+  }
+
+  // Select subagents (pre-select installed ones in manage mode)
+  const selectedAgents = await promptSubagentSelection(subagents, installedAgents);
+
+  // Perform installation or update
+  console.log('');
+  
+  if (isManageMode) {
+    // Calculate changes
+    const toAdd = selectedAgents.filter(s => !installedAgents.includes(s));
+    const toRemove = installedAgents.filter(s => !selectedAgents.includes(s));
+    const unchanged = selectedAgents.filter(s => installedAgents.includes(s));
+
+    if (toAdd.length === 0 && toRemove.length === 0) {
+      console.log('ℹ️  No changes to apply. Pulling latest updates...');
+    }
+
+    const updateSpinner = showSpinner('Updating subagents installation...');
+    
+    try {
+      await updateSubagentsSparseCheckout(absoluteInstallPath, selectedAgents, (message) => {
+        updateSpinner.stop(`   ${message}`);
+      });
+    } catch (error) {
+      updateSpinner.stop('❌ Update failed');
+      showError(error.message);
+      process.exit(1);
+    }
+
+    // Show summary of changes
+    showAgentManageSuccess(installPath, subagents, toAdd, toRemove, unchanged);
+  } else {
+    const installSpinner = showSpinner('Installing selected subagents...');
+    
+    try {
+      await sparseCloneSubagents(installPath, selectedAgents, (message) => {
+        installSpinner.stop(`   ${message}`);
+      });
+    } catch (error) {
+      installSpinner.stop('❌ Installation failed');
+      showError(error.message);
+      process.exit(1);
+    }
+
+    // Update .gitignore if requested
+    if (shouldGitignore) {
+      const gitignorePath = resolve(process.cwd(), '.gitignore');
+      addToGitignore(gitignorePath, installPath);
+    }
+
+    // Show success
+    const installedAgentNames = subagents
+      .filter(s => selectedAgents.includes(s.filename))
+      .map(s => s.name);
+    
+    showSubagentSuccess(installPath, installedAgentNames);
+  }
+}
+
+/**
+ * Display success message for manage mode with skill change summary
+ * @param {string} installPath - Where skills are installed
+ * @param {Array<{name: string, folder: string}>} allSkills - All available skills
+ * @param {string[]} added - Skill folders that were added
+ * @param {string[]} removed - Skill folders that were removed
+ * @param {string[]} unchanged - Skill folders that were unchanged
+ */
+function showSkillManageSuccess(installPath, allSkills, added, removed, unchanged) {
+  const getSkillName = (folder) => allSkills.find(s => s.folder === folder)?.name || folder;
+  
+  console.log('\n' + '═'.repeat(50));
+  console.log('✅ Skills updated successfully!');
+  console.log('═'.repeat(50));
+  console.log(`\n📁 Location: ${installPath}`);
+  
+  if (added.length > 0) {
+    console.log(`\n➕ Added (${added.length}):`);
+    added.forEach(folder => console.log(`   • ${getSkillName(folder)}`));
   }
+  
+  if (removed.length > 0) {
+    console.log(`\n➖ Removed (${removed.length}):`);
+    removed.forEach(folder => console.log(`   • ${getSkillName(folder)}`));
+  }
+  
+  if (unchanged.length > 0) {
+    console.log(`\n📦 Unchanged (${unchanged.length}):`);
+    unchanged.forEach(folder => console.log(`   • ${getSkillName(folder)}`));
+  }
+  
+  const totalInstalled = added.length + unchanged.length;
+  console.log(`\n🚀 ${totalInstalled} skill${totalInstalled !== 1 ? 's' : ''} now installed.`);
+  console.log('═'.repeat(50) + '\n');
+}
 
-  // Step 7: Show success
-  const installedSkillNames = skills
-    .filter(s => selectedSkills.includes(s.folder))
-    .map(s => s.name);
+/**
+ * Display success message for manage mode with subagent change summary
+ * @param {string} installPath - Where subagents are installed
+ * @param {Array<{name: string, filename: string}>} allAgents - All available subagents
+ * @param {string[]} added - Agent filenames that were added
+ * @param {string[]} removed - Agent filenames that were removed
+ * @param {string[]} unchanged - Agent filenames that were unchanged
+ */
+function showAgentManageSuccess(installPath, allAgents, added, removed, unchanged) {
+  const getAgentName = (filename) => allAgents.find(s => s.filename === filename)?.name || filename;
+  
+  console.log('\n' + '═'.repeat(50));
+  console.log('✅ Subagents updated successfully!');
+  console.log('═'.repeat(50));
+  console.log(`\n📁 Location: ${installPath}`);
+  
+  if (added.length > 0) {
+    console.log(`\n➕ Added (${added.length}):`);
+    added.forEach(filename => console.log(`   • ${getAgentName(filename)}`));
+  }
+  
+  if (removed.length > 0) {
+    console.log(`\n➖ Removed (${removed.length}):`);
+    removed.forEach(filename => console.log(`   • ${getAgentName(filename)}`));
+  }
+  
+  if (unchanged.length > 0) {
+    console.log(`\n🤖 Unchanged (${unchanged.length}):`);
+    unchanged.forEach(filename => console.log(`   • ${getAgentName(filename)}`));
+  }
   
-  showSuccess(installPath, installedSkillNames);
+  const totalInstalled = added.length + unchanged.length;
+  console.log(`\n🚀 ${totalInstalled} subagent${totalInstalled !== 1 ? 's' : ''} now installed.`);
+  console.log('═'.repeat(50) + '\n');
 }
 
 /**

package/lib/git.js

@@ -1,11 +1,12 @@
 /**
- * Git sparse-checkout utilities for cloning selected skills
+ * Git sparse-checkout utilities for cloning selected skills and subagents
  */
 
 import { execSync, spawn } from 'child_process';
 import { existsSync, mkdirSync, rmSync, writeFileSync, readFileSync, appendFileSync } from 'fs';
 import { join, resolve } from 'path';
 import { getRepoUrl } from './skills.js';
+import { getSubagentsRepoUrl } from './subagents.js';
 
 /**
  * Check if git is available
@@ -118,6 +119,42 @@ export async function sparseCloneSkills(targetPath, skillFolders, onProgress = (
   }
 }
 
+/**
+ * Update the sparse-checkout to include exactly the specified skills
+ * This replaces all existing skills with the new selection
+ * @param {string} repoPath - Path to the existing sparse-checkout repo
+ * @param {string[]} skillFolders - Skill folders to include (replaces existing)
+ * @param {(message: string) => void} onProgress - Progress callback
+ * @returns {Promise<void>}
+ */
+export async function updateSparseCheckout(repoPath, skillFolders, onProgress = () => {}) {
+  const absolutePath = resolve(repoPath);
+  
+  if (!existsSync(join(absolutePath, '.git'))) {
+    throw new Error(`"${repoPath}" is not a git repository`);
+  }
+
+  // Pull latest changes first
+  onProgress('Pulling latest changes...');
+  try {
+    await runGitCommand(['pull'], absolutePath);
+  } catch (error) {
+    // Ignore pull errors (e.g., no upstream configured)
+  }
+
+  // Write new patterns to sparse-checkout file (replaces existing)
+  onProgress('Updating sparse-checkout configuration...');
+  const sparseCheckoutPath = join(absolutePath, '.git', 'info', 'sparse-checkout');
+  const patterns = skillFolders.map(folder => `/${folder}/`).join('\n');
+  writeFileSync(sparseCheckoutPath, patterns + '\n');
+  
+  // Re-apply sparse-checkout
+  onProgress('Applying changes...');
+  await runGitCommand(['read-tree', '-mu', 'HEAD'], absolutePath);
+  
+  onProgress('Done!');
+}
+
 /**
  * Add more skills to an existing sparse-checkout
  * @param {string} repoPath - Path to the existing sparse-checkout repo
@@ -176,3 +213,131 @@ export async function pullUpdates(repoPath) {
   const absolutePath = resolve(repoPath);
   return runGitCommand(['pull'], absolutePath);
 }
+
+// ==================== SUBAGENTS FUNCTIONS ====================
+
+/**
+ * Perform a sparse clone of the subagents repository with only selected agent files
+ * 
+ * @param {string} targetPath - Where to clone the repository
+ * @param {string[]} agentFilenames - Array of agent filenames to include (e.g., 'Developer.agent.md')
+ * @param {(message: string) => void} onProgress - Progress callback
+ * @returns {Promise<void>}
+ */
+export async function sparseCloneSubagents(targetPath, agentFilenames, onProgress = () => {}) {
+  const repoUrl = getSubagentsRepoUrl();
+  const absolutePath = resolve(targetPath);
+  
+  // Check if target already exists and has content
+  if (existsSync(absolutePath)) {
+    const gitDir = join(absolutePath, '.git');
+    if (existsSync(gitDir)) {
+      throw new Error(`Directory "${targetPath}" already contains a git repository. Please remove it first or choose a different path.`);
+    }
+  }
+
+  // Create target directory
+  mkdirSync(absolutePath, { recursive: true });
+
+  try {
+    // Clone with blob filter for minimal download, no checkout yet
+    onProgress('Initializing sparse clone...');
+    await runGitCommand([
+      'clone',
+      '--filter=blob:none',
+      '--no-checkout',
+      '--sparse',
+      repoUrl,
+      '.'
+    ], absolutePath);
+
+    // Use non-cone mode for precise control over what's checked out
+    onProgress('Configuring sparse-checkout...');
+    await runGitCommand([
+      'sparse-checkout',
+      'init',
+      '--no-cone'
+    ], absolutePath);
+
+    // Write explicit patterns - only selected agent files
+    const sparseCheckoutPath = join(absolutePath, '.git', 'info', 'sparse-checkout');
+    const patterns = agentFilenames.map(filename => `/${filename}`).join('\n');
+    writeFileSync(sparseCheckoutPath, patterns + '\n');
+
+    // Checkout the files
+    onProgress('Checking out files...');
+    await runGitCommand(['checkout'], absolutePath);
+
+    onProgress('Done!');
+  } catch (error) {
+    // Clean up on failure
+    try {
+      rmSync(absolutePath, { recursive: true, force: true });
+    } catch {
+      // Ignore cleanup errors
+    }
+    throw error;
+  }
+}
+
+/**
+ * Update the sparse-checkout for subagents to include exactly the specified agents
+ * @param {string} repoPath - Path to the existing sparse-checkout repo
+ * @param {string[]} agentFilenames - Agent filenames to include (replaces existing)
+ * @param {(message: string) => void} onProgress - Progress callback
+ * @returns {Promise<void>}
+ */
+export async function updateSubagentsSparseCheckout(repoPath, agentFilenames, onProgress = () => {}) {
+  const absolutePath = resolve(repoPath);
+  
+  if (!existsSync(join(absolutePath, '.git'))) {
+    throw new Error(`"${repoPath}" is not a git repository`);
+  }
+
+  // Pull latest changes first
+  onProgress('Pulling latest changes...');
+  try {
+    await runGitCommand(['pull'], absolutePath);
+  } catch (error) {
+    // Ignore pull errors (e.g., no upstream configured)
+  }
+
+  // Write new patterns to sparse-checkout file (replaces existing)
+  onProgress('Updating sparse-checkout configuration...');
+  const sparseCheckoutPath = join(absolutePath, '.git', 'info', 'sparse-checkout');
+  const patterns = agentFilenames.map(filename => `/${filename}`).join('\n');
+  writeFileSync(sparseCheckoutPath, patterns + '\n');
+  
+  // Re-apply sparse-checkout
+  onProgress('Applying changes...');
+  await runGitCommand(['read-tree', '-mu', 'HEAD'], absolutePath);
+  
+  onProgress('Done!');
+}
+
+/**
+ * List currently checked out subagents in a sparse-checkout repo
+ * @param {string} repoPath - Path to the sparse-checkout repo
+ * @returns {Promise<string[]>} List of agent filenames
+ */
+export async function listCheckedOutSubagents(repoPath) {
+  const absolutePath = resolve(repoPath);
+  
+  if (!existsSync(join(absolutePath, '.git'))) {
+    throw new Error(`"${repoPath}" is not a git repository`);
+  }
+
+  // Read patterns from sparse-checkout file (non-cone mode format: /filename)
+  const sparseCheckoutPath = join(absolutePath, '.git', 'info', 'sparse-checkout');
+  if (!existsSync(sparseCheckoutPath)) {
+    return [];
+  }
+  
+  const content = readFileSync(sparseCheckoutPath, 'utf-8');
+  const patterns = content.split('\n').filter(Boolean);
+  
+  // Extract filenames from patterns like /Developer.agent.md
+  return patterns
+    .map(p => p.replace(/^\//, ''))  // Remove leading slash
+    .filter(p => p && p.endsWith('.agent.md'));
+}

package/lib/prompts.js

@@ -5,12 +5,18 @@
 import inquirer from 'inquirer';
 import * as readline from 'readline';
 
-const PATH_CHOICES = {
+const SKILL_PATH_CHOICES = {
   GITHUB: '.github/skills/',
   CLAUDE: '.claude/skills/',
   CUSTOM: '__custom__'
 };
 
+const AGENT_PATH_CHOICES = {
+  GITHUB: '.github/agents/',
+  CLAUDE: '.claude/agents/',
+  CUSTOM: '__custom__'
+};
+
 /**
  * Extract the first sentence from a description
  * @param {string} text - Full description text
@@ -27,25 +33,72 @@ function getFirstSentence(text, maxLength = 60) {
 }
 
 /**
- * Prompt user to select installation path
- * @returns {Promise<string>} The selected or custom path
+ * Prompt user to select what to install
+ * @returns {Promise<{skills: boolean, subagents: boolean}>}
+ */
+export async function promptInstallType() {
+  const { installType } = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'installType',
+      message: 'What would you like to install?',
+      choices: [
+        { name: 'Skills only', value: 'skills' },
+        { name: 'Subagents only', value: 'subagents' },
+        { name: 'Both skills and subagents', value: 'both' }
+      ]
+    }
+  ]);
+
+  return {
+    skills: installType === 'skills' || installType === 'both',
+    subagents: installType === 'subagents' || installType === 'both'
+  };
+}
+
+/**
+ * Prompt user to select installation path, showing existing installations
+ * @param {Array<{path: string, skillCount: number}>} existingInstalls - Detected existing installations
+ * @returns {Promise<{path: string, isExisting: boolean}>} The selected path and whether it's existing
  */
-export async function promptInstallPath() {
+export async function promptInstallPath(existingInstalls = []) {
+  const choices = [];
+  
+  // Add existing installations at the top
+  if (existingInstalls.length > 0) {
+    existingInstalls.forEach(install => {
+      choices.push({
+        name: `${install.path} (${install.skillCount} skill${install.skillCount !== 1 ? 's' : ''} installed)`,
+        value: { path: install.path, isExisting: true }
+      });
+    });
+    choices.push(new inquirer.Separator('── New installation ──'));
+  }
+  
+  // Standard path options
+  const standardPaths = [SKILL_PATH_CHOICES.GITHUB, SKILL_PATH_CHOICES.CLAUDE];
+  const existingPaths = existingInstalls.map(i => i.path);
+  
+  standardPaths.forEach(path => {
+    if (!existingPaths.includes(path)) {
+      choices.push({ name: path, value: { path, isExisting: false } });
+    }
+  });
+  
+  choices.push({ name: 'Custom path...', value: { path: SKILL_PATH_CHOICES.CUSTOM, isExisting: false } });
+
   const { pathChoice } = await inquirer.prompt([
     {
       type: 'list',
       name: 'pathChoice',
-      message: 'Where would you like to install the skills?',
-      choices: [
-        { name: '.github/skills/', value: PATH_CHOICES.GITHUB },
-        { name: '.claude/skills/', value: PATH_CHOICES.CLAUDE },
-        { name: 'Custom path...', value: PATH_CHOICES.CUSTOM }
-      ],
-      default: PATH_CHOICES.GITHUB
+      message: existingInstalls.length > 0 
+        ? 'Select an existing installation to manage, or choose a new location:'
+        : 'Where would you like to install the skills?',
+      choices
     }
   ]);
 
-  if (pathChoice === PATH_CHOICES.CUSTOM) {
+  if (pathChoice.path === SKILL_PATH_CHOICES.CUSTOM) {
     const { customPath } = await inquirer.prompt([
       {
         type: 'input',
@@ -59,7 +112,69 @@ export async function promptInstallPath() {
         }
       }
     ]);
-    return customPath.trim();
+    return { path: customPath.trim(), isExisting: false };
+  }
+
+  return pathChoice;
+}
+
+/**
+ * Prompt user to select subagent installation path
+ * @param {Array<{path: string, agentCount: number}>} existingInstalls - Detected existing installations
+ * @returns {Promise<{path: string, isExisting: boolean}>} The selected path and whether it's existing
+ */
+export async function promptAgentInstallPath(existingInstalls = []) {
+  const choices = [];
+  
+  // Add existing installations at the top
+  if (existingInstalls.length > 0) {
+    existingInstalls.forEach(install => {
+      choices.push({
+        name: `${install.path} (${install.agentCount} agent${install.agentCount !== 1 ? 's' : ''} installed)`,
+        value: { path: install.path, isExisting: true }
+      });
+    });
+    choices.push(new inquirer.Separator('── New installation ──'));
+  }
+  
+  // Standard path options
+  const standardPaths = [AGENT_PATH_CHOICES.GITHUB, AGENT_PATH_CHOICES.CLAUDE];
+  const existingPaths = existingInstalls.map(i => i.path);
+  
+  standardPaths.forEach(path => {
+    if (!existingPaths.includes(path)) {
+      choices.push({ name: path, value: { path, isExisting: false } });
+    }
+  });
+  
+  choices.push({ name: 'Custom path...', value: { path: AGENT_PATH_CHOICES.CUSTOM, isExisting: false } });
+
+  const { pathChoice } = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'pathChoice',
+      message: existingInstalls.length > 0 
+        ? 'Select an existing installation to manage, or choose a new location:'
+        : 'Where would you like to install the subagents?',
+      choices
+    }
+  ]);
+
+  if (pathChoice.path === AGENT_PATH_CHOICES.CUSTOM) {
+    const { customPath } = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'customPath',
+        message: 'Enter custom installation path:',
+        validate: (input) => {
+          if (!input.trim()) {
+            return 'Please enter a valid path';
+          }
+          return true;
+        }
+      }
+    ]);
+    return { path: customPath.trim(), isExisting: false };
   }
 
   return pathChoice;
@@ -86,9 +201,39 @@ export async function promptGitignore(installPath) {
 /**
  * Prompt user to select skills to install with expand/collapse support
  * @param {Array<{name: string, description: string, folder: string}>} skills - Available skills
+ * @param {string[]} installedSkills - Already installed skill folder names (will be pre-selected)
  * @returns {Promise<string[]>} Selected skill folder names
  */
-export async function promptSkillSelection(skills) {
+export async function promptSkillSelection(skills, installedSkills = []) {
+  return promptItemSelection(
+    skills.map(s => ({ id: s.folder, name: s.name, description: s.description })),
+    installedSkills,
+    '📦 Available Skills'
+  );
+}
+
+/**
+ * Prompt user to select subagents to install with expand/collapse support
+ * @param {Array<{name: string, description: string, filename: string}>} subagents - Available subagents
+ * @param {string[]} installedSubagents - Already installed subagent filenames (will be pre-selected)
+ * @returns {Promise<string[]>} Selected subagent filenames
+ */
+export async function promptSubagentSelection(subagents, installedSubagents = []) {
+  return promptItemSelection(
+    subagents.map(s => ({ id: s.filename, name: s.name, description: s.description })),
+    installedSubagents,
+    '🤖 Available Subagents'
+  );
+}
+
+/**
+ * Generic item selection prompt with expand/collapse support
+ * @param {Array<{id: string, name: string, description: string}>} items - Available items
+ * @param {string[]} installedItems - Already installed item IDs (will be pre-selected)
+ * @param {string} title - Title to display
+ * @returns {Promise<string[]>} Selected item IDs
+ */
+function promptItemSelection(items, installedItems = [], title = '📦 Available Items') {
   return new Promise((resolve, reject) => {
     const rl = readline.createInterface({
       input: process.stdin,
@@ -102,22 +247,22 @@ export async function promptSkillSelection(skills) {
     readline.emitKeypressEvents(process.stdin, rl);
 
     let cursor = 0;
-    const selected = new Set();
+    const selected = new Set(installedItems);
     const expanded = new Set();
 
     const render = () => {
       // Clear screen and move to top
       process.stdout.write('\x1B[2J\x1B[H');
       
-      console.log('\n📦 Available Skills');
+      console.log(`\n${title}`);
       console.log('─'.repeat(60));
       console.log('↑↓ navigate  SPACE toggle  → expand  ← collapse  A all  ENTER confirm\n');
-      console.log('Select skills to install:\n');
+      console.log('Select items to install:\n');
 
-      skills.forEach((skill, i) => {
-        const isSelected = selected.has(skill.folder);
+      items.forEach((item, i) => {
+        const isSelected = selected.has(item.id);
         const isCursor = i === cursor;
-        const isExpanded = expanded.has(skill.folder);
+        const isExpanded = expanded.has(item.id);
         
         const checkbox = isSelected ? '◉' : '○';
         const pointer = isCursor ? '❯' : ' ';
@@ -127,23 +272,23 @@ export async function promptSkillSelection(skills) {
         const highlight = isCursor ? '\x1B[36m' : '';  // Cyan for selected
         const reset = '\x1B[0m';
         
-        const shortDesc = getFirstSentence(skill.description);
+        const shortDesc = getFirstSentence(item.description);
         
         if (isExpanded) {
-          console.log(`${highlight}${pointer} ${checkbox} ${skill.name}${reset}`);
+          console.log(`${highlight}${pointer} ${checkbox} ${item.name}${reset}`);
           // Show full description indented
-          const fullDesc = skill.description || 'No description available';
+          const fullDesc = item.description || 'No description available';
           const lines = fullDesc.match(/.{1,55}/g) || [fullDesc];
           lines.forEach(line => {
             console.log(`     ${highlight}${line}${reset}`);
           });
         } else {
-          console.log(`${highlight}${pointer} ${checkbox} ${skill.name} ${expandIcon} ${shortDesc}${reset}`);
+          console.log(`${highlight}${pointer} ${checkbox} ${item.name} ${expandIcon} ${shortDesc}${reset}`);
         }
       });
 
       const selectedCount = selected.size;
-      console.log(`\n${selectedCount} skill${selectedCount !== 1 ? 's' : ''} selected`);
+      console.log(`\n${selectedCount} item${selectedCount !== 1 ? 's' : ''} selected`);
     };
 
     const cleanup = () => {
@@ -165,51 +310,51 @@ export async function promptSkillSelection(skills) {
 
       switch (key.name) {
         case 'up':
-          cursor = cursor > 0 ? cursor - 1 : skills.length - 1;
+          cursor = cursor > 0 ? cursor - 1 : items.length - 1;
           render();
           break;
         case 'down':
-          cursor = cursor < skills.length - 1 ? cursor + 1 : 0;
+          cursor = cursor < items.length - 1 ? cursor + 1 : 0;
           render();
           break;
         case 'right':
-          expanded.add(skills[cursor].folder);
+          expanded.add(items[cursor].id);
           render();
           break;
         case 'left':
-          expanded.delete(skills[cursor].folder);
+          expanded.delete(items[cursor].id);
           render();
           break;
         case 'space':
-          const folder = skills[cursor].folder;
-          if (selected.has(folder)) {
-            selected.delete(folder);
+          const itemId = items[cursor].id;
+          if (selected.has(itemId)) {
+            selected.delete(itemId);
           } else {
-            selected.add(folder);
+            selected.add(itemId);
           }
           render();
           break;
         case 'a':
           // Toggle all
-          if (selected.size === skills.length) {
+          if (selected.size === items.length) {
             selected.clear();
           } else {
-            skills.forEach(s => selected.add(s.folder));
+            items.forEach(item => selected.add(item.id));
           }
           render();
           break;
         case 'return':
           if (selected.size === 0) {
             // Show error inline
-            process.stdout.write('\x1B[31mPlease select at least one skill\x1B[0m');
+            process.stdout.write('\x1B[31mPlease select at least one item\x1B[0m');
             setTimeout(render, 1000);
           } else {
             cleanup();
             // Clear and show final selection
             process.stdout.write('\x1B[2J\x1B[H');
-            console.log('\n📦 Selected skills:');
-            skills.filter(s => selected.has(s.folder)).forEach(s => {
-              console.log(`   ✓ ${s.name}`);
+            console.log(`\n${title.split(' ')[0]} Selected:`);
+            items.filter(item => selected.has(item.id)).forEach(item => {
+              console.log(`   ✓ ${item.name}`);
             });
             console.log('');
             resolve(Array.from(selected));
@@ -267,6 +412,22 @@ export function showSuccess(installPath, installedSkills) {
   console.log('═'.repeat(50) + '\n');
 }
 
+/**
+ * Display success message for subagent installation
+ * @param {string} installPath - Where subagents were installed
+ * @param {string[]} installedAgents - List of installed subagent names
+ */
+export function showSubagentSuccess(installPath, installedAgents) {
+  console.log('\n' + '═'.repeat(50));
+  console.log('✅ Subagents installed successfully!');
+  console.log('═'.repeat(50));
+  console.log(`\n📁 Location: ${installPath}`);
+  console.log(`\n🤖 Installed subagents (${installedAgents.length}):`);
+  installedAgents.forEach(agent => console.log(`   • ${agent}`));
+  console.log('\n🚀 Your AI agent will automatically discover these subagents.');
+  console.log('═'.repeat(50) + '\n');
+}
+
 /**
  * Display error message
  * @param {string} message - Error message

package/lib/subagents.js

@@ -0,0 +1,115 @@
+/**
+ * Fetch and parse available subagents from the GitHub repository
+ */
+
+const SUBAGENTS_REPO_OWNER = 'supercorks';
+const SUBAGENTS_REPO_NAME = 'subagents';
+const GITHUB_API = 'https://api.github.com';
+
+/**
+ * Fetch the list of subagent files from the repository
+ * Subagents are .agent.md files at the repo root
+ * @returns {Promise<Array<{name: string, description: string, filename: string}>>}
+ */
+export async function fetchAvailableSubagents() {
+  const repoUrl = `${GITHUB_API}/repos/${SUBAGENTS_REPO_OWNER}/${SUBAGENTS_REPO_NAME}/contents`;
+  
+  const response = await fetch(repoUrl, {
+    headers: {
+      'Accept': 'application/vnd.github.v3+json',
+      'User-Agent': '@supercorks/skills-installer'
+    }
+  });
+
+  if (!response.ok) {
+    throw new Error(`Failed to fetch subagents list: ${response.status} ${response.statusText}`);
+  }
+
+  const contents = await response.json();
+  
+  // Filter to .agent.md files only
+  const agentFiles = contents.filter(
+    item => item.type === 'file' && item.name.endsWith('.agent.md')
+  );
+
+  // Fetch metadata for each agent file
+  const agentChecks = await Promise.all(
+    agentFiles.map(async (file) => {
+      const metadata = await fetchSubagentMetadata(file.name);
+      return {
+        filename: file.name,
+        name: metadata.name || file.name.replace('.agent.md', ''),
+        description: metadata.description || 'No description available'
+      };
+    })
+  );
+
+  return agentChecks;
+}
+
+/**
+ * Fetch and parse frontmatter from a subagent file
+ * @param {string} filename - The agent filename
+ * @returns {Promise<{name: string, description: string}>}
+ */
+async function fetchSubagentMetadata(filename) {
+  const fileUrl = `${GITHUB_API}/repos/${SUBAGENTS_REPO_OWNER}/${SUBAGENTS_REPO_NAME}/contents/${filename}`;
+  
+  try {
+    const response = await fetch(fileUrl, {
+      headers: {
+        'Accept': 'application/vnd.github.v3+json',
+        'User-Agent': '@supercorks/skills-installer'
+      }
+    });
+
+    if (!response.ok) {
+      return { name: '', description: '' };
+    }
+
+    const data = await response.json();
+    const content = Buffer.from(data.content, 'base64').toString('utf-8');
+    
+    return parseSubagentFrontmatter(content);
+  } catch (error) {
+    return { name: '', description: '' };
+  }
+}
+
+/**
+ * Parse the subagent frontmatter to extract name and description
+ * Supports both standard YAML frontmatter and chatagent format
+ * @param {string} content - The .agent.md file content
+ * @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];
+  
+  if (!frontmatterContent) {
+    return { name: '', description: '' };
+  }
+
+  const nameMatch = frontmatterContent.match(/name:\s*['"]?([^'"\n]+)['"]?/);
+  const descMatch = frontmatterContent.match(/description:\s*['"]?([^'"\n]+)['"]?/);
+
+  return {
+    name: nameMatch?.[1]?.trim() || '',
+    description: descMatch?.[1]?.trim() || ''
+  };
+}
+
+/**
+ * Get the subagents repository clone URL
+ * @returns {string}
+ */
+export function getSubagentsRepoUrl() {
+  return `https://github.com/${SUBAGENTS_REPO_OWNER}/${SUBAGENTS_REPO_NAME}.git`;
+}
+
+export { SUBAGENTS_REPO_OWNER, SUBAGENTS_REPO_NAME };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@supercorks/skills-installer",
-  "version": "1.0.0",
-  "description": "Interactive CLI installer for AI agent skills",
+  "version": "1.2.0",
+  "description": "Interactive CLI installer for AI agent skills and subagents",
   "type": "module",
   "bin": {
     "skills-installer": "./bin/install.js"
@@ -11,7 +11,9 @@
     "lib/"
   ],
   "scripts": {
-    "start": "node bin/install.js install"
+    "start": "node bin/install.js install",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "repository": {
     "type": "git",
@@ -28,6 +30,7 @@
     "ai",
     "agent",
     "skills",
+    "subagents",
     "copilot",
     "claude",
     "installer",
@@ -38,6 +41,9 @@
   "dependencies": {
     "inquirer": "^9.2.12"
   },
+  "devDependencies": {
+    "vitest": "^2.1.0"
+  },
   "engines": {
     "node": ">=18.0.0"
   }