@ara-commons/ara-skills 0.1.0

package/src/agents.js

@@ -0,0 +1,77 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * Minimal agent registry. Each entry declares where the agent expects skills
+ * to live, both globally (user-level) and locally (per-project).
+ *
+ * The layout we write is: <skillsDir>/<skill-id>/SKILL.md (+ any files).
+ */
+export const SUPPORTED_AGENTS = [
+  {
+    id: 'claude-code',
+    name: 'Claude Code',
+    globalSkillsDir: path.join(os.homedir(), '.claude', 'skills'),
+    localSkillsDir: '.claude/skills',
+    detect: () => fs.existsSync(path.join(os.homedir(), '.claude')),
+  },
+  {
+    id: 'cursor',
+    name: 'Cursor',
+    globalSkillsDir: path.join(os.homedir(), '.cursor', 'skills'),
+    localSkillsDir: '.cursor/skills',
+    detect: () => fs.existsSync(path.join(os.homedir(), '.cursor')),
+  },
+  {
+    id: 'gemini-cli',
+    name: 'Gemini CLI',
+    globalSkillsDir: path.join(os.homedir(), '.gemini', 'skills'),
+    localSkillsDir: '.gemini/skills',
+    detect: () => fs.existsSync(path.join(os.homedir(), '.gemini')),
+  },
+  {
+    id: 'opencode',
+    name: 'OpenCode',
+    globalSkillsDir: path.join(os.homedir(), '.opencode', 'skills'),
+    localSkillsDir: '.opencode/skills',
+    detect: () => fs.existsSync(path.join(os.homedir(), '.opencode')),
+  },
+  {
+    id: 'codex',
+    name: 'Codex CLI',
+    globalSkillsDir: path.join(os.homedir(), '.codex', 'skills'),
+    localSkillsDir: '.codex/skills',
+    detect: () => fs.existsSync(path.join(os.homedir(), '.codex')),
+  },
+  {
+    id: 'hermes',
+    name: 'Hermes Agent',
+    globalSkillsDir: path.join(os.homedir(), '.hermes', 'skills'),
+    localSkillsDir: '.hermes/skills',
+    detect: () => fs.existsSync(path.join(os.homedir(), '.hermes')),
+  },
+  {
+    id: 'generic',
+    name: 'Generic (./skills)',
+    globalSkillsDir: path.join(os.homedir(), '.skills'),
+    localSkillsDir: 'skills',
+    detect: () => false,
+  },
+];
+
+export function detectAgents() {
+  return SUPPORTED_AGENTS.filter((a) => a.detect());
+}
+
+export function getAgentById(id) {
+  return SUPPORTED_AGENTS.find((a) => a.id === id);
+}
+
+export function getSupportedAgentIds() {
+  return SUPPORTED_AGENTS.map((a) => a.id);
+}
+
+export function targetDirFor(agent, { local = false, cwd = process.cwd() } = {}) {
+  return local ? path.resolve(cwd, agent.localSkillsDir) : agent.globalSkillsDir;
+}

package/src/index.js

@@ -0,0 +1,165 @@
+import chalk from 'chalk';
+import { SUPPORTED_AGENTS, detectAgents, getAgentById } from './agents.js';
+import { listSkills } from './skills.js';
+import { install, uninstall, update, listInstalled } from './installer.js';
+
+const HELP = `
+${chalk.bold.cyan('ara-skills')} — install ARA research skills to your coding agent
+
+${chalk.bold('Usage:')}
+  npx @ara-commons/ara-skills                 # interactive
+  npx @ara-commons/ara-skills install [opts]
+  npx @ara-commons/ara-skills list
+  npx @ara-commons/ara-skills update  [opts]
+  npx @ara-commons/ara-skills uninstall [opts]
+  npx @ara-commons/ara-skills skills          # show available skills
+  npx @ara-commons/ara-skills agents          # show supported agents
+
+${chalk.bold('Install options:')}
+  --all                         Install every skill (default if no --skill given)
+  --skill <id>                  Install one skill (repeatable). Ids: compiler, research-manager, rigor-reviewer
+  --agent <id>                  Target one agent (repeatable). Default: auto-detect, else claude-code
+  --local                       Install into ./<agent>/skills instead of $HOME
+  --force                       Overwrite existing installations
+  --quiet                       Suppress per-skill log output
+
+${chalk.bold('Examples:')}
+  npx @ara-commons/ara-skills install --all
+  npx @ara-commons/ara-skills install --skill compiler --agent claude-code
+  npx @ara-commons/ara-skills install --all --local
+  npx @ara-commons/ara-skills uninstall --skill rigor-reviewer --agent cursor
+`;
+
+function parseArgs(argv) {
+  const out = { _: [], skills: [], agents: [], flags: {} };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--skill' || a === '-s') out.skills.push(argv[++i]);
+    else if (a === '--agent' || a === '-a') out.agents.push(argv[++i]);
+    else if (a === '--all') out.flags.all = true;
+    else if (a === '--local') out.flags.local = true;
+    else if (a === '--force') out.flags.force = true;
+    else if (a === '--quiet' || a === '-q') out.flags.quiet = true;
+    else if (a === '--help' || a === '-h') out.flags.help = true;
+    else if (a === '--version' || a === '-v') out.flags.version = true;
+    else if (a.startsWith('-')) throw new Error(`Unknown flag: ${a}`);
+    else out._.push(a);
+  }
+  return out;
+}
+
+function resolveAgents(requested) {
+  if (requested.length > 0) {
+    for (const id of requested) {
+      if (!getAgentById(id)) {
+        throw new Error(
+          `Unknown agent "${id}". Supported: ${SUPPORTED_AGENTS.map((a) => a.id).join(', ')}`
+        );
+      }
+    }
+    return requested;
+  }
+  const detected = detectAgents();
+  if (detected.length > 0) return detected.map((a) => a.id);
+  return ['claude-code'];
+}
+
+export async function main(argv) {
+  const args = parseArgs(argv);
+
+  if (args.flags.help) {
+    console.log(HELP);
+    return;
+  }
+  if (args.flags.version) {
+    const { readFileSync } = await import('node:fs');
+    const { fileURLToPath } = await import('node:url');
+    const { dirname, join } = await import('node:path');
+    const here = dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8'));
+    console.log(pkg.version);
+    return;
+  }
+
+  const cmd = args._[0];
+
+  if (!cmd) {
+    const { interactiveFlow } = await import('./prompts.js');
+    await interactiveFlow();
+    return;
+  }
+
+  if (cmd === 'skills') {
+    for (const s of listSkills()) {
+      console.log(`${chalk.bold(s.id)}`);
+      console.log(`  ${chalk.gray(s.description.slice(0, 120))}`);
+    }
+    return;
+  }
+
+  if (cmd === 'agents') {
+    const detected = new Set(detectAgents().map((a) => a.id));
+    for (const a of SUPPORTED_AGENTS) {
+      const tag = detected.has(a.id) ? chalk.green('✓ detected') : chalk.gray('not detected');
+      console.log(`${chalk.bold(a.id.padEnd(14))} ${tag}  ${chalk.gray(a.globalSkillsDir)}`);
+    }
+    return;
+  }
+
+  if (cmd === 'list') {
+    const rows = listInstalled();
+    if (rows.length === 0) {
+      console.log('No ARA skills installed.');
+      return;
+    }
+    for (const r of rows) {
+      console.log(`${chalk.bold(r.agent)} (${r.scope})  ${chalk.gray(r.dir)}`);
+      for (const s of r.skills) console.log(`  • ${s}`);
+    }
+    return;
+  }
+
+  const local = !!args.flags.local;
+  const force = !!args.flags.force;
+  const quiet = !!args.flags.quiet;
+
+  if (cmd === 'install') {
+    const agentIds = resolveAgents(args.agents);
+    const skillIds = args.skills;
+    if (!quiet) {
+      const label = skillIds.length ? skillIds.join(', ') : 'all skills';
+      console.log(
+        `Installing ${chalk.bold(label)} to ${chalk.bold(agentIds.join(', '))} (${
+          local ? 'local' : 'global'
+        })`
+      );
+    }
+    for (const agentId of agentIds) {
+      if (!quiet) console.log(chalk.bold(`→ ${agentId}`));
+      install({ agentId, skillIds, local, force, quiet });
+    }
+    return;
+  }
+
+  if (cmd === 'update') {
+    const agentIds = resolveAgents(args.agents);
+    for (const agentId of agentIds) {
+      if (!quiet) console.log(chalk.bold(`→ ${agentId}`));
+      update({ agentId, local, quiet });
+    }
+    return;
+  }
+
+  if (cmd === 'uninstall') {
+    const agentIds = resolveAgents(args.agents);
+    const skillIds = args.skills;
+    for (const agentId of agentIds) {
+      if (!quiet) console.log(chalk.bold(`→ ${agentId}`));
+      uninstall({ agentId, skillIds, local, quiet });
+    }
+    return;
+  }
+
+  console.log(HELP);
+  throw new Error(`Unknown command: ${cmd}`);
+}

package/src/installer.js

@@ -0,0 +1,188 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { listSkills, getSkill } from './skills.js';
+import { SUPPORTED_AGENTS, getAgentById, targetDirFor } from './agents.js';
+
+const LOCK_FILE = '.ara-skills.json';
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function copyDir(src, dst) {
+  fs.mkdirSync(dst, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dst, entry.name);
+    if (entry.isDirectory()) copyDir(s, d);
+    else if (entry.isSymbolicLink()) {
+      const link = fs.readlinkSync(s);
+      try {
+        fs.symlinkSync(link, d);
+      } catch {
+        fs.copyFileSync(s, d);
+      }
+    } else fs.copyFileSync(s, d);
+  }
+}
+
+function rmIfExists(p) {
+  if (fs.existsSync(p)) fs.rmSync(p, { recursive: true, force: true });
+}
+
+function readLock(dir) {
+  const file = path.join(dir, LOCK_FILE);
+  if (!fs.existsSync(file)) return { skills: {} };
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return { skills: {} };
+  }
+}
+
+function writeLock(dir, data) {
+  const file = path.join(dir, LOCK_FILE);
+  ensureDir(dir);
+  fs.writeFileSync(
+    file,
+    JSON.stringify({ updatedAt: new Date().toISOString(), ...data }, null, 2)
+  );
+}
+
+/**
+ * Install a set of skills to a single agent's skills directory.
+ *
+ * opts:
+ *   agentId:   string, required
+ *   skillIds:  string[] — empty array means "all skills"
+ *   local:     boolean — install into the current project rather than $HOME
+ *   cwd:       string  — overrides process.cwd() for local installs
+ *   force:     boolean — overwrite existing installations
+ *   quiet:     boolean — suppress log output
+ */
+export function install(opts) {
+  const { agentId, skillIds = [], local = false, cwd, force = false, quiet = false } = opts;
+  const agent = getAgentById(agentId);
+  if (!agent) throw new Error(`Unknown agent: ${agentId}`);
+
+  const allSkills = listSkills();
+  const selected =
+    skillIds.length === 0
+      ? allSkills
+      : skillIds.map((id) => {
+          const s = getSkill(id);
+          if (!s) throw new Error(`Unknown skill: ${id}`);
+          return s;
+        });
+
+  const targetDir = targetDirFor(agent, { local, cwd });
+  ensureDir(targetDir);
+
+  const results = [];
+  const lock = readLock(targetDir);
+  lock.skills = lock.skills || {};
+
+  for (const skill of selected) {
+    const dest = path.join(targetDir, skill.id);
+    const exists = fs.existsSync(dest);
+    if (exists && !force) {
+      results.push({ skill: skill.id, status: 'skipped', reason: 'already installed' });
+      if (!quiet) console.log(`  ~ ${skill.id} already installed (use --force to overwrite)`);
+      continue;
+    }
+    if (exists) rmIfExists(dest);
+    copyDir(skill.path, dest);
+    lock.skills[skill.id] = {
+      installedAt: new Date().toISOString(),
+      source: '@ara-commons/ara-skills',
+    };
+    results.push({ skill: skill.id, status: 'installed', dest });
+    if (!quiet) console.log(`  + ${skill.id}  ->  ${dest}`);
+  }
+
+  writeLock(targetDir, lock);
+  return { agent: agent.id, targetDir, results };
+}
+
+/**
+ * Install to multiple agents at once.
+ */
+export function installMany(opts) {
+  const { agentIds, ...rest } = opts;
+  return agentIds.map((agentId) => install({ ...rest, agentId }));
+}
+
+export function uninstall(opts) {
+  const { agentId, skillIds = [], local = false, cwd, quiet = false } = opts;
+  const agent = getAgentById(agentId);
+  if (!agent) throw new Error(`Unknown agent: ${agentId}`);
+
+  const targetDir = targetDirFor(agent, { local, cwd });
+  if (!fs.existsSync(targetDir)) {
+    return { agent: agent.id, targetDir, results: [] };
+  }
+
+  const lock = readLock(targetDir);
+  const known = Object.keys(lock.skills || {});
+  const targets = skillIds.length === 0 ? known : skillIds;
+
+  const results = [];
+  for (const id of targets) {
+    const dest = path.join(targetDir, id);
+    if (fs.existsSync(dest)) {
+      rmIfExists(dest);
+      delete lock.skills[id];
+      results.push({ skill: id, status: 'removed' });
+      if (!quiet) console.log(`  - ${id}`);
+    } else {
+      results.push({ skill: id, status: 'missing' });
+    }
+  }
+  writeLock(targetDir, lock);
+  return { agent: agent.id, targetDir, results };
+}
+
+/**
+ * "Update" = re-install (overwrite) every currently tracked skill.
+ */
+export function update(opts) {
+  const { agentId, local = false, cwd, quiet = false } = opts;
+  const agent = getAgentById(agentId);
+  if (!agent) throw new Error(`Unknown agent: ${agentId}`);
+
+  const targetDir = targetDirFor(agent, { local, cwd });
+  const lock = readLock(targetDir);
+  const ids = Object.keys(lock.skills || {});
+  if (ids.length === 0) {
+    if (!quiet) console.log(`  (no skills tracked at ${targetDir})`);
+    return { agent: agent.id, targetDir, results: [] };
+  }
+  return install({ agentId, skillIds: ids, local, cwd, force: true, quiet });
+}
+
+/**
+ * List currently installed skills across all known agents.
+ * Checks both global and local (cwd) locations.
+ */
+export function listInstalled({ cwd = process.cwd() } = {}) {
+  const rows = [];
+  for (const agent of SUPPORTED_AGENTS) {
+    for (const scope of ['global', 'local']) {
+      const dir = targetDirFor(agent, { local: scope === 'local', cwd });
+      if (!fs.existsSync(dir)) continue;
+      const lock = readLock(dir);
+      const skills = Object.keys(lock.skills || {});
+      if (skills.length === 0) {
+        // Also look for skill dirs present without a lock file.
+        const bare = fs
+          .readdirSync(dir, { withFileTypes: true })
+          .filter((e) => e.isDirectory() && fs.existsSync(path.join(dir, e.name, 'SKILL.md')))
+          .map((e) => e.name);
+        if (bare.length > 0) rows.push({ agent: agent.id, scope, dir, skills: bare, tracked: false });
+      } else {
+        rows.push({ agent: agent.id, scope, dir, skills, tracked: true });
+      }
+    }
+  }
+  return rows;
+}

package/src/prompts.js

@@ -0,0 +1,118 @@
+import { checkbox, select, confirm } from '@inquirer/prompts';
+import chalk from 'chalk';
+import { SUPPORTED_AGENTS, detectAgents } from './agents.js';
+import { listSkills } from './skills.js';
+import { install, uninstall, update, listInstalled } from './installer.js';
+
+function banner() {
+  console.log();
+  console.log(chalk.bold.cyan('  ARA Skills'));
+  console.log(chalk.gray('  Agent-Native Research Artifact — skills installer'));
+  console.log();
+}
+
+export async function interactiveFlow() {
+  banner();
+
+  const skills = listSkills();
+  const detected = detectAgents();
+  if (detected.length > 0) {
+    console.log(chalk.gray(`  Detected agents: ${detected.map((a) => a.name).join(', ')}`));
+  } else {
+    console.log(chalk.yellow('  No coding agents detected — you can still install locally.'));
+  }
+  console.log();
+
+  const action = await select({
+    message: 'What would you like to do?',
+    choices: [
+      { name: 'Install skills', value: 'install' },
+      { name: 'List installed skills', value: 'list' },
+      { name: 'Update installed skills', value: 'update' },
+      { name: 'Uninstall skills', value: 'uninstall' },
+      { name: 'Exit', value: 'exit' },
+    ],
+  });
+
+  if (action === 'exit') return;
+
+  if (action === 'list') {
+    const rows = listInstalled();
+    if (rows.length === 0) {
+      console.log(chalk.gray('  No ARA skills installed.'));
+      return;
+    }
+    for (const r of rows) {
+      console.log(`  ${chalk.bold(r.agent)} (${r.scope}) — ${chalk.gray(r.dir)}`);
+      for (const s of r.skills) console.log(`    • ${s}`);
+    }
+    return;
+  }
+
+  const scope = await select({
+    message: 'Install scope',
+    choices: [
+      { name: 'Global  (user-level, available in every project)', value: 'global' },
+      { name: 'Local   (just this project / current directory)', value: 'local' },
+    ],
+  });
+  const local = scope === 'local';
+
+  const agentChoices = SUPPORTED_AGENTS.map((a) => ({
+    name: `${a.name}${detected.includes(a) ? chalk.green('  ✓ detected') : ''}`,
+    value: a.id,
+    checked: detected.includes(a),
+  }));
+  const agentIds = await checkbox({
+    message: 'Pick target agents',
+    choices: agentChoices,
+    required: true,
+  });
+
+  if (action === 'install') {
+    const skillIds = await checkbox({
+      message: 'Pick skills to install',
+      choices: skills.map((s) => ({
+        name: `${chalk.bold(s.id)}  —  ${chalk.gray(s.description.slice(0, 80))}`,
+        value: s.id,
+        checked: true,
+      })),
+      required: true,
+    });
+    const force = await confirm({
+      message: 'Overwrite existing installations if present?',
+      default: true,
+    });
+    console.log();
+    for (const agentId of agentIds) {
+      console.log(chalk.bold(`→ ${agentId} (${local ? 'local' : 'global'})`));
+      install({ agentId, skillIds, local, force });
+    }
+  }
+
+  if (action === 'update') {
+    console.log();
+    for (const agentId of agentIds) {
+      console.log(chalk.bold(`→ ${agentId} (${local ? 'local' : 'global'})`));
+      update({ agentId, local });
+    }
+  }
+
+  if (action === 'uninstall') {
+    const skillIds = await checkbox({
+      message: 'Pick skills to remove (empty = all tracked)',
+      choices: skills.map((s) => ({
+        name: `${chalk.bold(s.id)}`,
+        value: s.id,
+      })),
+    });
+    console.log();
+    for (const agentId of agentIds) {
+      console.log(chalk.bold(`→ ${agentId} (${local ? 'local' : 'global'})`));
+      uninstall({ agentId, skillIds, local });
+    }
+  }
+
+  console.log();
+  console.log(chalk.green('  Done.'));
+}

package/src/skills.js

@@ -0,0 +1,98 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+
+/**
+ * Locate the directory that holds the skill sources.
+ *
+ * Two modes:
+ *   1. Published package: skills are bundled at <pkg>/skills/  (via `prepack`).
+ *   2. Dev mode (running from monorepo): fall back to <repoRoot>/skills/
+ *      which is <pkg>/../../skills.
+ */
+export function resolveSkillsRoot() {
+  const bundled = path.join(PACKAGE_ROOT, 'skills');
+  if (isSkillsDir(bundled)) return bundled;
+
+  const monorepo = path.resolve(PACKAGE_ROOT, '..', '..', 'skills');
+  if (isSkillsDir(monorepo)) return monorepo;
+
+  throw new Error(
+    `Could not locate skills directory. Looked in:\n  ${bundled}\n  ${monorepo}`
+  );
+}
+
+function isSkillsDir(dir) {
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return false;
+  const entries = fs.readdirSync(dir);
+  return entries.some((name) => {
+    const skillMd = path.join(dir, name, 'SKILL.md');
+    return fs.existsSync(skillMd);
+  });
+}
+
+/**
+ * Parse the YAML frontmatter at the top of SKILL.md.
+ * Intentionally minimal — we only need `name` and `description`.
+ */
+function parseFrontmatter(mdPath) {
+  const src = fs.readFileSync(mdPath, 'utf8');
+  if (!src.startsWith('---')) return {};
+  const end = src.indexOf('\n---', 3);
+  if (end < 0) return {};
+  const body = src.slice(3, end).trim();
+
+  const out = {};
+  let currentKey = null;
+  let buffer = [];
+  const flush = () => {
+    if (currentKey !== null) {
+      out[currentKey] = buffer.join('\n').trim();
+    }
+  };
+
+  for (const raw of body.split('\n')) {
+    const line = raw.replace(/\r$/, '');
+    const m = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    // A new top-level key starts only when the line has no leading whitespace.
+    if (m && !raw.startsWith(' ') && !raw.startsWith('\t')) {
+      flush();
+      currentKey = m[1];
+      const value = m[2];
+      buffer = value === '' || value === '|' || value === '>' ? [] : [value];
+    } else if (currentKey) {
+      buffer.push(line.replace(/^\s{2}/, ''));
+    }
+  }
+  flush();
+  return out;
+}
+
+/**
+ * Discover all skills by scanning <root>/<id>/SKILL.md.
+ * Returns: [{ id, name, description, path }]
+ */
+export function listSkills(root = resolveSkillsRoot()) {
+  const out = [];
+  for (const id of fs.readdirSync(root).sort()) {
+    const skillDir = path.join(root, id);
+    const skillMd = path.join(skillDir, 'SKILL.md');
+    if (!fs.existsSync(skillMd)) continue;
+    if (!fs.statSync(skillDir).isDirectory()) continue;
+
+    const meta = parseFrontmatter(skillMd);
+    const name = meta.name || id;
+    const description =
+      (meta.description || '').replace(/\s+/g, ' ').trim().slice(0, 240) ||
+      `(no description)`;
+    out.push({ id, name, description, path: skillDir });
+  }
+  return out;
+}
+
+export function getSkill(id) {
+  return listSkills().find((s) => s.id === id || s.name === id);
+}