@supercorks/skills-installer 1.6.0 → 1.8.0

package/README.md

@@ -1,6 +1,6 @@
 # @supercorks/skills-installer
 
-Interactive CLI installer for AI agent skills. Selectively install skills for GitHub Copilot, 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.
 
 ## Usage
 
@@ -16,22 +16,32 @@ npx @supercorks/skills-installer install
 
 ## What it does
 
-1. **Choose installation path(s)** - Select one or more locations where skills should be installed:
-   - `.github/skills/` (GitHub Copilot default)
-   - `.agents/skills/` (Agent workspace skills)
-   - `/etc/codex/skills/` (System-level skills)
+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)
    - Custom path of your choice
 
-2. **Gitignore option** - Optionally add the installation path to `.gitignore`
+3. **Gitignore option** - Optionally add the installation path to `.gitignore`
 
-3. **Select skills** - Interactive checkbox to pick which skills to install:
+4. **Select skills/subagents** - Interactive checkbox to pick what to install:
    - Use `↑`/`↓` to navigate
    - Use `SPACE` to toggle selection
+   - Use `→` to expand and lazy-load descriptions
    - Use `A` to toggle all
    - Press `ENTER` to confirm
 
-4. **Sparse clone** - Only downloads the selected skills using Git sparse-checkout, keeping the download minimal while preserving full git functionality.
+5. **Sparse clone** - Only downloads selected skills/subagents using Git sparse-checkout, keeping the download minimal while preserving full git functionality.
+
+## Installed repositories
+
+- Skills repo: [https://github.com/supercorks/agent-skills](https://github.com/supercorks/agent-skills)
+- Subagents repo: [https://github.com/supercorks/subagents](https://github.com/supercorks/subagents)
 
 ## Features
 

package/bin/install.js

@@ -9,6 +9,7 @@
 
 import { existsSync, appendFileSync, readFileSync, writeFileSync } from 'fs';
 import { resolve, join } from 'path';
+import { homedir } from 'os';
 import { 
   promptInstallType,
   promptInstallPath,
@@ -21,8 +22,8 @@ import {
   showSubagentSuccess,
   showError
 } from '../lib/prompts.js';
-import { fetchAvailableSkills } from '../lib/skills.js';
-import { fetchAvailableSubagents } from '../lib/subagents.js';
+import { fetchAvailableSkills, fetchSkillMetadata } from '../lib/skills.js';
+import { fetchAvailableSubagents, fetchSubagentMetadata } from '../lib/subagents.js';
 import { 
   sparseCloneSkills, 
   isGitAvailable, 
@@ -40,8 +41,14 @@ 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/', '.agents/skills/', '/etc/codex/skills/', '.claude/skills/'];
-const AGENT_PATHS = ['.github/agents/', '.claude/agents/'];
+const SKILL_PATHS = ['.github/skills/', '~/.codex/skills/', '.claude/skills/'];
+const AGENT_PATHS = ['.github/agents/', '.agents/agents/', '.claude/agents/'];
+
+function resolveInstallPath(path) {
+  if (path === '~') return homedir();
+  if (path.startsWith('~/')) return resolve(homedir(), path.slice(2));
+  return resolve(process.cwd(), path);
+}
 
 /**
  * Detect existing skill installations in common paths
@@ -51,7 +58,7 @@ async function detectExistingSkillInstallations() {
   const installations = [];
   
   for (const path of SKILL_PATHS) {
-    const absolutePath = resolve(process.cwd(), path);
+    const absolutePath = resolveInstallPath(path);
     const gitDir = join(absolutePath, '.git');
     
     if (existsSync(gitDir)) {
@@ -79,7 +86,7 @@ async function detectExistingAgentInstallations() {
   const installations = [];
   
   for (const path of AGENT_PATHS) {
-    const absolutePath = resolve(process.cwd(), path);
+    const absolutePath = resolveInstallPath(path);
     const gitDir = join(absolutePath, '.git');
     
     if (existsSync(gitDir)) {
@@ -227,7 +234,7 @@ async function runSkillsInstall() {
  */
 async function runSkillsInstallForTarget(skills, existingInstalls, target) {
   const { path: installPath, isExisting } = target;
-  const absoluteInstallPath = resolve(process.cwd(), installPath);
+  const absoluteInstallPath = resolveInstallPath(installPath);
 
   // Get currently installed skills if managing existing installation
   let installedSkills = [];
@@ -266,13 +273,18 @@ async function runSkillsInstallForTarget(skills, existingInstalls, target) {
 
   // Ask about .gitignore (only for fresh installs and if not already in .gitignore)
   let shouldGitignore = false;
-  const gitignorePath = resolve(process.cwd(), '.gitignore');
+  const gitignorePath = resolveInstallPath('.gitignore');
   if (!isManageMode && !isInGitignore(gitignorePath, installPath)) {
     shouldGitignore = await promptGitignore(installPath);
   }
 
   // Select skills (pre-select installed skills in manage mode)
-  const selectedSkills = await promptSkillSelection(skills, installedSkills, skillsNeedingUpdate);
+  const selectedSkills = await promptSkillSelection(
+    skills,
+    installedSkills,
+    skillsNeedingUpdate,
+    (skillFolder) => fetchSkillMetadata(skillFolder)
+  );
 
   // Perform installation or update
   console.log('');
@@ -374,7 +386,7 @@ async function runSubagentsInstall() {
  */
 async function runSubagentsInstallForTarget(subagents, existingInstalls, target) {
   const { path: installPath, isExisting } = target;
-  const absoluteInstallPath = resolve(process.cwd(), installPath);
+  const absoluteInstallPath = resolveInstallPath(installPath);
 
   // Get currently installed subagents if managing existing installation
   let installedAgents = [];
@@ -413,13 +425,18 @@ async function runSubagentsInstallForTarget(subagents, existingInstalls, target)
 
   // Ask about .gitignore (only for fresh installs and if not already in .gitignore)
   let shouldGitignore = false;
-  const gitignorePath = resolve(process.cwd(), '.gitignore');
+  const gitignorePath = resolveInstallPath('.gitignore');
   if (!isManageMode && !isInGitignore(gitignorePath, installPath)) {
     shouldGitignore = await promptGitignore(installPath);
   }
 
   // Select subagents (pre-select installed ones in manage mode)
-  const selectedAgents = await promptSubagentSelection(subagents, installedAgents, subagentsNeedingUpdate);
+  const selectedAgents = await promptSubagentSelection(
+    subagents,
+    installedAgents,
+    subagentsNeedingUpdate,
+    (filename) => fetchSubagentMetadata(filename)
+  );
 
   // Perform installation or update
   console.log('');

package/lib/git.js

@@ -3,7 +3,7 @@
  */
 
 import { execSync, spawn } from 'child_process';
-import { existsSync, mkdirSync, rmSync, writeFileSync, readFileSync, appendFileSync } from 'fs';
+import { existsSync, mkdirSync, rmSync, writeFileSync, readFileSync, appendFileSync, readdirSync } from 'fs';
 import { join, resolve } from 'path';
 import { getRepoUrl } from './skills.js';
 import { getSubagentsRepoUrl } from './subagents.js';
@@ -71,6 +71,10 @@ export async function sparseCloneSkills(targetPath, skillFolders, onProgress = (
     if (existsSync(gitDir)) {
       throw new Error(`Directory "${targetPath}" already contains a git repository. Please remove it first or choose a different path.`);
     }
+    const entries = readdirSync(absolutePath).filter(name => name !== '.DS_Store');
+    if (entries.length > 0) {
+      throw new Error(`Directory "${targetPath}" already exists and is not empty. Choose an empty directory or an existing managed installation.`);
+    }
   }
 
   // Create target directory
@@ -328,6 +332,10 @@ export async function sparseCloneSubagents(targetPath, agentFilenames, onProgres
     if (existsSync(gitDir)) {
       throw new Error(`Directory "${targetPath}" already contains a git repository. Please remove it first or choose a different path.`);
     }
+    const entries = readdirSync(absolutePath).filter(name => name !== '.DS_Store');
+    if (entries.length > 0) {
+      throw new Error(`Directory "${targetPath}" already exists and is not empty. Choose an empty directory or an existing managed installation.`);
+    }
   }
 
   // Create target directory

package/lib/prompts.js

@@ -7,14 +7,14 @@ import * as readline from 'readline';
 
 const SKILL_PATH_CHOICES = {
   GITHUB: '.github/skills/',
-  AGENTS: '.agents/skills/',
-  ETC: '/etc/codex/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__'
 };
@@ -80,15 +80,14 @@ export async function promptInstallPath(existingInstalls = []) {
   
   // Standard path options
   const standardPaths = [
-    SKILL_PATH_CHOICES.GITHUB,
-    SKILL_PATH_CHOICES.AGENTS,
-    SKILL_PATH_CHOICES.ETC,
-    SKILL_PATH_CHOICES.CLAUDE
+    { 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 => {
+  standardPaths.forEach(({ path, label }) => {
     if (!existingPaths.includes(path)) {
-      choices.push({ name: path, value: path });
+      choices.push({ name: label, value: path });
     }
   });
   
@@ -163,11 +162,15 @@ export async function promptAgentInstallPath(existingInstalls = []) {
   }
   
   // Standard path options
-  const standardPaths = [AGENT_PATH_CHOICES.GITHUB, AGENT_PATH_CHOICES.CLAUDE];
+  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 => {
+  standardPaths.forEach(({ path, label }) => {
     if (!existingPaths.includes(path)) {
-      choices.push({ name: path, value: path });
+      choices.push({ name: label, value: path });
     }
   });
   
@@ -244,14 +247,16 @@ export async function promptGitignore(installPath) {
  * @param {Array<{name: string, description: string, folder: string}>} skills - Available skills
  * @param {string[]} installedSkills - Already installed skill folder names (will be pre-selected)
  * @param {Set<string>} skillsNeedingUpdate - Skill folder names that have updates available
+ * @param {(skillFolder: string) => Promise<{name?: string, description?: string}>} metadataLoader - Lazy metadata loader
  * @returns {Promise<string[]>} Selected skill folder names
  */
-export async function promptSkillSelection(skills, installedSkills = [], skillsNeedingUpdate = new Set()) {
+export async function promptSkillSelection(skills, installedSkills = [], skillsNeedingUpdate = new Set(), metadataLoader = null) {
   return promptItemSelection(
     skills.map(s => ({ id: s.folder, name: s.name, description: s.description })),
     installedSkills,
     '📦 Available Skills',
-    skillsNeedingUpdate
+    skillsNeedingUpdate,
+    metadataLoader
   );
 }
 
@@ -260,14 +265,16 @@ export async function promptSkillSelection(skills, installedSkills = [], skillsN
  * @param {Array<{name: string, description: string, filename: string}>} subagents - Available subagents
  * @param {string[]} installedSubagents - Already installed subagent filenames (will be pre-selected)
  * @param {Set<string>} subagentsNeedingUpdate - Subagent filenames that have updates available
+ * @param {(agentFilename: string) => Promise<{name?: string, description?: string}>} metadataLoader - Lazy metadata loader
  * @returns {Promise<string[]>} Selected subagent filenames
  */
-export async function promptSubagentSelection(subagents, installedSubagents = [], subagentsNeedingUpdate = new Set()) {
+export async function promptSubagentSelection(subagents, installedSubagents = [], subagentsNeedingUpdate = new Set(), metadataLoader = null) {
   return promptItemSelection(
     subagents.map(s => ({ id: s.filename, name: s.name, description: s.description })),
     installedSubagents,
     '🤖 Available Subagents',
-    subagentsNeedingUpdate
+    subagentsNeedingUpdate,
+    metadataLoader
   );
 }
 
@@ -277,9 +284,10 @@ export async function promptSubagentSelection(subagents, installedSubagents = []
  * @param {string[]} installedItems - Already installed item IDs (will be pre-selected)
  * @param {string} title - Title to display
  * @param {Set<string>} itemsNeedingUpdate - Item IDs that have updates available
+ * @param {(itemId: string) => Promise<{name?: string, description?: string}>} metadataLoader - Lazy metadata loader
  * @returns {Promise<string[]>} Selected item IDs
  */
-function promptItemSelection(items, installedItems = [], title = '📦 Available Items', itemsNeedingUpdate = new Set()) {
+function promptItemSelection(items, installedItems = [], title = '📦 Available Items', itemsNeedingUpdate = new Set(), metadataLoader = null) {
   return new Promise((resolve, reject) => {
     const rl = readline.createInterface({
       input: process.stdin,
@@ -298,6 +306,8 @@ function promptItemSelection(items, installedItems = [], title = '📦 Available
       ? new Set(installedItems) 
       : new Set(items.map(item => item.id));
     const expanded = new Set();
+    const metadataCache = new Set();
+    const metadataLoading = new Set();
 
     const render = () => {
       // Clear screen and move to top
@@ -305,7 +315,7 @@ function promptItemSelection(items, installedItems = [], title = '📦 Available
       
       console.log(`\n${title}`);
       console.log('─'.repeat(60));
-      console.log('↑↓ navigate  SPACE toggle  → expand  ← collapse  A all  ENTER confirm\n');
+      console.log('↑↓ navigate  SPACE toggle  → expand/load  ← collapse  A all  ENTER confirm\n');
       console.log('Select items to install:\n');
 
       items.forEach((item, i) => {
@@ -328,7 +338,9 @@ function promptItemSelection(items, installedItems = [], title = '📦 Available
         if (isExpanded) {
           console.log(`${highlight}${pointer} ${checkbox} ${item.name}${reset}${updateFlag}`);
           // Show full description indented
-          const fullDesc = item.description || 'No description available';
+          const fullDesc = metadataLoading.has(item.id)
+            ? 'Loading description...'
+            : (item.description || 'No description available');
           const lines = fullDesc.match(/.{1,55}/g) || [fullDesc];
           lines.forEach(line => {
             console.log(`     ${highlight}${line}${reset}`);
@@ -371,7 +383,33 @@ function promptItemSelection(items, installedItems = [], title = '📦 Available
           render();
           break;
         case 'right':
-          expanded.add(items[cursor].id);
+          const currentItem = items[cursor];
+          expanded.add(currentItem.id);
+          if (metadataLoader && !metadataCache.has(currentItem.id) && !metadataLoading.has(currentItem.id)) {
+            metadataLoading.add(currentItem.id);
+            render();
+            metadataLoader(currentItem.id)
+              .then((metadata) => {
+                if (metadata?.name) {
+                  currentItem.name = metadata.name;
+                }
+                if (metadata?.description) {
+                  currentItem.description = metadata.description;
+                } else if (!currentItem.description || currentItem.description === 'Press right arrow to load description') {
+                  currentItem.description = 'Description unavailable';
+                }
+              })
+              .catch(() => {
+                if (!currentItem.description || currentItem.description === 'Press right arrow to load description') {
+                  currentItem.description = 'Description unavailable (metadata fetch failed)';
+                }
+              })
+              .finally(() => {
+                metadataLoading.delete(currentItem.id);
+                metadataCache.add(currentItem.id);
+                render();
+              });
+          }
           render();
           break;
         case 'left':

package/lib/skills.js

@@ -9,6 +9,14 @@ const GITHUB_API = 'https://api.github.com';
 // Folders to exclude from skill detection (not actual skills)
 const EXCLUDED_FOLDERS = ['.github', '.claude', 'node_modules'];
 
+function humanizeSkillName(folder) {
+  return folder
+    .split(/[-_]/g)
+    .filter(Boolean)
+    .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+}
+
 /**
  * Fetch the list of skill directories from the repository
  * Skills are at the repo root level, each folder with a SKILL.md is a skill
@@ -35,23 +43,12 @@ export async function fetchAvailableSkills() {
     item => item.type === 'dir' && !EXCLUDED_FOLDERS.includes(item.name) && !item.name.startsWith('.')
   );
 
-  // Check each directory for SKILL.md to confirm it's a skill
-  const skillChecks = await Promise.all(
-    potentialSkillDirs.map(async (dir) => {
-      const metadata = await fetchSkillMetadata(dir.name);
-      // Only include if we found valid metadata (has a SKILL.md)
-      if (metadata.name || metadata.description) {
-        return {
-          folder: dir.name,
-          name: metadata.name || dir.name,
-          description: metadata.description || 'No description available'
-        };
-      }
-      return null;
-    })
-  );
-
-  return skillChecks.filter(Boolean);
+  // Keep listing lightweight: metadata is loaded lazily on expand in the UI
+  return potentialSkillDirs.map(dir => ({
+    folder: dir.name,
+    name: humanizeSkillName(dir.name),
+    description: 'Press right arrow to load description'
+  }));
 }
 
 /**
@@ -59,7 +56,7 @@ export async function fetchAvailableSkills() {
  * @param {string} skillFolder - The skill folder name
  * @returns {Promise<{name: string, description: string}>}
  */
-async function fetchSkillMetadata(skillFolder) {
+export async function fetchSkillMetadata(skillFolder) {
   const skillMdUrl = `${GITHUB_API}/repos/${REPO_OWNER}/${REPO_NAME}/contents/${skillFolder}/SKILL.md`;
   
   try {
@@ -71,7 +68,7 @@ async function fetchSkillMetadata(skillFolder) {
     });
 
     if (!response.ok) {
-      return { name: '', description: '' };
+      throw new Error(`Failed to fetch skill metadata: ${response.status} ${response.statusText}`);
     }
 
     const data = await response.json();
@@ -79,7 +76,7 @@ async function fetchSkillMetadata(skillFolder) {
     
     return parseSkillFrontmatter(content);
   } catch (error) {
-    return { name: '', description: '' };
+    throw error;
   }
 }
 

package/lib/subagents.js

@@ -6,6 +6,15 @@ const SUBAGENTS_REPO_OWNER = 'supercorks';
 const SUBAGENTS_REPO_NAME = 'subagents';
 const GITHUB_API = 'https://api.github.com';
 
+function humanizeAgentName(filename) {
+  const base = filename.replace('.agent.md', '');
+  return base
+    .split(/[-_]/g)
+    .filter(Boolean)
+    .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+}
+
 /**
  * Fetch the list of subagent files from the repository
  * Subagents are .agent.md files at the repo root
@@ -32,19 +41,12 @@ export async function fetchAvailableSubagents() {
     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;
+  // Keep listing lightweight: metadata is loaded lazily on expand in the UI
+  return agentFiles.map(file => ({
+    filename: file.name,
+    name: humanizeAgentName(file.name),
+    description: 'Press right arrow to load description'
+  }));
 }
 
 /**
@@ -52,7 +54,7 @@ export async function fetchAvailableSubagents() {
  * @param {string} filename - The agent filename
  * @returns {Promise<{name: string, description: string}>}
  */
-async function fetchSubagentMetadata(filename) {
+export async function fetchSubagentMetadata(filename) {
   const fileUrl = `${GITHUB_API}/repos/${SUBAGENTS_REPO_OWNER}/${SUBAGENTS_REPO_NAME}/contents/${filename}`;
   
   try {
@@ -64,7 +66,7 @@ async function fetchSubagentMetadata(filename) {
     });
 
     if (!response.ok) {
-      return { name: '', description: '' };
+      throw new Error(`Failed to fetch subagent metadata: ${response.status} ${response.statusText}`);
     }
 
     const data = await response.json();
@@ -72,7 +74,7 @@ async function fetchSubagentMetadata(filename) {
     
     return parseSubagentFrontmatter(content);
   } catch (error) {
-    return { name: '', description: '' };
+    throw error;
   }
 }
 

package/package.json

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