@orchestra-research/ai-research-skills 1.2.1 → 1.3.6

package/README.md

@@ -11,7 +11,7 @@ npx @orchestra-research/ai-research-skills
 - **83 skills** across 20 categories for AI research engineering
 - **Auto-detects** installed coding agents
 - **Interactive installer** with guided experience
-- **One canonical copy** with symlinks to all agents
+- **Global or local install** — install globally with symlinks, or per-project with `--local` for version-controlled, project-specific skill sets
 - **Works with 8 agents**: Claude Code, OpenCode, OpenClaw, Cursor, Codex, Gemini CLI, Qwen Code, and shared `.agents/`
 
 ## Quick Start
@@ -34,7 +34,7 @@ This will:
 # Interactive mode (recommended)
 npx @orchestra-research/ai-research-skills
 
-# Install everything
+# Install everything (global)
 npx @orchestra-research/ai-research-skills install --all
 
 # Install a specific category
@@ -47,6 +47,46 @@ npx @orchestra-research/ai-research-skills list
 npx @orchestra-research/ai-research-skills update
 ```
 
+### Local Installation (per-project)
+
+Install skills directly into your project directory so different projects can have different skill sets:
+
+```bash
+# Install all skills locally to the current project
+npx @orchestra-research/ai-research-skills install --all --local
+
+# Install a category locally
+npx @orchestra-research/ai-research-skills install --category post-training --local
+
+# List locally installed skills
+npx @orchestra-research/ai-research-skills list --local
+
+# Update local skills
+npx @orchestra-research/ai-research-skills update --local
+
+# Uninstall local skills
+npx @orchestra-research/ai-research-skills uninstall --local
+```
+
+Local installation copies skills (not symlinks) into agent directories within your project:
+
+```
+my-project/
+├── .claude/skills/        # Claude Code picks these up
+│   ├── grpo-rl-training/
+│   └── vllm/
+├── .cursor/skills/        # Cursor picks these up
+│   ├── grpo-rl-training/
+│   └── vllm/
+├── .orchestra-skills.json # Tracks installed skills
+└── ...
+```
+
+Benefits:
+- **Per-project skills**: Each project gets only the skills it needs
+- **Version control**: Commit skills to your repo so the whole team has them
+- **Reproducible**: Lock file (`.orchestra-skills.json`) tracks what's installed
+
 ## Categories
 
 | Category | Skills | Description |
@@ -61,25 +101,41 @@ npx @orchestra-research/ai-research-skills update
 
 ## How It Works
 
-1. **Canonical Storage**: Skills are stored once at `~/.agents/skills/`
+### Global Install (default)
+
+1. **Canonical Storage**: Skills are stored once at `~/.orchestra/skills/`
 2. **Symlinks**: Each agent gets symlinks pointing to the canonical copy
 3. **Auto-activation**: Skills activate when you discuss relevant topics
 
 ```
-~/.agents/skills/          # Single source of truth
+~/.orchestra/skills/       # Single source of truth
 ├── 06-post-training/
 │   ├── verl/
 │   └── grpo-rl-training/
 └── ...
 
 ~/.claude/skills/          # Symlinks for Claude Code
-├── verl → ~/.agents/skills/.../verl
+├── verl → ~/.orchestra/skills/.../verl
 └── grpo-rl-training → ...
 
 ~/.cursor/skills/          # Symlinks for Cursor
 └── (same links)
 ```
 
+### Local Install (`--local`)
+
+1. **Direct Copy**: Skills are copied into agent directories within your project
+2. **Version Control**: Files can be committed to git for team sharing
+3. **Lock File**: `.orchestra-skills.json` tracks what's installed
+
+```
+my-project/
+├── .claude/skills/verl/           # Copied for Claude Code
+├── .cursor/skills/verl/           # Copied for Cursor
+├── .codex/skills/verl/            # Copied for Codex
+└── .orchestra-skills.json         # Lock file
+```
+
 ## Supported Agents
 
 | Agent | Config Directory |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orchestra-research/ai-research-skills",
-  "version": "1.2.1",
+  "version": "1.3.6",
   "description": "Install AI research engineering skills to your coding agents (Claude Code, OpenCode, Cursor, Gemini CLI, and more)",
   "main": "src/index.js",
   "bin": {

package/src/agents.js

@@ -3,8 +3,13 @@ import { homedir } from 'os';
 import { join } from 'path';
 
 /**
- * Supported coding agents with their global config directories and skills paths
- * All agents now support ~/.{agent}/skills/ format
+ * Supported coding agents with their global and local config directories
+ *
+ * Global: ~/.{agent}/skills/ (home directory)
+ * Local:  .{agent}/skills/  (project directory)
+ *
+ * localConfigDir/localSkillsDir define where skills go at the project level.
+ * These may differ from global paths (e.g., OpenClaw uses <project>/skills/).
  */
 export const SUPPORTED_AGENTS = [
   {
@@ -12,53 +17,69 @@ export const SUPPORTED_AGENTS = [
     name: 'Claude Code',
     configDir: '.claude',
     skillsDir: 'skills',
+    localConfigDir: '.claude',
+    localSkillsDir: 'skills',
   },
   {
     id: 'cursor',
     name: 'Cursor',
     configDir: '.cursor',
     skillsDir: 'skills',
+    localConfigDir: '.cursor',
+    localSkillsDir: 'skills',
   },
   {
     id: 'codex',
     name: 'Codex',
     configDir: '.codex',
     skillsDir: 'skills',
+    localConfigDir: '.codex',
+    localSkillsDir: 'skills',
   },
   {
     id: 'gemini',
     name: 'Gemini CLI',
     configDir: '.gemini',
     skillsDir: 'skills',
+    localConfigDir: '.gemini',
+    localSkillsDir: 'skills',
   },
   {
     id: 'qwen',
     name: 'Qwen Code',
     configDir: '.qwen',
     skillsDir: 'skills',
+    localConfigDir: '.qwen',
+    localSkillsDir: 'skills',
   },
   {
     id: 'opencode',
     name: 'OpenCode',
     configDir: '.config/opencode',
     skillsDir: 'skills',
+    localConfigDir: '.opencode',
+    localSkillsDir: 'skills',
   },
   {
     id: 'openclaw',
     name: 'OpenClaw',
     configDir: '.openclaw',
     skillsDir: 'skills',
+    localConfigDir: '.',
+    localSkillsDir: 'skills',
   },
   {
     id: 'agents',
     name: 'Shared Agents',
     configDir: '.agents',
     skillsDir: 'skills',
+    localConfigDir: '.agents',
+    localSkillsDir: 'skills',
   },
 ];
 
 /**
- * Detect which coding agents are installed on the system
+ * Detect which coding agents are installed on the system (global)
  * @returns {Array} List of detected agents with their paths
  */
 export function detectAgents() {
@@ -81,6 +102,49 @@ export function detectAgents() {
   return detected;
 }
 
+/**
+ * Build local agent targets for a given project directory
+ * @param {Array} agents - List of agent configs (from SUPPORTED_AGENTS or detectAgents)
+ * @param {string} projectDir - Absolute path to the project root
+ * @returns {Array} List of agents with local paths set
+ */
+export function buildLocalAgentTargets(agents, projectDir) {
+  return agents.map(agent => ({
+    ...agent,
+    path: `./${agent.localConfigDir || agent.configDir}`,
+    fullPath: join(projectDir, agent.localConfigDir || agent.configDir),
+    skillsPath: join(projectDir, agent.localConfigDir || agent.configDir, agent.localSkillsDir || agent.skillsDir),
+    local: true,
+  }));
+}
+
+/**
+ * Detect which coding agents have local skills in a project directory
+ * @param {string} projectDir - Absolute path to the project root
+ * @returns {Array} List of agents with local skills directories
+ */
+export function detectLocalAgents(projectDir) {
+  const detected = [];
+
+  for (const agent of SUPPORTED_AGENTS) {
+    const localConfigDir = agent.localConfigDir || agent.configDir;
+    const localSkillsDir = agent.localSkillsDir || agent.skillsDir;
+    const skillsPath = join(projectDir, localConfigDir, localSkillsDir);
+
+    if (existsSync(skillsPath)) {
+      detected.push({
+        ...agent,
+        path: `./${localConfigDir}`,
+        fullPath: join(projectDir, localConfigDir),
+        skillsPath,
+        local: true,
+      });
+    }
+  }
+
+  return detected;
+}
+
 /**
  * Get agent by ID
  * @param {string} id Agent ID

package/src/ascii.js

@@ -100,6 +100,43 @@ export function showSuccess(skillCount, agents) {
   console.log();
 }
 
+/**
+ * Local installation success screen
+ */
+export function showLocalSuccess(skillCount, agents, projectDir) {
+  console.clear();
+  console.log();
+  console.log();
+  console.log(chalk.green.bold('                          ✓  Local Installation Complete'));
+  console.log();
+  console.log();
+  console.log(`              Installed ${chalk.white(skillCount)} skills to ${chalk.white(agents.length)} agent${agents.length !== 1 ? 's' : ''}`);
+  console.log(`              Project: ${chalk.white(projectDir)}`);
+  console.log();
+
+  console.log(chalk.dim('              Skills copied to:'));
+  for (const agent of agents) {
+    console.log(chalk.dim(`                → ${agent.skillsPath.replace(projectDir, '.')}`));
+  }
+  console.log();
+  console.log(chalk.dim('              Skills are copied (not symlinked) and can be'));
+  console.log(chalk.dim('              committed to version control for team sharing.'));
+  console.log();
+  console.log(chalk.dim('    ────────────────────────────────────────────────────────────'));
+  console.log();
+  console.log(chalk.white('              Commands:'));
+  console.log();
+  console.log(`              ${chalk.dim('$')} ${chalk.cyan('npx @orchestra-research/ai-research-skills list --local')}`);
+  console.log(`              ${chalk.dim('$')} ${chalk.cyan('npx @orchestra-research/ai-research-skills update --local')}`);
+  console.log(`              ${chalk.dim('$')} ${chalk.cyan('npx @orchestra-research/ai-research-skills uninstall --local')}`);
+  console.log();
+  console.log(chalk.dim('    ────────────────────────────────────────────────────────────'));
+  console.log();
+  console.log(chalk.dim('              Tip: Add .orchestra-skills.json to your repo'));
+  console.log(chalk.dim('              so teammates can run `update --local` to sync.'));
+  console.log();
+}
+
 /**
  * No agents found screen
  */

package/src/index.js

@@ -1,15 +1,17 @@
 import ora from 'ora';
 import chalk from 'chalk';
 
-import { detectAgents } from './agents.js';
-import { showWelcome, showAgentsDetected, showSuccess, showNoAgents, showMenuHeader } from './ascii.js';
+import { detectAgents, buildLocalAgentTargets, detectLocalAgents, SUPPORTED_AGENTS } from './agents.js';
+import { showWelcome, showAgentsDetected, showSuccess, showLocalSuccess, showNoAgents, showMenuHeader } from './ascii.js';
 import {
   askInstallChoice,
   askCategories,
   askIndividualSkills,
   askConfirmation,
+  askLocalConfirmation,
   askMainMenuAction,
   askSelectAgents,
+  askSelectLocalAgents,
   askAfterAction,
   askUninstallChoice,
   askSelectSkillsToUninstall,
@@ -20,7 +22,25 @@ import {
   QUICK_START_SKILLS,
   getTotalSkillCount,
 } from './prompts.js';
-import { installSkills, installSpecificSkills, listInstalledSkills, getAllCategoryIds, updateInstalledSkills, uninstallAllSkills, uninstallSpecificSkills, getInstalledSkillPaths, getInstalledSkillsForSelection } from './installer.js';
+import {
+  installSkills,
+  installSpecificSkills,
+  installSkillsLocal,
+  installSpecificSkillsLocal,
+  listInstalledSkills,
+  listLocalSkills,
+  getAllCategoryIds,
+  updateInstalledSkills,
+  updateLocalSkills,
+  uninstallAllSkills,
+  uninstallSpecificSkills,
+  uninstallLocalSkills,
+  uninstallAllLocalSkills,
+  getInstalledSkillPaths,
+  getInstalledSkillsForSelection,
+  getLocalSkillPaths,
+  getLocalSkillsForSelection,
+} from './installer.js';
 
 /**
  * Sleep utility
@@ -166,6 +186,103 @@ async function interactiveFlow() {
       continue step2_menu;
     }
 
+    if (menuAction === 'install-local') {
+      // LOCAL INSTALLATION FLOW
+      const projectDir = process.cwd();
+      const localAgents = buildLocalAgentTargets(
+        agents.length > 0 ? agents : SUPPORTED_AGENTS.slice(0, 1).map(a => ({ ...a })),
+        projectDir
+      );
+
+      // Choose what to install locally
+      step_local_choice:
+      while (true) {
+        showMenuHeader();
+        console.log(chalk.cyan(`    Local install to: ${projectDir}`));
+        console.log();
+        const choice = await askInstallChoice();
+
+        if (choice === 'back') {
+          continue step2_menu;
+        }
+
+        let categories = [];
+        let selectedSkills = [];
+        let skillCount = 0;
+        let installType = choice;
+
+        if (choice === 'everything') {
+          categories = getAllCategoryIds();
+          skillCount = getTotalSkillCount();
+        } else if (choice === 'quickstart') {
+          categories = [...new Set(QUICK_START_SKILLS.map(s => s.split('/')[0]))];
+          skillCount = QUICK_START_SKILLS.length;
+        } else if (choice === 'categories') {
+          step_local_categories:
+          while (true) {
+            showMenuHeader();
+            const result = await askCategories();
+            if (result.action === 'back') continue step_local_choice;
+            if (result.action === 'retry') continue step_local_categories;
+            categories = result.categories;
+            skillCount = CATEGORIES
+              .filter(c => categories.includes(c.id))
+              .reduce((sum, c) => sum + c.skills, 0);
+            break;
+          }
+        } else if (choice === 'individual') {
+          step_local_individual:
+          while (true) {
+            showMenuHeader();
+            const result = await askIndividualSkills();
+            if (result.action === 'back') continue step_local_choice;
+            if (result.action === 'retry') continue step_local_individual;
+            selectedSkills = result.skills;
+            skillCount = selectedSkills.length;
+            break;
+          }
+        }
+
+        // Select local agents
+        let targetAgents = localAgents;
+        step_local_agents:
+        while (true) {
+          showMenuHeader();
+          const agentResult = await askSelectLocalAgents(localAgents);
+          if (agentResult.action === 'back') continue step_local_choice;
+          if (agentResult.action === 'retry') continue step_local_agents;
+          targetAgents = agentResult.agents;
+
+          // Confirmation
+          showMenuHeader();
+          const confirmAction = await askLocalConfirmation(skillCount, targetAgents, projectDir, categories, selectedSkills, installType);
+          if (confirmAction === 'exit') {
+            console.log(chalk.dim('              Goodbye!'));
+            console.log();
+            return;
+          }
+          if (confirmAction === 'back') continue step_local_agents;
+          break;
+        }
+
+        // Install locally
+        console.log();
+        console.log(chalk.cyan('    Installing locally...'));
+        console.log();
+
+        let installedCount;
+        if (selectedSkills.length > 0) {
+          installedCount = await installSpecificSkillsLocal(selectedSkills, targetAgents, projectDir);
+        } else {
+          installedCount = await installSkillsLocal(categories, targetAgents, projectDir);
+        }
+
+        await sleep(500);
+        showLocalSuccess(installedCount, targetAgents, projectDir);
+        return;
+      }
+    }
+
     // STEP 3: Choose what to install (menuAction === 'install')
     step3_choice:
     while (true) {
@@ -286,35 +403,77 @@ async function interactiveFlow() {
  * Direct command mode (for power users)
  */
 async function commandMode(options) {
+  const projectDir = process.cwd();
+  const isLocal = options.local;
+
   if (options.command === 'list') {
-    listInstalledSkills();
+    if (isLocal) {
+      listLocalSkills(projectDir);
+    } else {
+      listInstalledSkills();
+    }
     return;
   }
 
   if (options.command === 'update') {
-    const agents = detectAgents();
-    if (agents.length === 0) {
-      console.log(chalk.yellow('No agents detected.'));
-      return;
-    }
-    const installedPaths = getInstalledSkillPaths();
-    if (installedPaths.length === 0) {
-      console.log(chalk.yellow('No skills installed to update.'));
-      return;
+    if (isLocal) {
+      const agents = detectAgents();
+      const localAgents = buildLocalAgentTargets(
+        agents.length > 0 ? agents : [SUPPORTED_AGENTS[0]],
+        projectDir
+      );
+      const localPaths = getLocalSkillPaths(projectDir);
+      if (localPaths.length === 0) {
+        console.log(chalk.yellow('No local skills installed to update.'));
+        return;
+      }
+      console.log(chalk.cyan(`Updating ${localPaths.length} local skills...`));
+      await updateLocalSkills(localAgents, projectDir);
+      console.log(chalk.green('✓ Local skills updated!'));
+    } else {
+      const agents = detectAgents();
+      if (agents.length === 0) {
+        console.log(chalk.yellow('No agents detected.'));
+        return;
+      }
+      const installedPaths = getInstalledSkillPaths();
+      if (installedPaths.length === 0) {
+        console.log(chalk.yellow('No skills installed to update.'));
+        return;
+      }
+      console.log(chalk.cyan(`Updating ${installedPaths.length} installed skills...`));
+      await updateInstalledSkills(agents);
+      console.log(chalk.green('✓ Skills updated!'));
     }
-    console.log(chalk.cyan(`Updating ${installedPaths.length} installed skills...`));
-    await updateInstalledSkills(agents);
-    console.log(chalk.green('✓ Skills updated!'));
     return;
   }
 
-  if (options.command === 'install' || options.all || options.category || options.skill) {
-    const agents = detectAgents();
-    if (agents.length === 0) {
-      console.log(chalk.yellow('No agents detected.'));
-      return;
+  if (options.command === 'uninstall') {
+    if (isLocal) {
+      const agents = detectAgents();
+      const localAgents = buildLocalAgentTargets(
+        agents.length > 0 ? agents : [SUPPORTED_AGENTS[0]],
+        projectDir
+      );
+      const detectedLocal = detectLocalAgents(projectDir);
+      const targets = detectedLocal.length > 0 ? detectedLocal : localAgents;
+      console.log(chalk.cyan('Uninstalling local skills...'));
+      await uninstallAllLocalSkills(targets, projectDir);
+      console.log(chalk.green('✓ Local skills removed!'));
+    } else {
+      const agents = detectAgents();
+      if (agents.length === 0) {
+        console.log(chalk.yellow('No agents detected.'));
+        return;
+      }
+      console.log(chalk.cyan('Uninstalling all skills...'));
+      await uninstallAllSkills(agents);
+      console.log(chalk.green('✓ Skills removed!'));
     }
+    return;
+  }
 
+  if (options.command === 'install' || options.all || options.category || options.skill) {
     let categories;
     if (options.all) {
       categories = getAllCategoryIds();
@@ -334,9 +493,25 @@ async function commandMode(options) {
       categories = getAllCategoryIds();
     }
 
-    console.log(chalk.cyan('Installing skills...'));
-    await installSkills(categories, agents);
-    console.log(chalk.green('✓ Done!'));
+    if (isLocal) {
+      const agents = detectAgents();
+      const localAgents = buildLocalAgentTargets(
+        agents.length > 0 ? agents : [SUPPORTED_AGENTS[0]],
+        projectDir
+      );
+      console.log(chalk.cyan(`Installing skills locally to ${projectDir}...`));
+      await installSkillsLocal(categories, localAgents, projectDir);
+      console.log(chalk.green('✓ Done! Skills installed to project directory.'));
+    } else {
+      const agents = detectAgents();
+      if (agents.length === 0) {
+        console.log(chalk.yellow('No agents detected.'));
+        return;
+      }
+      console.log(chalk.cyan('Installing skills...'));
+      await installSkills(categories, agents);
+      console.log(chalk.green('✓ Done!'));
+    }
     return;
   }
 }

package/src/installer.js

@@ -8,6 +8,7 @@ import ora from 'ora';
 const REPO_URL = 'https://github.com/Orchestra-Research/AI-research-SKILLs';
 const CANONICAL_DIR = join(homedir(), '.orchestra', 'skills');
 const LOCK_FILE = join(homedir(), '.orchestra', '.lock.json');
+const LOCAL_LOCK_FILENAME = '.orchestra-skills.json';
 
 /**
  * Copy directory contents (cross-platform replacement for `cp -r source/* dest/`)
@@ -621,3 +622,409 @@ export function getInstalledSkillsForSelection() {
     }
   });
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Local (project-level) installation
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Get the local lock file path for a project
+ */
+function getLocalLockPath(projectDir) {
+  return join(projectDir, LOCAL_LOCK_FILENAME);
+}
+
+/**
+ * Read local lock file
+ */
+function readLocalLock(projectDir) {
+  const lockPath = getLocalLockPath(projectDir);
+  if (existsSync(lockPath)) {
+    try {
+      return JSON.parse(readFileSync(lockPath, 'utf8'));
+    } catch {
+      return { version: null, installedAt: null, skills: [], agents: [] };
+    }
+  }
+  return { version: null, installedAt: null, skills: [], agents: [] };
+}
+
+/**
+ * Write local lock file
+ */
+function writeLocalLock(projectDir, data) {
+  writeFileSync(getLocalLockPath(projectDir), JSON.stringify(data, null, 2));
+}
+
+/**
+ * Copy skills directly into agent local directories (no symlinks)
+ * @param {Object} agent - Agent with skillsPath set to local project path
+ * @param {Array} skills - Skills list from download
+ * @param {string} tempDir - Temp clone directory
+ */
+function copySkillsToLocal(agent, skills, tempDir) {
+  const agentSkillsPath = agent.skillsPath;
+
+  if (!existsSync(agentSkillsPath)) {
+    mkdirSync(agentSkillsPath, { recursive: true });
+  }
+
+  let copiedCount = 0;
+
+  for (const skill of skills) {
+    const sourcePath = skill.standalone
+      ? join(tempDir, skill.category)
+      : join(tempDir, skill.category, skill.skill);
+
+    if (!existsSync(sourcePath)) continue;
+
+    const destName = skill.standalone ? skill.category : skill.skill;
+    const destPath = join(agentSkillsPath, destName);
+
+    // Remove existing if present
+    if (existsSync(destPath)) {
+      rmSync(destPath, { recursive: true, force: true });
+    }
+
+    mkdirSync(destPath, { recursive: true });
+    copyDirectoryContents(sourcePath, destPath);
+    copiedCount++;
+  }
+
+  return copiedCount;
+}
+
+/**
+ * Download and install skills locally to agent project directories
+ */
+export async function installSkillsLocal(categories, agents, projectDir) {
+  const spinner = ora('Downloading from GitHub...').start();
+
+  const tempDir = join(homedir(), '.orchestra', '.temp-clone');
+
+  try {
+    if (existsSync(tempDir)) {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+
+    spinner.text = 'Cloning repository...';
+    execSync(`git clone --depth 1 ${REPO_URL}.git ${tempDir}`, {
+      stdio: 'pipe',
+    });
+
+    // Build skills list from categories
+    const skills = [];
+    for (const categoryId of categories) {
+      const categoryPath = join(tempDir, categoryId);
+      if (!existsSync(categoryPath)) continue;
+
+      const standaloneSkillPath = join(categoryPath, 'SKILL.md');
+      if (existsSync(standaloneSkillPath)) {
+        skills.push({ category: categoryId, skill: categoryId, standalone: true });
+      } else {
+        const entries = readdirSync(categoryPath, { withFileTypes: true });
+        for (const entry of entries) {
+          if (entry.isDirectory()) {
+            const skillPath = join(categoryPath, entry.name, 'SKILL.md');
+            if (existsSync(skillPath)) {
+              skills.push({ category: categoryId, skill: entry.name, standalone: false });
+            }
+          }
+        }
+      }
+    }
+
+    spinner.succeed(`Found ${skills.length} skills`);
+
+    // Copy to each agent's local directory
+    spinner.start('Installing to project...');
+
+    for (const agent of agents) {
+      const count = copySkillsToLocal(agent, skills, tempDir);
+      console.log(`    ${chalk.green('✓')} ${agent.name.padEnd(14)} ${chalk.dim('→')} ${agent.skillsPath.replace(projectDir, '.').padEnd(30)} ${chalk.green(count + ' skills')}`);
+    }
+
+    spinner.stop();
+
+    // Cleanup
+    rmSync(tempDir, { recursive: true, force: true });
+
+    // Update local lock file
+    const lock = readLocalLock(projectDir);
+    lock.version = '1.0.0';
+    lock.installedAt = new Date().toISOString();
+    lock.skills = [...(lock.skills || []).filter(s => {
+      const existing = `${s.category}/${s.skill}`;
+      return !skills.some(ns => `${ns.category}/${ns.skill}` === existing);
+    }), ...skills];
+    lock.agents = agents.map(a => a.id);
+    writeLocalLock(projectDir, lock);
+
+    return skills.length;
+  } catch (error) {
+    if (existsSync(tempDir)) {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+    spinner.fail('Installation failed');
+    throw error;
+  }
+}
+
+/**
+ * Download and install specific skills locally
+ */
+export async function installSpecificSkillsLocal(skillPaths, agents, projectDir) {
+  const spinner = ora('Downloading from GitHub...').start();
+
+  const tempDir = join(homedir(), '.orchestra', '.temp-clone');
+
+  try {
+    if (existsSync(tempDir)) {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+
+    spinner.text = 'Cloning repository...';
+    execSync(`git clone --depth 1 ${REPO_URL}.git ${tempDir}`, {
+      stdio: 'pipe',
+    });
+
+    const skills = [];
+    for (const skillPath of skillPaths) {
+      const parts = skillPath.split('/');
+      const categoryId = parts[0];
+      const skillName = parts[1] || null;
+
+      if (skillName) {
+        const sourcePath = join(tempDir, categoryId, skillName);
+        if (existsSync(sourcePath)) {
+          skills.push({ category: categoryId, skill: skillName, standalone: false });
+        }
+      } else {
+        const sourcePath = join(tempDir, categoryId);
+        if (existsSync(sourcePath)) {
+          skills.push({ category: categoryId, skill: categoryId, standalone: true });
+        }
+      }
+    }
+
+    spinner.succeed(`Found ${skills.length} skills`);
+
+    // Copy to each agent's local directory
+    spinner.start('Installing to project...');
+
+    for (const agent of agents) {
+      const count = copySkillsToLocal(agent, skills, tempDir);
+      console.log(`    ${chalk.green('✓')} ${agent.name.padEnd(14)} ${chalk.dim('→')} ${agent.skillsPath.replace(projectDir, '.').padEnd(30)} ${chalk.green(count + ' skills')}`);
+    }
+
+    spinner.stop();
+
+    // Cleanup
+    rmSync(tempDir, { recursive: true, force: true });
+
+    // Update local lock file
+    const lock = readLocalLock(projectDir);
+    lock.version = '1.0.0';
+    lock.installedAt = new Date().toISOString();
+    lock.skills = [...(lock.skills || []).filter(s => {
+      const existing = `${s.category}/${s.skill}`;
+      return !skills.some(ns => `${ns.category}/${ns.skill}` === existing);
+    }), ...skills];
+    lock.agents = agents.map(a => a.id);
+    writeLocalLock(projectDir, lock);
+
+    return skills.length;
+  } catch (error) {
+    if (existsSync(tempDir)) {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+    spinner.fail('Installation failed');
+    throw error;
+  }
+}
+
+/**
+ * List locally installed skills for a project
+ */
+export function listLocalSkills(projectDir) {
+  const lock = readLocalLock(projectDir);
+
+  if (!lock.skills || lock.skills.length === 0) {
+    console.log(chalk.yellow('    No skills installed locally in this project.'));
+    console.log();
+    console.log(`    Run ${chalk.cyan('npx @orchestra-research/ai-research-skills install --local')} to install skills.`);
+    return;
+  }
+
+  const byCategory = {};
+  let totalSkills = 0;
+
+  for (const skill of lock.skills) {
+    const category = skill.category;
+    if (!byCategory[category]) {
+      byCategory[category] = [];
+    }
+    if (skill.standalone) {
+      byCategory[category].push(category);
+    } else {
+      byCategory[category].push(skill.skill);
+    }
+    totalSkills++;
+  }
+
+  console.log(chalk.white.bold(`    Local Skills (${totalSkills})`));
+  console.log(chalk.dim(`    Project: ${projectDir}`));
+  console.log();
+
+  for (const [category, skills] of Object.entries(byCategory)) {
+    console.log(chalk.cyan(`    ${category}`));
+    for (const skill of skills) {
+      if (skill === category) {
+        console.log(`      ${chalk.dim('●')} ${chalk.white('(standalone)')}`);
+      } else {
+        console.log(`      ${chalk.dim('●')} ${skill}`);
+      }
+    }
+    console.log();
+  }
+
+  // Show agent directories
+  if (lock.agents && lock.agents.length > 0) {
+    console.log(chalk.dim(`    Agents: ${lock.agents.join(', ')}`));
+  }
+}
+
+/**
+ * Get locally installed skill paths for a project
+ */
+export function getLocalSkillPaths(projectDir) {
+  const lock = readLocalLock(projectDir);
+  if (!lock.skills || lock.skills.length === 0) {
+    return [];
+  }
+
+  return lock.skills.map(s => {
+    return s.standalone ? s.category : `${s.category}/${s.skill}`;
+  });
+}
+
+/**
+ * Get locally installed skills with display info for selection
+ */
+export function getLocalSkillsForSelection(projectDir) {
+  const lock = readLocalLock(projectDir);
+  if (!lock.skills || lock.skills.length === 0) {
+    return [];
+  }
+
+  return lock.skills.map(s => {
+    if (s.standalone) {
+      return { path: s.category, name: s.category, category: 'Standalone', standalone: true };
+    } else {
+      return { path: `${s.category}/${s.skill}`, name: s.skill, category: s.category, standalone: false };
+    }
+  });
+}
+
+/**
+ * Update locally installed skills
+ */
+export async function updateLocalSkills(agents, projectDir) {
+  const installedPaths = getLocalSkillPaths(projectDir);
+
+  if (installedPaths.length === 0) {
+    console.log(chalk.yellow('    No local skills installed to update.'));
+    return 0;
+  }
+
+  // Re-install the same skills
+  return await installSpecificSkillsLocal(installedPaths, agents, projectDir);
+}
+
+/**
+ * Uninstall specific local skills
+ */
+export async function uninstallLocalSkills(skillPaths, agents, projectDir) {
+  const spinner = ora('Removing local skills...').start();
+
+  try {
+    for (const skillPath of skillPaths) {
+      const parts = skillPath.split('/');
+      const categoryId = parts[0];
+      const skillName = parts[1] || null;
+      const linkName = skillName || categoryId;
+
+      // Remove from each agent's local directory
+      for (const agent of agents) {
+        const skillDir = join(agent.skillsPath, linkName);
+        if (existsSync(skillDir)) {
+          rmSync(skillDir, { recursive: true, force: true });
+        }
+      }
+
+      spinner.text = `Removed ${linkName}`;
+    }
+
+    spinner.succeed(`Removed ${skillPaths.length} skill${skillPaths.length !== 1 ? 's' : ''}`);
+
+    // Update local lock file
+    const lock = readLocalLock(projectDir);
+    if (lock.skills) {
+      lock.skills = lock.skills.filter(s => {
+        const path = s.standalone ? s.category : `${s.category}/${s.skill}`;
+        return !skillPaths.includes(path);
+      });
+      writeLocalLock(projectDir, lock);
+    }
+
+    return skillPaths.length;
+  } catch (error) {
+    spinner.fail('Uninstall failed');
+    throw error;
+  }
+}
+
+/**
+ * Uninstall all local skills
+ */
+export async function uninstallAllLocalSkills(agents, projectDir) {
+  const lock = readLocalLock(projectDir);
+  const trackedSkills = lock.skills || [];
+
+  if (trackedSkills.length === 0) {
+    console.log(chalk.yellow('    No tracked local skills to remove.'));
+    return false;
+  }
+
+  const spinner = ora('Removing all local skills...').start();
+
+  try {
+    // Build set of directory names to remove (only tracked skills)
+    const skillNames = trackedSkills.map(s => s.standalone ? s.category : s.skill);
+
+    for (const agent of agents) {
+      if (existsSync(agent.skillsPath)) {
+        for (const name of skillNames) {
+          const skillDir = join(agent.skillsPath, name);
+          if (existsSync(skillDir)) {
+            rmSync(skillDir, { recursive: true, force: true });
+          }
+        }
+      }
+      console.log(`    ${chalk.green('✓')} Removed skills from ${agent.name} (${agent.skillsPath.replace(projectDir, '.')})`);
+    }
+
+    // Remove local lock file
+    const lockPath = getLocalLockPath(projectDir);
+    if (existsSync(lockPath)) {
+      rmSync(lockPath, { force: true });
+      console.log(`    ${chalk.green('✓')} Removed ${LOCAL_LOCK_FILENAME}`);
+    }
+
+    spinner.stop();
+    return true;
+  } catch (error) {
+    spinner.fail('Uninstall failed');
+    throw error;
+  }
+}

package/src/prompts.js

@@ -94,8 +94,10 @@ export function getTotalSkillCount() {
 /**
  * Ask main menu action after agent detection
  */
-export async function askMainMenuAction() {
+export async function askMainMenuAction(projectDir) {
   console.log();
+  const cwd = projectDir || process.cwd();
+  const shortCwd = cwd.split('/').slice(-2).join('/');
   const { action } = await inquirer.prompt([
     {
       type: 'list',
@@ -103,9 +105,10 @@ export async function askMainMenuAction() {
       message: ' ',
       choices: [
         { name: 'Install new skills', value: 'install' },
+        { name: `Install to project (local) ${chalk.dim('→ ./' + shortCwd)}`, value: 'install-local' },
         { name: 'View installed skills', value: 'view' },
         { name: 'Update installed skills', value: 'update' },
-        { name: 'Uninstall all skills', value: 'uninstall' },
+        { name: 'Uninstall skills', value: 'uninstall' },
         new inquirer.Separator(' '),
         { name: chalk.dim('Exit'), value: 'exit' },
       ],
@@ -115,6 +118,141 @@ export async function askMainMenuAction() {
   return action;
 }
 
+/**
+ * Ask which agents to install to locally
+ */
+export async function askSelectLocalAgents(agents) {
+  console.log();
+  console.log(chalk.dim('    Install to which agents in this project?'));
+  console.log();
+
+  const { selection } = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'selection',
+      message: ' ',
+      choices: [
+        { name: `All detected agents (${agents.length})`, value: 'all' },
+        { name: 'Select specific agents', value: 'select' },
+        new inquirer.Separator(' '),
+        { name: chalk.dim('← Back'), value: 'back' },
+      ],
+      prefix: '   ',
+    },
+  ]);
+
+  if (selection === 'back') {
+    return { agents: [], action: 'back' };
+  }
+
+  if (selection === 'all') {
+    return { agents, action: 'confirm' };
+  }
+
+  // Select specific agents
+  console.log();
+  const { selectedAgents } = await inquirer.prompt([
+    {
+      type: 'checkbox',
+      name: 'selectedAgents',
+      message: ' ',
+      choices: agents.map(agent => ({
+        name: `${agent.name.padEnd(14)} ${chalk.dim(agent.path)}`,
+        value: agent,
+        checked: false,
+      })),
+      prefix: '   ',
+    },
+  ]);
+
+  if (selectedAgents.length === 0) {
+    console.log();
+    const { action } = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'action',
+        message: chalk.yellow('No agents selected'),
+        choices: [
+          { name: 'Try again', value: 'retry' },
+          { name: chalk.dim('← Back'), value: 'back' },
+        ],
+        prefix: '   ',
+      },
+    ]);
+    return { agents: [], action };
+  }
+
+  return { agents: selectedAgents, action: 'confirm' };
+}
+
+/**
+ * Ask for local install confirmation
+ */
+export async function askLocalConfirmation(skillCount, agents, projectDir, categories, selectedSkills, installType) {
+  console.log();
+  console.log(chalk.white('    Local Installation Summary'));
+  console.log(chalk.dim('    ─────────────────────────────────────────────────────'));
+  console.log();
+
+  console.log(`    ${chalk.white('Skills:')}     ${skillCount} skills`);
+  console.log(`    ${chalk.white('Project:')}    ${projectDir}`);
+  console.log(`    ${chalk.white('Agents:')}     ${agents.map(a => a.name).join(', ')}`);
+  console.log();
+
+  // Destinations
+  console.log(chalk.dim('    Destinations:'));
+  for (const agent of agents) {
+    console.log(chalk.dim(`    • ${agent.skillsPath.replace(projectDir, '.')}`));
+  }
+  console.log();
+
+  // Description based on install type
+  if (installType === 'everything') {
+    console.log(chalk.dim('    All 20 categories'));
+  } else if (installType === 'quickstart') {
+    console.log(chalk.dim('    Essential skills for AI research'));
+  } else if (categories && categories.length > 0) {
+    const catNames = CATEGORIES
+      .filter(c => categories.includes(c.id))
+      .map(c => c.name);
+    console.log(chalk.dim('    Selected categories:'));
+    catNames.forEach(name => console.log(chalk.dim(`    • ${name}`)));
+  } else if (selectedSkills && selectedSkills.length > 0) {
+    console.log(chalk.dim('    Selected skills:'));
+    const skillNames = INDIVIDUAL_SKILLS
+      .filter(s => selectedSkills.includes(s.id))
+      .map(s => s.name)
+      .slice(0, 8);
+    skillNames.forEach(name => console.log(chalk.dim(`    • ${name}`)));
+    if (selectedSkills.length > 8) {
+      console.log(chalk.dim(`    • ...and ${selectedSkills.length - 8} more`));
+    }
+  }
+
+  console.log();
+  console.log(chalk.dim('    ─────────────────────────────────────────────────────'));
+  console.log();
+  console.log(chalk.dim('    Skills will be copied (not symlinked) so you can'));
+  console.log(chalk.dim('    commit them to version control.'));
+  console.log();
+
+  const { action } = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'action',
+      message: ' ',
+      choices: [
+        { name: chalk.green('Install locally'), value: 'confirm' },
+        { name: chalk.dim('← Back'), value: 'back' },
+        { name: chalk.dim('Exit'), value: 'exit' },
+      ],
+      prefix: '   ',
+    },
+  ]);
+
+  return action;
+}
+
 /**
  * Ask what to uninstall
  */
@@ -500,6 +638,7 @@ export function parseArgs(args) {
   const options = {
     command: null,
     all: false,
+    local: false,
     category: null,
     skill: null,
     agent: null,
@@ -514,8 +653,12 @@ export function parseArgs(args) {
       options.command = 'list';
     } else if (arg === 'update') {
       options.command = 'update';
+    } else if (arg === 'uninstall') {
+      options.command = 'uninstall';
     } else if (arg === '--all' || arg === '-a') {
       options.all = true;
+    } else if (arg === '--local' || arg === '-l') {
+      options.local = true;
     } else if (arg === '--agent' && args[i + 1]) {
       options.agent = args[++i];
     } else if (arg === '--category' && args[i + 1]) {