ai-agent-skills 1.6.1 → 1.7.0

package/README.md

@@ -29,16 +29,14 @@
 ## Quick Start
 
 ```bash
-# Browse skills interactively
-npx ai-agent-skills browse
-
-# Install from our curated catalog
+# Install a skill to ALL agents with one command
 npx ai-agent-skills install frontend-design
 
-# Install for specific agents
+# Install to a specific agent only
 npx ai-agent-skills install frontend-design --agent cursor
-npx ai-agent-skills install frontend-design --agent codex
-npx ai-agent-skills install frontend-design --agent amp
+
+# Browse skills interactively
+npx ai-agent-skills browse
 
 # Install from any GitHub repo
 npx ai-agent-skills install anthropics/skills
@@ -48,7 +46,7 @@ npx ai-agent-skills install anthropics/skills/pdf    # specific skill
 npx ai-agent-skills install ./my-custom-skill
 ```
 
-That's it. The skill installs to the right location for your agent automatically.
+**One command. Every agent.** By default, skills install to Claude Code, Cursor, Codex, Amp, VS Code, Copilot, Goose, Letta, and OpenCode simultaneously.
 
 ## Why This Exists
 
@@ -58,7 +56,7 @@ This repo curates the best in one place. Quality over quantity. All skills follo
 
 ## Compatible Agents
 
-Works with **Claude Code**, **Cursor**, **Amp**, **VS Code**, **GitHub Copilot**, **Goose**, **Letta**, **OpenCode**, and **Claude.ai**.
+Works with **Claude Code**, **Cursor**, **Codex**, **Amp**, **VS Code**, **GitHub Copilot**, **Goose**, **Letta**, and **OpenCode**.
 
 ## Available Skills
 
@@ -133,12 +131,11 @@ npx ai-agent-skills list
 npx ai-agent-skills list --category development
 npx ai-agent-skills list --installed --agent cursor
 
-# Install from catalog, GitHub, or local path
-npx ai-agent-skills install <name>                    # from catalog
-npx ai-agent-skills install <owner/repo>              # from GitHub
-npx ai-agent-skills install <owner/repo/skill>        # specific skill from GitHub
-npx ai-agent-skills install ./path                    # from local path
-npx ai-agent-skills install <name> --agent cursor     # for specific agent
+# Install (defaults to ALL agents)
+npx ai-agent-skills install <name>                    # installs to ALL agents
+npx ai-agent-skills install <name> --agent cursor     # install to specific agent only
+npx ai-agent-skills install <owner/repo>              # from GitHub (all agents)
+npx ai-agent-skills install ./path                    # from local path (all agents)
 npx ai-agent-skills install <name> --dry-run          # preview only
 
 # Manage installed skills
@@ -156,15 +153,17 @@ npx ai-agent-skills config --default-agent cursor
 
 ### Supported Agents
 
+By default, `install` targets **all agents**. Use `--agent <name>` to install to a specific one.
+
 | Agent | Flag | Install Location |
 |-------|------|------------------|
-| Claude Code | `--agent claude` (default) | `~/.claude/skills/` |
+| Claude Code | `--agent claude` | `~/.claude/skills/` |
 | Cursor | `--agent cursor` | `.cursor/skills/` |
+| Codex | `--agent codex` | `~/.codex/skills/` |
 | Amp | `--agent amp` | `~/.amp/skills/` |
 | VS Code / Copilot | `--agent vscode` | `.github/skills/` |
 | Goose | `--agent goose` | `~/.config/goose/skills/` |
-| OpenCode | `--agent opencode` | `~/.opencode/skills/` |
-| Codex | `--agent codex` | `~/.codex/skills/` |
+| OpenCode | `--agent opencode` | `~/.opencode/skill/` |
 | Letta | `--agent letta` | `~/.letta/skills/` |
 | Portable | `--agent project` | `.skills/` (works with any agent) |
 

package/cli.js

@@ -24,7 +24,7 @@ const AGENT_PATHS = {
   copilot: path.join(process.cwd(), '.github', 'skills'),
   project: path.join(process.cwd(), '.skills'),
   goose: path.join(os.homedir(), '.config', 'goose', 'skills'),
-  opencode: path.join(os.homedir(), '.opencode', 'skill'),
+  opencode: path.join(os.homedir(), '.config', 'opencode', 'skill'),
   codex: path.join(os.homedir(), '.codex', 'skills'),
   letta: path.join(os.homedir(), '.letta', 'skills'),
 };
@@ -70,6 +70,41 @@ function saveConfig(config) {
   }
 }
 
+// ============ SKILL METADATA SUPPORT ============
+
+const SKILL_META_FILE = '.skill-meta.json';
+
+function writeSkillMeta(skillPath, meta) {
+  try {
+    const metaPath = path.join(skillPath, SKILL_META_FILE);
+    const now = new Date().toISOString();
+    const metadata = {
+      ...meta,
+      // Preserve original installedAt if it exists, otherwise set it
+      installedAt: meta.installedAt || now,
+      // Always update the updatedAt timestamp
+      updatedAt: now
+    };
+    fs.writeFileSync(metaPath, JSON.stringify(metadata, null, 2));
+    return true;
+  } catch (e) {
+    // Non-fatal - skill still works without metadata
+    return false;
+  }
+}
+
+function readSkillMeta(skillPath) {
+  try {
+    const metaPath = path.join(skillPath, SKILL_META_FILE);
+    if (fs.existsSync(metaPath)) {
+      return JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+    }
+  } catch (e) {
+    // Ignore - treat as legacy skill
+  }
+  return null;
+}
+
 // ============ SECURITY VALIDATION ============
 
 function validateSkillName(name) {
@@ -151,6 +186,7 @@ function parseArgs(args) {
     param: null,
     agents: [],           // New: array of agents
     allAgents: false,     // New: --all-agents flag
+    explicitAgent: false, // Track if user explicitly specified agent(s)
     installed: false,
     all: false,
     dryRun: false,
@@ -163,6 +199,7 @@ function parseArgs(args) {
 
     // --agents claude,cursor,codex (multiple agents)
     if (arg === '--agents') {
+      result.explicitAgent = true;
       const value = args[i + 1] || '';
       value.split(',').forEach(a => {
         const agent = a.trim();
@@ -174,6 +211,7 @@ function parseArgs(args) {
     }
     // --agent cursor (single agent, backward compatible)
     else if (arg === '--agent' || arg === '-a') {
+      result.explicitAgent = true;
       let agentValue = args[i + 1] || defaultAgent;
       agentValue = agentValue.replace(/^-+/, '');
       if (validAgents.includes(agentValue) && !result.agents.includes(agentValue)) {
@@ -183,6 +221,7 @@ function parseArgs(args) {
     }
     // --all-agents (install to all known agents)
     else if (arg === '--all-agents') {
+      result.explicitAgent = true;
       result.allAgents = true;
     }
     else if (arg === '--installed' || arg === '-i') {
@@ -205,6 +244,7 @@ function parseArgs(args) {
     else if (arg.startsWith('--')) {
       const potentialAgent = arg.replace(/^--/, '');
       if (validAgents.includes(potentialAgent)) {
+        result.explicitAgent = true;
         if (!result.agents.includes(potentialAgent)) {
           result.agents.push(potentialAgent);
         }
@@ -362,6 +402,12 @@ function installSkill(skillName, agent = 'claude', dryRun = false) {
 
     copyDir(sourcePath, destPath);
 
+    // Write metadata for update tracking
+    writeSkillMeta(destPath, {
+      source: 'registry',
+      name: skillName
+    });
+
     success(`\nInstalled: ${skillName}`);
     info(`Agent: ${agent}`);
     info(`Location: ${destPath}`);
@@ -469,32 +515,133 @@ function listInstalledSkills(agent = 'claude') {
   log(`${colors.dim}Uninstall: npx ai-agent-skills uninstall <name> --agent ${agent}${colors.reset}`);
 }
 
-function updateSkill(skillName, agent = 'claude', dryRun = false) {
+// Update from bundled registry
+function updateFromRegistry(skillName, agent, destPath, dryRun) {
+  const sourcePath = path.join(SKILLS_DIR, skillName);
+
+  if (!fs.existsSync(sourcePath)) {
+    error(`Skill "${skillName}" not found in repository.`);
+    return false;
+  }
+
+  if (dryRun) {
+    log(`\n${colors.bold}Dry Run${colors.reset} (no changes made)\n`);
+    info(`Would update: ${skillName} (from registry)`);
+    info(`Agent: ${agent}`);
+    info(`Path: ${destPath}`);
+    return true;
+  }
+
   try {
-    validateSkillName(skillName);
+    fs.rmSync(destPath, { recursive: true });
+    copyDir(sourcePath, destPath);
+
+    // Write metadata
+    writeSkillMeta(destPath, {
+      source: 'registry',
+      name: skillName
+    });
+
+    success(`\nUpdated: ${skillName}`);
+    info(`Agent: ${agent}`);
+    info(`Location: ${destPath}`);
+    return true;
   } catch (e) {
-    error(e.message);
+    error(`Failed to update skill: ${e.message}`);
     return false;
   }
+}
 
-  const sourcePath = path.join(SKILLS_DIR, skillName);
-  const destDir = AGENT_PATHS[agent] || AGENT_PATHS.claude;
-  const destPath = path.join(destDir, skillName);
+// Update from GitHub repository
+function updateFromGitHub(meta, skillName, agent, destPath, dryRun) {
+  const { execFileSync } = require('child_process');
+  const repo = meta.repo;
+
+  // Validate repo format
+  if (!repo || typeof repo !== 'string' || !repo.includes('/')) {
+    error(`Invalid repository in metadata: ${repo}`);
+    error(`Try reinstalling the skill from GitHub.`);
+    return false;
+  }
+
+  if (dryRun) {
+    log(`\n${colors.bold}Dry Run${colors.reset} (no changes made)\n`);
+    info(`Would update: ${skillName} (from github:${repo})`);
+    info(`Agent: ${agent}`);
+    info(`Path: ${destPath}`);
+    return true;
+  }
+
+  const tempDir = path.join(os.tmpdir(), `ai-skills-update-${Date.now()}`);
+
+  try {
+    info(`Updating ${skillName} from ${repo}...`);
+    const repoUrl = `https://github.com/${repo}.git`;
+    execFileSync('git', ['clone', '--depth', '1', repoUrl, tempDir], { stdio: 'pipe' });
+
+    // Determine source path in cloned repo
+    let sourcePath;
+    if (meta.isRootSkill) {
+      sourcePath = tempDir;
+    } else if (meta.skillPath) {
+      // Check if skills/ subdirectory exists
+      const skillsSubdir = path.join(tempDir, 'skills', meta.skillPath);
+      const directPath = path.join(tempDir, meta.skillPath);
+      sourcePath = fs.existsSync(skillsSubdir) ? skillsSubdir : directPath;
+    } else {
+      sourcePath = tempDir;
+    }
+
+    if (!fs.existsSync(sourcePath) || !fs.existsSync(path.join(sourcePath, 'SKILL.md'))) {
+      error(`Skill not found in repository ${repo}`);
+      fs.rmSync(tempDir, { recursive: true });
+      return false;
+    }
+
+    fs.rmSync(destPath, { recursive: true });
+    copyDir(sourcePath, destPath);
+
+    // Preserve metadata
+    writeSkillMeta(destPath, meta);
+
+    fs.rmSync(tempDir, { recursive: true });
+
+    success(`\nUpdated: ${skillName}`);
+    info(`Source: github:${repo}`);
+    info(`Agent: ${agent}`);
+    info(`Location: ${destPath}`);
+    return true;
+  } catch (e) {
+    error(`Failed to update from GitHub: ${e.message}`);
+    try { fs.rmSync(tempDir, { recursive: true }); } catch {}
+    return false;
+  }
+}
+
+// Update from local path
+function updateFromLocalPath(meta, skillName, agent, destPath, dryRun) {
+  const sourcePath = meta.path;
+
+  if (!sourcePath || typeof sourcePath !== 'string') {
+    error(`Invalid path in metadata.`);
+    error(`Try reinstalling the skill from the local path.`);
+    return false;
+  }
 
   if (!fs.existsSync(sourcePath)) {
-    error(`Skill "${skillName}" not found in repository.`);
+    error(`Source path no longer exists: ${sourcePath}`);
     return false;
   }
 
-  if (!fs.existsSync(destPath)) {
-    error(`Skill "${skillName}" is not installed for ${agent}.`);
-    log(`\nUse 'install' to add it first.`);
+  // Verify it's still a valid skill directory
+  if (!fs.existsSync(path.join(sourcePath, 'SKILL.md'))) {
+    error(`Source is no longer a valid skill (missing SKILL.md): ${sourcePath}`);
     return false;
   }
 
   if (dryRun) {
     log(`\n${colors.bold}Dry Run${colors.reset} (no changes made)\n`);
-    info(`Would update: ${skillName}`);
+    info(`Would update: ${skillName} (from local:${sourcePath})`);
     info(`Agent: ${agent}`);
     info(`Path: ${destPath}`);
     return true;
@@ -504,16 +651,57 @@ function updateSkill(skillName, agent = 'claude', dryRun = false) {
     fs.rmSync(destPath, { recursive: true });
     copyDir(sourcePath, destPath);
 
+    // Preserve metadata
+    writeSkillMeta(destPath, meta);
+
     success(`\nUpdated: ${skillName}`);
+    info(`Source: local:${sourcePath}`);
     info(`Agent: ${agent}`);
     info(`Location: ${destPath}`);
     return true;
   } catch (e) {
-    error(`Failed to update skill: ${e.message}`);
+    error(`Failed to update from local path: ${e.message}`);
     return false;
   }
 }
 
+function updateSkill(skillName, agent = 'claude', dryRun = false) {
+  try {
+    validateSkillName(skillName);
+  } catch (e) {
+    error(e.message);
+    return false;
+  }
+
+  const destDir = AGENT_PATHS[agent] || AGENT_PATHS.claude;
+  const destPath = path.join(destDir, skillName);
+
+  if (!fs.existsSync(destPath)) {
+    error(`Skill "${skillName}" is not installed for ${agent}.`);
+    log(`\nUse 'install' to add it first.`);
+    return false;
+  }
+
+  // Read metadata to determine source
+  const meta = readSkillMeta(destPath);
+
+  if (!meta) {
+    // Legacy skill without metadata - try registry
+    return updateFromRegistry(skillName, agent, destPath, dryRun);
+  }
+
+  // Route to correct update method based on source
+  switch (meta.source) {
+    case 'github':
+      return updateFromGitHub(meta, skillName, agent, destPath, dryRun);
+    case 'local':
+      return updateFromLocalPath(meta, skillName, agent, destPath, dryRun);
+    case 'registry':
+    default:
+      return updateFromRegistry(skillName, agent, destPath, dryRun);
+  }
+}
+
 function updateAllSkills(agent = 'claude', dryRun = false) {
   const installed = getInstalledSkills(agent);
 
@@ -905,6 +1093,14 @@ async function installFromGitHub(source, agent = 'claude', dryRun = false) {
       }
 
       copyDir(skillPath, destPath);
+
+      // Write metadata for update tracking
+      writeSkillMeta(destPath, {
+        source: 'github',
+        repo: `${owner}/${repo}`,
+        skillPath: skillName
+      });
+
       success(`\nInstalled: ${skillName} from ${owner}/${repo}`);
       info(`Location: ${destPath}`);
     } else if (isRootSkill) {
@@ -928,6 +1124,14 @@ async function installFromGitHub(source, agent = 'claude', dryRun = false) {
       }
 
       copyDir(tempDir, destPath);
+
+      // Write metadata for update tracking
+      writeSkillMeta(destPath, {
+        source: 'github',
+        repo: `${owner}/${repo}`,
+        isRootSkill: true
+      });
+
       success(`\nInstalled: ${skillName} from ${owner}/${repo}`);
       info(`Location: ${destPath}`);
     } else {
@@ -947,6 +1151,14 @@ async function installFromGitHub(source, agent = 'claude', dryRun = false) {
             }
 
             copyDir(skillPath, destPath);
+
+            // Write metadata for update tracking
+            writeSkillMeta(destPath, {
+              source: 'github',
+              repo: `${owner}/${repo}`,
+              skillPath: entry.name
+            });
+
             log(`  ${colors.green}✓${colors.reset} ${entry.name}`);
             installed++;
           }
@@ -1005,6 +1217,13 @@ function installFromLocalPath(source, agent = 'claude', dryRun = false) {
     }
 
     copyDir(sourcePath, destPath);
+
+    // Write metadata for update tracking
+    writeSkillMeta(destPath, {
+      source: 'local',
+      path: sourcePath
+    });
+
     success(`\nInstalled: ${skillName} from local path`);
     info(`Location: ${destPath}`);
   } else {
@@ -1024,6 +1243,13 @@ function installFromLocalPath(source, agent = 'claude', dryRun = false) {
           }
 
           copyDir(skillPath, destPath);
+
+          // Write metadata for update tracking
+          writeSkillMeta(destPath, {
+            source: 'local',
+            path: skillPath
+          });
+
           log(`  ${colors.green}✓${colors.reset} ${entry.name}`);
           installed++;
         }
@@ -1055,7 +1281,8 @@ ${colors.bold}Commands:${colors.reset}
   ${colors.green}list${colors.reset}                             List all available skills
   ${colors.green}list --installed${colors.reset}                 List installed skills for an agent
   ${colors.green}list --category <cat>${colors.reset}            Filter by category
-  ${colors.green}install <name>${colors.reset}                   Install a skill from catalog
+  ${colors.green}install <name>${colors.reset}                   Install to ALL agents (default)
+  ${colors.green}install <name> --agent cursor${colors.reset}    Install to specific agent only
   ${colors.green}install <owner/repo>${colors.reset}             Install from GitHub repository
   ${colors.green}install ./path${colors.reset}                   Install from local path
   ${colors.green}install <name> --dry-run${colors.reset}         Preview installation without changes
@@ -1069,39 +1296,36 @@ ${colors.bold}Commands:${colors.reset}
   ${colors.green}help${colors.reset}                             Show this help
 
 ${colors.bold}Options:${colors.reset}
-  ${colors.cyan}--agent <name>${colors.reset}       Target single agent (default: claude)
+  ${colors.cyan}--agent <name>${colors.reset}       Target specific agent (install defaults to ALL)
   ${colors.cyan}--agents <list>${colors.reset}      Target multiple agents (comma-separated)
-  ${colors.cyan}--all-agents${colors.reset}         Target ALL known agents at once
   ${colors.cyan}--installed${colors.reset}          Show only installed skills (with list)
   ${colors.cyan}--dry-run, -n${colors.reset}        Preview changes without applying
   ${colors.cyan}--category <c>${colors.reset}       Filter by category
   ${colors.cyan}--all${colors.reset}                Apply to all (with update)
   ${colors.cyan}--version, -v${colors.reset}        Show version number
 
-${colors.bold}Agents:${colors.reset}
-  ${colors.cyan}claude${colors.reset}   (default) ~/.claude/skills/
-  ${colors.cyan}cursor${colors.reset}   .cursor/skills/ in current project
+${colors.bold}Agents:${colors.reset} (install targets ALL by default)
+  ${colors.cyan}claude${colors.reset}   ~/.claude/skills/
+  ${colors.cyan}cursor${colors.reset}   .cursor/skills/ (project)
+  ${colors.cyan}codex${colors.reset}    ~/.codex/skills/
   ${colors.cyan}amp${colors.reset}      ~/.amp/skills/
-  ${colors.cyan}vscode${colors.reset}   .github/skills/ in current project
+  ${colors.cyan}vscode${colors.reset}   .github/skills/ (project)
   ${colors.cyan}copilot${colors.reset}  .github/skills/ (alias for vscode)
   ${colors.cyan}goose${colors.reset}    ~/.config/goose/skills/
   ${colors.cyan}opencode${colors.reset} ~/.opencode/skill/
-  ${colors.cyan}codex${colors.reset}    ~/.codex/skills/
   ${colors.cyan}letta${colors.reset}    ~/.letta/skills/
-  ${colors.cyan}project${colors.reset}  .skills/ in current directory (portable)
+  ${colors.cyan}project${colors.reset}  .skills/ (portable)
 
 ${colors.bold}Categories:${colors.reset}
   development, document, creative, business, productivity
 
 ${colors.bold}Examples:${colors.reset}
   npx ai-agent-skills browse                              # Interactive browser
-  npx ai-agent-skills install frontend-design             # Install from catalog
+  npx ai-agent-skills install frontend-design             # Install to ALL agents
+  npx ai-agent-skills install pdf --agent cursor          # Install to Cursor only
+  npx ai-agent-skills install pdf --agents claude,cursor  # Install to specific agents
   npx ai-agent-skills install anthropics/skills           # Install from GitHub
-  npx ai-agent-skills install anthropics/skills/pdf       # Install specific skill from GitHub
   npx ai-agent-skills install ./my-skill                  # Install from local path
-  npx ai-agent-skills install pdf --agent cursor          # Install for Cursor
-  npx ai-agent-skills install pdf --agents claude,cursor  # Install for multiple agents
-  npx ai-agent-skills install pdf --all-agents            # Install for ALL agents
   npx ai-agent-skills install pdf --dry-run               # Preview install
   npx ai-agent-skills list --category development
   npx ai-agent-skills search testing
@@ -1207,7 +1431,8 @@ function setConfig(key, value) {
 // ============ MAIN CLI ============
 
 const args = process.argv.slice(2);
-const { command, param, agents, installed, dryRun, category, tags, all } = parseArgs(args);
+const { command, param, agents, explicitAgent, installed, dryRun, category, tags, all } = parseArgs(args);
+const ALL_AGENTS = Object.keys(AGENT_PATHS);
 
 // Handle config commands specially
 if (command === 'config') {
@@ -1252,11 +1477,12 @@ switch (command || 'help') {
   case 'add':
     if (!param) {
       error('Please specify a skill name, GitHub repo, or local path.');
-      log('Usage: npx ai-agent-skills install <name> [--agents claude,cursor] [--all-agents]');
+      log('Usage: npx ai-agent-skills install <name> [--agent cursor]');
       process.exit(1);
     }
-    // Install to all specified agents
-    for (const agent of agents) {
+    // Default to ALL agents when no agent explicitly specified
+    const installTargets = explicitAgent ? agents : ALL_AGENTS;
+    for (const agent of installTargets) {
       if (isLocalPath(param)) {
         installFromLocalPath(param, agent, dryRun);
       } else if (isGitHubUrl(param)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-agent-skills",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "description": "Install curated AI agent skills with one command. Works with Claude Code, Cursor, Amp, VS Code, and all Agent Skills compatible tools.",
   "main": "cli.js",
   "bin": {