@supercorks/skills-installer 1.7.0 → 1.9.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,21 +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:
+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

@@ -22,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, 
@@ -279,7 +279,12 @@ async function runSkillsInstallForTarget(skills, existingInstalls, target) {
   }
 
   // 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('');
@@ -426,7 +431,12 @@ async function runSubagentsInstallForTarget(subagents, existingInstalls, target)
   }
 
   // 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/github-auth.js

@@ -0,0 +1,72 @@
+/**
+ * Helpers for authenticated GitHub API requests.
+ * Uses env tokens first, then falls back to `gh auth token` when available.
+ */
+
+import { execFileSync } from 'child_process';
+
+let cachedToken = '';
+let tokenResolved = false;
+
+function normalizeToken(raw) {
+  if (!raw || typeof raw !== 'string') return '';
+  return raw.trim();
+}
+
+function readTokenFromGhCli() {
+  try {
+    const token = execFileSync('gh', ['auth', 'token'], {
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    });
+    return normalizeToken(token);
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Returns a GitHub token if available.
+ * Resolution order: GITHUB_TOKEN -> GH_TOKEN -> gh auth token.
+ * Value is cached for process lifetime.
+ * @returns {string}
+ */
+export function getGitHubAuthToken() {
+  if (tokenResolved) return cachedToken;
+
+  tokenResolved = true;
+  cachedToken =
+    normalizeToken(process.env.GITHUB_TOKEN) ||
+    normalizeToken(process.env.GH_TOKEN) ||
+    readTokenFromGhCli() ||
+    '';
+
+  return cachedToken;
+}
+
+/**
+ * Build GitHub API headers with optional auth.
+ * @param {string} [userAgent='@supercorks/skills-installer']
+ * @returns {Record<string, string>}
+ */
+export function getGitHubHeaders(userAgent = '@supercorks/skills-installer') {
+  const headers = {
+    Accept: 'application/vnd.github.v3+json',
+    'User-Agent': userAgent
+  };
+
+  const token = getGitHubAuthToken();
+  if (token) {
+    headers.Authorization = `Bearer ${token}`;
+  }
+
+  return headers;
+}
+
+/**
+ * Test-only cache reset helper.
+ */
+export function __resetGitHubAuthCacheForTests() {
+  cachedToken = '';
+  tokenResolved = false;
+}

package/lib/prompts.js

@@ -247,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
   );
 }
 
@@ -263,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
   );
 }
 
@@ -280,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,
@@ -301,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
@@ -308,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) => {
@@ -331,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}`);
@@ -374,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

@@ -2,6 +2,8 @@
  * Fetch and parse available skills from the GitHub repository
  */
 
+import { getGitHubHeaders } from './github-auth.js';
+
 const REPO_OWNER = 'supercorks';
 const REPO_NAME = 'agent-skills';
 const GITHUB_API = 'https://api.github.com';
@@ -9,6 +11,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
@@ -18,10 +28,7 @@ export async function fetchAvailableSkills() {
   const repoUrl = `${GITHUB_API}/repos/${REPO_OWNER}/${REPO_NAME}/contents`;
   
   const response = await fetch(repoUrl, {
-    headers: {
-      'Accept': 'application/vnd.github.v3+json',
-      'User-Agent': '@supercorks/skills-installer'
-    }
+    headers: getGitHubHeaders()
   });
 
   if (!response.ok) {
@@ -35,23 +42,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,19 +55,16 @@ 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 {
     const response = await fetch(skillMdUrl, {
-      headers: {
-        'Accept': 'application/vnd.github.v3+json',
-        'User-Agent': '@supercorks/skills-installer'
-      }
+      headers: getGitHubHeaders()
     });
 
     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 +72,7 @@ async function fetchSkillMetadata(skillFolder) {
     
     return parseSkillFrontmatter(content);
   } catch (error) {
-    return { name: '', description: '' };
+    throw error;
   }
 }
 

package/lib/subagents.js

@@ -2,10 +2,21 @@
  * Fetch and parse available subagents from the GitHub repository
  */
 
+import { getGitHubHeaders } from './github-auth.js';
+
 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
@@ -15,10 +26,7 @@ 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'
-    }
+    headers: getGitHubHeaders()
   });
 
   if (!response.ok) {
@@ -32,19 +40,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,19 +53,16 @@ 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 {
     const response = await fetch(fileUrl, {
-      headers: {
-        'Accept': 'application/vnd.github.v3+json',
-        'User-Agent': '@supercorks/skills-installer'
-      }
+      headers: getGitHubHeaders()
     });
 
     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 +70,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.7.0",
+  "version": "1.9.0",
   "description": "Interactive CLI installer for AI agent skills and subagents",
   "type": "module",
   "bin": {