Manage Local Skills

#!/usr/bin/env node

import fs from 'fs';
import path from 'path';
import { fileURLToPath } from 'url';
import { sanitizeSkillName } from './lib/path-safety.mjs';

const __filename = fileURLToPath(import.meta.url);

function parseArgs(argv) {
  const options = {
    input: '',
    subpath: '',
    json: false,
  };

  for (let index = 0; index < argv.length; index += 1) {
    const arg = argv[index];
    if (arg === '--input') {
      options.input = argv[index + 1] || '';
      index += 1;
      continue;
    }
    if (arg === '--subpath') {
      options.subpath = argv[index + 1] || '';
      index += 1;
      continue;
    }
    if (arg === '--json') {
      options.json = true;
    }
  }

  if (!options.input) {
    throw new Error('Missing required --input');
  }

  return options;
}

function walkFiles(rootDir, currentDir = rootDir, result = []) {
  for (const entry of fs.readdirSync(currentDir, { withFileTypes: true })) {
    if (entry.name === '.git' || entry.name === 'node_modules' || entry.name === '.DS_Store') {
      continue;
    }

    const fullPath = path.join(currentDir, entry.name);
    const relativePath = path.relative(rootDir, fullPath) || entry.name;
    if (entry.isDirectory()) {
      walkFiles(rootDir, fullPath, result);
    } else if (entry.isFile()) {
      result.push(relativePath.split(path.sep).join('/'));
    }
  }

  return result.sort();
}

function classifyFiles(files) {
  const references = [];
  const scripts = [];
  const assets = [];
  const warnings = [];

  for (const file of files) {
    const lower = file.toLowerCase();
    if (lower.endsWith('/skill.md') || lower === 'skill.md') {
      continue;
    }
    if (lower.endsWith('.mjs') || lower.endsWith('.js') || lower.endsWith('.sh') || lower.endsWith('.py')) {
      scripts.push(file);
      continue;
    }
    if (lower.endsWith('.md') || lower.endsWith('.mdx') || lower.endsWith('.txt')) {
      references.push(file);
      continue;
    }
    assets.push(file);
  }

  if (references.length === 0 && scripts.length === 0) {
    warnings.push('No obvious reference or script files were detected.');
  }

  return { references, scripts, assets, warnings };
}

export function inspectSource({ input, subpath = '' }) {
  const inputPath = path.resolve(input);
  const rootPath = subpath ? path.join(inputPath, subpath) : inputPath;

  if (!fs.existsSync(rootPath)) {
    throw new Error(`Input path not found: ${rootPath}`);
  }

  const allFiles = walkFiles(rootPath);
  const skillFiles = allFiles.filter((file) => path.basename(file).toLowerCase() === 'skill.md');
  const hasRootSkill = skillFiles.includes('SKILL.md');

  let sourceType = 'nonstandard';
  if (hasRootSkill && skillFiles.length === 1) {
    sourceType = 'standard';
  } else if (skillFiles.length > 0) {
    sourceType = hasRootSkill ? 'mixed' : 'mixed';
  }

  const candidateName = sanitizeSkillName(path.basename(rootPath));
  const grouped = classifyFiles(allFiles);

  return {
    sourceType,
    inputPath,
    rootPath,
    candidateSkillName: candidateName,
    skillEntryPath: hasRootSkill ? path.join(rootPath, 'SKILL.md') : null,
    detectedFiles: allFiles,
    suggestedReferences: grouped.references,
    suggestedScripts: grouped.scripts,
    suggestedAssets: grouped.assets,
    warnings: grouped.warnings,
  };
}

function main() {
  const options = parseArgs(process.argv.slice(2));
  const result = inspectSource(options);

  if (options.json) {
    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
    return;
  }

  console.log(`Source type: ${result.sourceType}`);
  console.log(`Candidate skill: ${result.candidateSkillName}`);
  console.log(`Files: ${result.detectedFiles.length}`);
  console.log(`References: ${result.suggestedReferences.length}`);
  console.log(`Scripts: ${result.suggestedScripts.length}`);
  console.log(`Assets: ${result.suggestedAssets.length}`);

  if (result.warnings.length > 0) {
    console.log('Warnings:');
    for (const warning of result.warnings) {
      console.log(`- ${warning}`);
    }
  }
}

if (process.argv[1] && path.resolve(process.argv[1]) === __filename) {
  try {
    main();
  } catch (error) {
    console.error(error.message);
    process.exit(1);
  }
}

#!/usr/bin/env node

import fs from 'fs';
import path from 'path';
import { fileURLToPath } from 'url';
import { installLocalSkill } from './lib/install-model.mjs';

const __filename = fileURLToPath(import.meta.url);

function parseArgs(argv) {
  const options = {
    sourceDir: '',
    skill: '',
    agent: '',
    scope: 'project',
    mode: 'symlink',
    dryRun: false,
    json: false,
  };

  for (let index = 0; index < argv.length; index += 1) {
    const arg = argv[index];
    if (arg === '--source-dir') {
      options.sourceDir = argv[index + 1] || '';
      index += 1;
      continue;
    }
    if (arg === '--skill') {
      options.skill = argv[index + 1] || '';
      index += 1;
      continue;
    }
    if (arg === '--agent') {
      options.agent = argv[index + 1] || '';
      index += 1;
      continue;
    }
    if (arg === '--scope') {
      options.scope = argv[index + 1] || options.scope;
      index += 1;
      continue;
    }
    if (arg === '--mode') {
      options.mode = argv[index + 1] || options.mode;
      index += 1;
      continue;
    }
    if (arg === '--dry-run') {
      options.dryRun = true;
      continue;
    }
    if (arg === '--json') {
      options.json = true;
    }
  }

  if (!options.sourceDir || !options.skill || !options.agent) {
    throw new Error('Missing required --source-dir, --skill, or --agent');
  }

  if (!['project', 'global'].includes(options.scope)) {
    throw new Error(`Unsupported scope: ${options.scope}`);
  }

  if (!['symlink', 'copy'].includes(options.mode)) {
    throw new Error(`Unsupported mode: ${options.mode}`);
  }

  return options;
}

export function runInstallSkill(options) {
  const skillDir = path.resolve(options.sourceDir, options.skill);
  if (!fs.existsSync(path.join(skillDir, 'SKILL.md'))) {
    throw new Error(`Missing SKILL.md for skill: ${skillDir}`);
  }

  return installLocalSkill({
    sourceDir: skillDir,
    skillName: options.skill,
    agentKey: options.agent,
    scope: options.scope,
    mode: options.mode,
    dryRun: options.dryRun,
  });
}

function main() {
  const options = parseArgs(process.argv.slice(2));
  const result = runInstallSkill(options);

  if (options.json) {
    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
    return;
  }

  console.log(`Skill: ${result.skillName}`);
  console.log(`Agent: ${result.agentKey}`);
  console.log(`Scope: ${result.scope}`);
  console.log(`Mode: ${result.mode}`);
  console.log(`Canonical: ${result.canonicalPath}`);
  console.log(`Target: ${result.targetPath}`);
  if (result.symlinkFailed) {
    console.log('Symlink failed, copied instead.');
  }
}

if (process.argv[1] && path.resolve(process.argv[1]) === __filename) {
  try {
    main();
  } catch (error) {
    console.error(error.message);
    process.exit(1);
  }
}

import path from 'path';
import { homedir } from 'os';
import { expandHomePath } from './path-safety.mjs';

const HOME = homedir();
const CONFIG_HOME = process.env.XDG_CONFIG_HOME?.trim() || path.join(HOME, '.config');
const CODEX_HOME = process.env.CODEX_HOME?.trim() || path.join(HOME, '.codex');
const CLAUDE_HOME = process.env.CLAUDE_CONFIG_DIR?.trim() || path.join(HOME, '.claude');
const CANONICAL_SKILLS_DIR = '.agents/skills';

export const AGENT_MAPPINGS = {
  universal: {
    key: 'universal',
    displayName: 'Universal',
    skillsDir: CANONICAL_SKILLS_DIR,
    globalSkillsDir: path.join(CONFIG_HOME, 'agents/skills'),
    showInUniversalList: false,
  },
  claude: {
    key: 'claude',
    displayName: 'Claude',
    skillsDir: '.claude/skills',
    globalSkillsDir: path.join(CLAUDE_HOME, 'skills'),
  },
  'claude-code': {
    key: 'claude-code',
    displayName: 'Claude Code',
    skillsDir: '.claude/skills',
    globalSkillsDir: path.join(CLAUDE_HOME, 'skills'),
  },
  codebuddy: {
    key: 'codebuddy',
    displayName: 'CodeBuddy',
    skillsDir: '.codebuddy/skills',
    globalSkillsDir: path.join(HOME, '.codebuddy/skills'),
  },
  cursor: {
    key: 'cursor',
    displayName: 'Cursor',
    skillsDir: CANONICAL_SKILLS_DIR,
    globalSkillsDir: path.join(HOME, '.cursor/skills'),
  },
  codex: {
    key: 'codex',
    displayName: 'Codex',
    skillsDir: CANONICAL_SKILLS_DIR,
    globalSkillsDir: path.join(CODEX_HOME, 'skills'),
  },
};

export function getAgentMapping(agentKey) {
  const mapping = AGENT_MAPPINGS[agentKey];
  if (!mapping) {
    throw new Error(`Unsupported agent: ${agentKey}`);
  }
  return mapping;
}

export function listAgentMappings() {
  return Object.values(AGENT_MAPPINGS).map((mapping) => ({ ...mapping }));
}

export function isUniversalAgent(agentKey) {
  return getAgentMapping(agentKey).skillsDir === CANONICAL_SKILLS_DIR;
}

export function getUniversalAgents() {
  return Object.entries(AGENT_MAPPINGS)
    .filter(([, mapping]) => mapping.skillsDir === CANONICAL_SKILLS_DIR && mapping.showInUniversalList !== false)
    .map(([agentKey]) => agentKey);
}

export function resolveAgentBaseDir(agentKey, scope, cwd) {
  const mapping = getAgentMapping(agentKey);

  if (isUniversalAgent(agentKey)) {
    return scope === 'global'
      ? path.join(HOME, '.agents', 'skills')
      : path.join(cwd, CANONICAL_SKILLS_DIR);
  }

  if (scope === 'project') {
    return path.join(cwd, mapping.skillsDir);
  }

  if (!mapping.globalSkillsDir) {
    throw new Error(`${mapping.displayName} does not support global scope`);
  }

  return expandHomePath(mapping.globalSkillsDir, HOME);
}

import fs from 'fs';
import path from 'path';
import { homedir, platform } from 'os';
import { assertPathSafe, sanitizeSkillName } from './path-safety.mjs';
import { getAgentMapping, isUniversalAgent, resolveAgentBaseDir } from './agent-mappings.mjs';

function ensureDir(dirPath) {
  fs.mkdirSync(dirPath, { recursive: true });
}

function removePath(targetPath) {
  fs.rmSync(targetPath, { recursive: true, force: true });
}

function shouldSkip(name) {
  return name === '.git' || name === 'node_modules' || name === '.DS_Store';
}

export function copyDirectory(sourceDir, targetDir) {
  ensureDir(targetDir);

  for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) {
    if (shouldSkip(entry.name)) {
      continue;
    }

    const sourcePath = path.join(sourceDir, entry.name);
    const targetPath = path.join(targetDir, entry.name);

    if (entry.isDirectory()) {
      copyDirectory(sourcePath, targetPath);
      continue;
    }

    if (entry.isFile()) {
      ensureDir(path.dirname(targetPath));
      fs.copyFileSync(sourcePath, targetPath);
    }
  }
}

function symlinkDirectory(sourceDir, targetPath) {
  ensureDir(path.dirname(targetPath));
  const relativeTarget = path.relative(path.dirname(targetPath), sourceDir);
  fs.symlinkSync(relativeTarget, targetPath, platform() === 'win32' ? 'junction' : undefined);
}

export function getCanonicalBaseDir(scope, cwd) {
  return scope === 'global' ? path.join(homedir(), '.agents', 'skills') : path.join(cwd, '.agents', 'skills');
}

export function getCanonicalSkillPath(skillName, scope, cwd) {
  const sanitized = sanitizeSkillName(skillName);
  const baseDir = getCanonicalBaseDir(scope, cwd);
  const canonicalPath = path.join(baseDir, sanitized);
  assertPathSafe(baseDir, canonicalPath, 'canonical path');
  return canonicalPath;
}

export function getAgentSkillPath(agentKey, skillName, scope, cwd) {
  const sanitized = sanitizeSkillName(skillName);
  const agentBase = resolveAgentBaseDir(agentKey, scope, cwd);
  const targetPath = path.join(agentBase, sanitized);
  assertPathSafe(agentBase, targetPath, 'agent skill path');
  return targetPath;
}

export function detectConflict(targetPath) {
  if (!fs.existsSync(targetPath)) {
    return 'none';
  }

  const stats = fs.lstatSync(targetPath);
  if (stats.isSymbolicLink()) {
    return 'replace';
  }

  if (stats.isDirectory()) {
    return 'overwrite';
  }

  return 'replace';
}

export function installLocalSkill(options) {
  const {
    sourceDir,
    skillName,
    agentKey,
    scope = 'project',
    mode = 'symlink',
    dryRun = false,
    cwd = process.cwd(),
  } = options;

  const mapping = getAgentMapping(agentKey);
  const canonicalPath = getCanonicalSkillPath(skillName, scope, cwd);
  const targetPath = isUniversalAgent(agentKey)
    ? canonicalPath
    : getAgentSkillPath(agentKey, skillName, scope, cwd);
  const canonicalConflict = detectConflict(canonicalPath);
  const targetConflict = targetPath === canonicalPath ? canonicalConflict : detectConflict(targetPath);
  const canonicalPointsToSource = mode === 'symlink';
  let canonicalSymlinkFailed = false;
  let canonicalSymlinkError = null;

  const plan = {
    sourceDir,
    skillName: sanitizeSkillName(skillName),
    agentKey,
    scope,
    requestedMode: mode,
    canonicalPath,
    targetPath,
    canonicalConflict,
    targetConflict,
    targetIsUniversal: isUniversalAgent(agentKey),
    canonicalPointsToSource,
  };

  if (dryRun) {
    return {
      success: true,
      dryRun: true,
      mode,
      ...plan,
    };
  }

  removePath(canonicalPath);
  ensureDir(path.dirname(canonicalPath));

  if (mode === 'symlink') {
    try {
      symlinkDirectory(sourceDir, canonicalPath);
    } catch (error) {
      canonicalSymlinkFailed = true;
      canonicalSymlinkError = error instanceof Error ? error.message : String(error);
      copyDirectory(sourceDir, canonicalPath);

      if (targetPath === canonicalPath) {
        return {
          success: true,
          dryRun: false,
          mode: 'copy',
          symlinkFailed: true,
          error: canonicalSymlinkError,
          ...plan,
        };
      }
    }
  } else {
    copyDirectory(sourceDir, canonicalPath);
  }

  if (targetPath === canonicalPath) {
    if (targetPath !== canonicalPath) {
      removePath(targetPath);
      copyDirectory(canonicalPath, targetPath);
    }

    return {
      success: true,
      dryRun: false,
      mode,
      ...plan,
    };
  }

  if (mode === 'copy') {
    removePath(targetPath);
    copyDirectory(canonicalPath, targetPath);

    return {
      success: true,
      dryRun: false,
      mode: 'copy',
      ...plan,
    };
  }

  removePath(targetPath);
  ensureDir(path.dirname(targetPath));

  try {
    const relativeTarget = path.relative(path.dirname(targetPath), canonicalPath);
    fs.symlinkSync(relativeTarget, targetPath, platform() === 'win32' ? 'junction' : undefined);

    return {
      success: true,
      dryRun: false,
      mode: canonicalSymlinkFailed ? 'copy' : 'symlink',
      ...(canonicalSymlinkFailed
        ? {
            symlinkFailed: true,
            error: canonicalSymlinkError,
          }
        : {}),
      ...plan,
    };
  } catch (error) {
    copyDirectory(canonicalPath, targetPath);
    return {
      success: true,
      dryRun: false,
      mode: 'copy',
      symlinkFailed: true,
      error: error instanceof Error ? error.message : String(error),
      ...plan,
    };
  }
}

import path from 'path';

export function sanitizeSkillName(name) {
  const sanitized = String(name || '')
    .toLowerCase()
    .replace(/[^a-z0-9._]+/g, '-')
    .replace(/^[.-]+|[.-]+$/g, '')
    .substring(0, 255);

  return sanitized || 'unnamed-skill';
}

export function isPathSafe(basePath, targetPath) {
  const normalizedBase = path.normalize(path.resolve(basePath));
  const normalizedTarget = path.normalize(path.resolve(targetPath));
  return normalizedTarget === normalizedBase || normalizedTarget.startsWith(`${normalizedBase}${path.sep}`);
}

export function assertPathSafe(basePath, targetPath, label = 'path') {
  if (!isPathSafe(basePath, targetPath)) {
    throw new Error(`Unsafe ${label}: ${targetPath}`);
  }
}

export function expandHomePath(input, homeDir) {
  if (!input) {
    return input;
  }

  if (input === '~') {
    return homeDir;
  }

  if (input.startsWith('~/')) {
    return path.join(homeDir, input.slice(2));
  }

  return input;
}

#!/usr/bin/env node

import fs from 'fs';
import path from 'path';
import { fileURLToPath } from 'url';

const __filename = fileURLToPath(import.meta.url);

function parseArgs(argv) {
  const options = {
    skillDir: '',
    installedPath: '',
    json: false,
  };

  for (let index = 0; index < argv.length; index += 1) {
    const arg = argv[index];
    if (arg === '--skill-dir') {
      options.skillDir = argv[index + 1] || '';
      index += 1;
      continue;
    }
    if (arg === '--installed-path') {
      options.installedPath = argv[index + 1] || '';
      index += 1;
      continue;
    }
    if (arg === '--json') {
      options.json = true;
    }
  }

  if (!options.skillDir) {
    throw new Error('Missing required --skill-dir');
  }

  return options;
}

function parseFrontmatter(content) {
  const match = content.match(/^---\n([\s\S]*?)\n---/);
  if (!match) {
    return {};
  }

  const frontmatter = match[1];
  const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
  const descriptionMatch = frontmatter.match(/^description:\s*(.+)$/m);

  return {
    name: nameMatch ? nameMatch[1].trim() : '',
    description: descriptionMatch ? descriptionMatch[1].trim() : '',
  };
}

function collectMissingReferences(skillDir, content) {
  const missing = [];
  const matches = content.matchAll(/\[[^\]]+\]\(([^)]+)\)/g);
  for (const match of matches) {
    const target = match[1];
    if (/^https?:/.test(target) || target.startsWith('#')) {
      continue;
    }
    const resolved = path.resolve(skillDir, target);
    if (!fs.existsSync(resolved)) {
      missing.push(target);
    }
  }
  return missing;
}

export function validateSkill({ skillDir, installedPath = '' }) {
  const resolvedSkillDir = path.resolve(skillDir);
  const skillFile = path.join(resolvedSkillDir, 'SKILL.md');
  const errors = [];

  if (!fs.existsSync(skillFile)) {
    errors.push('Missing SKILL.md');
    return { valid: false, errors, warnings: [] };
  }

  const content = fs.readFileSync(skillFile, 'utf8');
  const frontmatter = parseFrontmatter(content);
  if (!frontmatter.name) {
    errors.push('Missing frontmatter name');
  }
  if (!frontmatter.description) {
    errors.push('Missing frontmatter description');
  }

  const missingReferences = collectMissingReferences(resolvedSkillDir, content);
  for (const reference of missingReferences) {
    errors.push(`Missing referenced file: ${reference}`);
  }

  if (installedPath) {
    const resolvedInstalledPath = path.resolve(installedPath);
    if (!fs.existsSync(resolvedInstalledPath)) {
      errors.push(`Installed path not found: ${resolvedInstalledPath}`);
    } else if (!fs.existsSync(path.join(resolvedInstalledPath, 'SKILL.md'))) {
      errors.push(`Installed path missing SKILL.md: ${resolvedInstalledPath}`);
    }
  }

  return {
    valid: errors.length === 0,
    errors,
    warnings: [],
    frontmatter,
  };
}

function main() {
  const options = parseArgs(process.argv.slice(2));
  const result = validateSkill(options);

  if (options.json) {
    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
    if (!result.valid) {
      process.exit(1);
    }
    return;
  }

  if (!result.valid) {
    console.error('Skill validation failed');
    for (const error of result.errors) {
      console.error(`- ${error}`);
    }
    process.exit(1);
  }

  console.log('Skill validation passed');
}

if (process.argv[1] && path.resolve(process.argv[1]) === __filename) {
  try {
    main();
  } catch (error) {
    console.error(error.message);
    process.exit(1);
  }
}