@orchestra-research/ai-research-skills 1.0.0

package/README.md

@@ -0,0 +1,97 @@
+# @orchestra-research/ai-research-skills
+
+Install AI research engineering skills to your coding agents (Claude Code, Cursor, Gemini CLI, and more).
+
+```bash
+npx @orchestra-research/ai-research-skills
+```
+
+## Features
+
+- **82 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
+- **Works with 7 agents**: Claude Code, Cursor, Codex, Windsurf, Gemini CLI, Kilo Code, Qwen Code
+
+## Quick Start
+
+Run the interactive installer:
+
+```bash
+npx @orchestra-research/ai-research-skills
+```
+
+This will:
+1. Detect your installed coding agents
+2. Let you choose what to install (everything, categories, or quick start bundle)
+3. Download skills from GitHub
+4. Create symlinks to each agent's skills directory
+
+## Commands
+
+```bash
+# Interactive mode (recommended)
+npx @orchestra-research/ai-research-skills
+
+# Install everything
+npx @orchestra-research/ai-research-skills install --all
+
+# Install a specific category
+npx @orchestra-research/ai-research-skills install post-training
+
+# List installed skills
+npx @orchestra-research/ai-research-skills list
+
+# Update all skills
+npx @orchestra-research/ai-research-skills update
+```
+
+## Categories
+
+| Category | Skills | Description |
+|----------|--------|-------------|
+| Model Architecture | 6 | LitGPT, Mamba, TorchTitan, Megatron... |
+| Post-Training | 8 | GRPO, verl, slime, miles, torchforge... |
+| Fine-Tuning | 5 | Axolotl, Unsloth, PEFT, Torchtune... |
+| Distributed Training | 6 | DeepSpeed, FSDP, Megatron... |
+| Inference Serving | 4 | vLLM, TensorRT-LLM, SGLang... |
+| Optimization | 6 | Flash Attention, GPTQ, AWQ... |
+| And 14 more... | | |
+
+## How It Works
+
+1. **Canonical Storage**: Skills are stored once at `~/.agents/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
+├── 06-post-training/
+│   ├── verl/
+│   └── grpo-rl-training/
+└── ...
+
+~/.claude/skills/          # Symlinks for Claude Code
+├── verl → ~/.agents/skills/.../verl
+└── grpo-rl-training → ...
+
+~/.cursor/skills/          # Symlinks for Cursor
+└── (same links)
+```
+
+## Supported Agents
+
+| Agent | Config Directory |
+|-------|-----------------|
+| Claude Code | `~/.claude` |
+| Cursor | `~/.cursor` |
+| Codex (OpenAI) | `~/.codex` |
+| Windsurf | `~/.windsurf` |
+| Gemini CLI | `~/.gemini` |
+| Kilo Code | `~/.kilocode` |
+| Qwen Code | `~/.qwen` |
+
+## License
+
+MIT - Orchestra Research

package/bin/cli.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { main } from '../src/index.js';
+
+main().catch((error) => {
+  console.error('Error:', error.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@orchestra-research/ai-research-skills",
+  "version": "1.0.0",
+  "description": "Install AI research engineering skills to your coding agents (Claude Code, Cursor, Gemini CLI, and more)",
+  "main": "src/index.js",
+  "bin": {
+    "ai-research-skills": "./bin/cli.js"
+  },
+  "type": "module",
+  "scripts": {
+    "start": "node bin/cli.js",
+    "test": "node --test"
+  },
+  "keywords": [
+    "ai",
+    "research",
+    "skills",
+    "claude",
+    "cursor",
+    "gemini",
+    "codex",
+    "windsurf",
+    "llm",
+    "machine-learning",
+    "deep-learning",
+    "cli"
+  ],
+  "author": "Orchestra Research",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/orchestra-research/ai-research-skills.git"
+  },
+  "homepage": "https://github.com/orchestra-research/ai-research-skills",
+  "bugs": {
+    "url": "https://github.com/orchestra-research/ai-research-skills/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "inquirer": "^9.2.12",
+    "ora": "^8.0.1"
+  }
+}

package/src/agents.js

@@ -0,0 +1,81 @@
+import { existsSync } from 'fs';
+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
+ */
+export const SUPPORTED_AGENTS = [
+  {
+    id: 'claude',
+    name: 'Claude Code',
+    configDir: '.claude',
+    skillsDir: 'skills',
+  },
+  {
+    id: 'cursor',
+    name: 'Cursor',
+    configDir: '.cursor',
+    skillsDir: 'skills',
+  },
+  {
+    id: 'codex',
+    name: 'Codex',
+    configDir: '.codex',
+    skillsDir: 'skills',
+  },
+  {
+    id: 'gemini',
+    name: 'Gemini CLI',
+    configDir: '.gemini',
+    skillsDir: 'skills',
+  },
+  {
+    id: 'qwen',
+    name: 'Qwen Code',
+    configDir: '.qwen',
+    skillsDir: 'skills',
+  },
+];
+
+/**
+ * Detect which coding agents are installed on the system
+ * @returns {Array} List of detected agents with their paths
+ */
+export function detectAgents() {
+  const home = homedir();
+  const detected = [];
+
+  for (const agent of SUPPORTED_AGENTS) {
+    const configPath = join(home, agent.configDir);
+
+    if (existsSync(configPath)) {
+      detected.push({
+        ...agent,
+        path: `~/${agent.configDir}`,
+        fullPath: configPath,
+        skillsPath: join(configPath, agent.skillsDir),
+      });
+    }
+  }
+
+  return detected;
+}
+
+/**
+ * Get agent by ID
+ * @param {string} id Agent ID
+ * @returns {Object|null} Agent configuration or null
+ */
+export function getAgentById(id) {
+  return SUPPORTED_AGENTS.find(agent => agent.id === id) || null;
+}
+
+/**
+ * Get all supported agent IDs
+ * @returns {Array<string>} List of agent IDs
+ */
+export function getSupportedAgentIds() {
+  return SUPPORTED_AGENTS.map(agent => agent.id);
+}

package/src/ascii.js

@@ -0,0 +1,126 @@
+import chalk from 'chalk';
+
+// Clean capital ORCHESTRA
+const logo = `
+
+      ██████╗ ██████╗  ██████╗ ██╗  ██╗ ███████╗ ███████╗ ████████╗ ██████╗   █████╗
+     ██╔═══██╗██╔══██╗██╔════╝ ██║  ██║ ██╔════╝ ██╔════╝ ╚══██╔══╝ ██╔══██╗ ██╔══██╗
+     ██║   ██║██████╔╝██║      ███████║ █████╗   ███████╗    ██║    ██████╔╝ ███████║
+     ██║   ██║██╔══██╗██║      ██╔══██║ ██╔══╝   ╚════██║    ██║    ██╔══██╗ ██╔══██║
+     ╚██████╔╝██║  ██║╚██████╗ ██║  ██║ ███████╗ ███████║    ██║    ██║  ██║ ██║  ██║
+      ╚═════╝ ╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═╝ ╚══════╝ ╚══════╝    ╚═╝    ╚═╝  ╚═╝ ╚═╝  ╚═╝
+
+`;
+
+/**
+ * Welcome screen
+ */
+export function showWelcome(skillCount = 82, categoryCount = 20, agentCount = 5) {
+  console.clear();
+  console.log(chalk.white(logo));
+  console.log();
+  console.log(chalk.bold.white('                          AI Research Skills'));
+  console.log();
+  console.log();
+  console.log(chalk.dim('              Expert-level knowledge for AI research engineering'));
+  console.log();
+  console.log();
+  console.log(`              ${skillCount} skills   ·   ${categoryCount} categories   ·   ${agentCount} agents`);
+  console.log();
+  console.log();
+}
+
+/**
+ * Agents detected screen
+ */
+export function showAgentsDetected(agents) {
+  console.clear();
+  console.log(chalk.white(logo));
+  console.log();
+  console.log(chalk.bold.white('                          AI Research Skills'));
+  console.log();
+  console.log();
+  console.log(chalk.green(`              ✓  Found ${agents.length} coding agent${agents.length !== 1 ? 's' : ''}`));
+  console.log();
+
+  for (const agent of agents) {
+    console.log(`                  ${chalk.green('●')}  ${chalk.white(agent.name.padEnd(14))} ${chalk.dim(agent.path)}`);
+  }
+
+  console.log();
+  console.log();
+}
+
+/**
+ * Menu header for inner screens
+ */
+export function showMenuHeader() {
+  console.clear();
+  console.log();
+  console.log(chalk.dim('    ────────────────────────────────────────────────────────────'));
+  console.log(chalk.white('                      ORCHESTRA  ·  AI Research Skills'));
+  console.log(chalk.dim('    ────────────────────────────────────────────────────────────'));
+  console.log();
+}
+
+/**
+ * Success screen
+ */
+export function showSuccess(skillCount, agents) {
+  console.clear();
+  console.log();
+  console.log();
+  console.log(chalk.green.bold('                          ✓  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();
+  console.log(chalk.dim('              Your skills are now active and will appear when relevant.'));
+  console.log();
+  console.log();
+  console.log(chalk.dim('    ────────────────────────────────────────────────────────────'));
+  console.log();
+  console.log(chalk.white('              Examples:'));
+  console.log();
+  console.log(chalk.dim('                  →  "Help me set up GRPO training with verl"'));
+  console.log(chalk.dim('                  →  "How do I serve a model with vLLM?"'));
+  console.log(chalk.dim('                  →  "Write a NeurIPS paper introduction"'));
+  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')}`);
+  console.log(`              ${chalk.dim('$')} ${chalk.cyan('npx @orchestra-research/ai-research-skills list')}`);
+  console.log(`              ${chalk.dim('$')} ${chalk.cyan('npx @orchestra-research/ai-research-skills update')}`);
+  console.log();
+  console.log(chalk.dim('    ────────────────────────────────────────────────────────────'));
+  console.log();
+  console.log(chalk.dim('              github.com/orchestra-research/ai-research-skills'));
+  console.log();
+}
+
+/**
+ * No agents found screen
+ */
+export function showNoAgents() {
+  console.clear();
+  console.log(chalk.white(logo));
+  console.log();
+  console.log(chalk.bold.white('                          AI Research Skills'));
+  console.log();
+  console.log();
+  console.log(chalk.yellow('              ⚠  No coding agents detected'));
+  console.log();
+  console.log(chalk.dim('              Install one of these supported agents:'));
+  console.log();
+  console.log('                  ○  Claude Code');
+  console.log('                  ○  Cursor');
+  console.log('                  ○  Codex (OpenAI)');
+  console.log('                  ○  Windsurf');
+  console.log('                  ○  Gemini CLI');
+  console.log('                  ○  Kilo Code');
+  console.log('                  ○  Qwen Code');
+  console.log();
+  console.log();
+}

package/src/index.js

@@ -0,0 +1,282 @@
+import ora from 'ora';
+import chalk from 'chalk';
+
+import { detectAgents } from './agents.js';
+import { showWelcome, showAgentsDetected, showSuccess, showNoAgents, showMenuHeader } from './ascii.js';
+import {
+  askInstallChoice,
+  askCategories,
+  askIndividualSkills,
+  askConfirmation,
+  askMainMenuAction,
+  askSelectAgents,
+  askAfterAction,
+  parseArgs,
+  CATEGORIES,
+  INDIVIDUAL_SKILLS,
+  QUICK_START_SKILLS,
+  getTotalSkillCount,
+} from './prompts.js';
+import { installSkills, installSpecificSkills, listInstalledSkills, getAllCategoryIds } from './installer.js';
+
+/**
+ * Sleep utility
+ */
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Interactive flow - the main guided experience with navigation
+ */
+async function interactiveFlow() {
+  let agents = [];
+
+  // STEP 1: Welcome + Agent Detection
+  showWelcome();
+  const spinner = ora({
+    text: chalk.cyan('Detecting coding agents...'),
+    spinner: 'dots',
+    prefixText: '              ',
+  }).start();
+
+  await sleep(1200);
+  agents = detectAgents();
+  spinner.stop();
+
+  if (agents.length === 0) {
+    showNoAgents();
+    console.log(chalk.yellow('              Please install a supported coding agent first.'));
+    console.log();
+    return;
+  }
+
+  // STEP 2: Show detected agents + main menu
+  step2_menu:
+  while (true) {
+    showAgentsDetected(agents);
+    const menuAction = await askMainMenuAction();
+
+    if (menuAction === 'exit') {
+      console.log(chalk.dim('              Goodbye!'));
+      console.log();
+      return;
+    }
+
+    if (menuAction === 'view') {
+      // View installed skills
+      showMenuHeader();
+      listInstalledSkills();
+      const afterView = await askAfterAction();
+      if (afterView === 'exit') {
+        console.log(chalk.dim('              Goodbye!'));
+        console.log();
+        return;
+      }
+      continue step2_menu;
+    }
+
+    if (menuAction === 'update') {
+      // Update all skills
+      showMenuHeader();
+      console.log(chalk.cyan('    Updating all skills...'));
+      console.log();
+      const categories = getAllCategoryIds();
+      await installSkills(categories, agents);
+      console.log();
+      console.log(chalk.green('    ✓ All skills updated!'));
+      const afterUpdate = await askAfterAction();
+      if (afterUpdate === 'exit') {
+        console.log(chalk.dim('              Goodbye!'));
+        console.log();
+        return;
+      }
+      continue step2_menu;
+    }
+
+    // STEP 3: Choose what to install (menuAction === 'install')
+    step3_choice:
+    while (true) {
+      showMenuHeader();
+      const choice = await askInstallChoice();
+
+      if (choice === 'back') {
+        continue step2_menu;
+      }
+
+      let categories = [];
+      let selectedSkills = [];
+      let skillCount = 0;
+      let installType = choice;
+
+      // Handle different choices
+      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') {
+        // Category selection
+        step4_categories:
+        while (true) {
+          showMenuHeader();
+          const result = await askCategories();
+
+          if (result.action === 'back') {
+            continue step3_choice;
+          }
+          if (result.action === 'retry') {
+            continue step4_categories;
+          }
+
+          categories = result.categories;
+          skillCount = CATEGORIES
+            .filter(c => categories.includes(c.id))
+            .reduce((sum, c) => sum + c.skills, 0);
+          break;
+        }
+      } else if (choice === 'individual') {
+        // Individual skill selection
+        step4_individual:
+        while (true) {
+          showMenuHeader();
+          const result = await askIndividualSkills();
+
+          if (result.action === 'back') {
+            continue step3_choice;
+          }
+          if (result.action === 'retry') {
+            continue step4_individual;
+          }
+
+          selectedSkills = result.skills;
+          skillCount = selectedSkills.length;
+          break;
+        }
+      }
+
+      // STEP 5: Select agents + Confirmation
+      let targetAgents = agents;
+      step5_agents:
+      while (true) {
+        showMenuHeader();
+        const agentResult = await askSelectAgents(agents);
+
+        if (agentResult.action === 'back') {
+          continue step3_choice;
+        }
+        if (agentResult.action === 'retry') {
+          continue step5_agents;
+        }
+
+        targetAgents = agentResult.agents;
+
+        // STEP 6: Confirmation
+        showMenuHeader();
+        const confirmAction = await askConfirmation(skillCount, targetAgents, categories, selectedSkills, installType);
+
+        if (confirmAction === 'exit') {
+          console.log(chalk.dim('              Goodbye!'));
+          console.log();
+          return;
+        }
+        if (confirmAction === 'back') {
+          continue step5_agents;
+        }
+
+        break;
+      }
+
+      // STEP 7: Installation
+      console.log();
+      console.log(chalk.cyan('    Installing...'));
+      console.log();
+
+      let installedCount;
+      if (selectedSkills.length > 0) {
+        // Install specific skills
+        installedCount = await installSpecificSkills(selectedSkills, targetAgents);
+      } else {
+        // Install by categories
+        installedCount = await installSkills(categories, targetAgents);
+      }
+
+      // STEP 8: Success!
+      await sleep(500);
+      showSuccess(installedCount, targetAgents);
+      return;
+    }
+  }
+}
+
+/**
+ * Direct command mode (for power users)
+ */
+async function commandMode(options) {
+  if (options.command === 'list') {
+    listInstalledSkills();
+    return;
+  }
+
+  if (options.command === 'update') {
+    console.log(chalk.cyan('Updating skills...'));
+    const agents = detectAgents();
+    if (agents.length === 0) {
+      console.log(chalk.yellow('No agents detected.'));
+      return;
+    }
+    const categories = getAllCategoryIds();
+    await installSkills(categories, 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;
+    }
+
+    let categories;
+    if (options.all) {
+      categories = getAllCategoryIds();
+    } else if (options.category) {
+      categories = [options.category];
+    } else if (options.skill) {
+      const matchingCategory = CATEGORIES.find(c =>
+        c.id.includes(options.skill) || c.name.toLowerCase().includes(options.skill.toLowerCase())
+      );
+      if (matchingCategory) {
+        categories = [matchingCategory.id];
+      } else {
+        console.log(chalk.yellow(`Category or skill "${options.skill}" not found.`));
+        return;
+      }
+    } else {
+      categories = getAllCategoryIds();
+    }
+
+    console.log(chalk.cyan('Installing skills...'));
+    await installSkills(categories, agents);
+    console.log(chalk.green('✓ Done!'));
+    return;
+  }
+}
+
+/**
+ * Main entry point
+ */
+export async function main() {
+  const args = process.argv.slice(2);
+  const options = parseArgs(args);
+
+  // If any command-line options provided, use command mode
+  if (options.command || options.all || options.category || options.skill) {
+    await commandMode(options);
+  } else {
+    // Otherwise, use interactive flow
+    await interactiveFlow();
+  }
+}