vellum 0.2.14 → 0.3.2

package/src/config/skills.ts

@@ -1,972 +0,0 @@
-import { existsSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from 'node:fs';
-import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
-import Anthropic from '@anthropic-ai/sdk';
-import { getConfig } from './loader.js';
-import { getWorkspaceSkillsDir } from '../util/platform.js';
-import { getLogger } from '../util/logger.js';
-import { stripCommentLines } from './system-prompt.js';
-import { parseToolManifestFile } from '../skills/tool-manifest.js';
-import { computeSkillVersionHash } from '../skills/version-hash.js';
-
-const log = getLogger('skills');
-
-const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
-
-// ─── New interfaces for extended skill metadata ──────────────────────────────
-
-export interface VellumMetadata {
-  emoji?: string;
-  os?: string[];
-  requires?: SkillRequirements;
-  primaryEnv?: string;
-  install?: InstallerSpec[];
-}
-
-export interface SkillRequirements {
-  bins?: string[];
-  anyBins?: string[];
-  env?: string[];
-  config?: string[];
-}
-
-export interface InstallerSpec {
-  id: string;
-  kind: 'brew' | 'node' | 'go' | 'uv' | 'download';
-  [key: string]: unknown;
-}
-
-export type SkillSource = 'bundled' | 'managed' | 'workspace' | 'extra';
-
-// ─── Core interfaces ─────────────────────────────────────────────────────────
-
-export interface SkillSummary {
-  id: string;
-  name: string;
-  description: string;
-  directoryPath: string;
-  skillFilePath: string;
-  bundled?: boolean;
-  icon?: string;
-  emoji?: string;
-  homepage?: string;
-  userInvocable: boolean;
-  disableModelInvocation: boolean;
-  source: SkillSource;
-  metadata?: VellumMetadata;
-  /** Parsed tool manifest metadata, if the skill has a valid TOOLS.json. */
-  toolManifest?: SkillToolManifestMeta;
-  /** IDs of child skills that this skill includes (metadata-only, not auto-activated). */
-  includes?: string[];
-}
-
-export interface SkillDefinition extends SkillSummary {
-  body: string;
-}
-
-export interface SkillLookupResult {
-  skill?: SkillDefinition;
-  error?: string;
-}
-
-export interface SkillSelectorResult {
-  skill?: SkillSummary;
-  error?: string;
-}
-
-// ─── Skill Tool Manifest Types ────────────────────────────────────────────────
-
-/**
- * Schema for a skill's TOOLS.json manifest file.
- * Declares which tools a skill provides and how they should be executed.
- */
-export interface SkillToolManifest {
-  version: 1;
-  tools: SkillToolEntry[];
-}
-
-/**
- * A single tool entry within a skill's TOOLS.json manifest.
- */
-export interface SkillToolEntry {
-  /** Unique tool name (must not collide with core tool names). */
-  name: string;
-  /** Human-readable description shown to the model. */
-  description: string;
-  /** Tool category for grouping/display. */
-  category: string;
-  /** Default risk level for permission checks. */
-  risk: 'low' | 'medium' | 'high';
-  /** JSON Schema for the tool's input parameters. */
-  input_schema: Record<string, unknown>;
-  /** Relative path to the executor script within the skill directory. */
-  executor: string;
-  /** Where the tool script runs. */
-  execution_target: 'host' | 'sandbox';
-}
-
-/**
- * Lightweight metadata about a skill's tool manifest, attached to SkillSummary
- * without loading the full manifest at catalog time.
- */
-export interface SkillToolManifestMeta {
-  /** Whether the skill has a TOOLS.json file. */
-  present: boolean;
-  /** Whether the manifest parsed successfully. */
-  valid: boolean;
-  /** Number of tools declared in the manifest (0 if invalid). */
-  toolCount: number;
-  /** Tool names declared in the manifest (empty if invalid). */
-  toolNames: string[];
-  /**
-   * Deterministic content hash of the skill directory (`v1:<hex-sha256>`).
-   * Lazily computed on first access to avoid hashing every skill directory
-   * during catalog load.
-   */
-  versionHash?: string;
-}
-
-// ─── Requirements check ──────────────────────────────────────────────────────
-
-export interface RequirementsCheckResult {
-  eligible: boolean;
-  missing: {
-    bins?: string[];
-    env?: string[];
-  };
-}
-
-export function checkSkillRequirements(
-  skill: SkillSummary,
-  envOverrides?: Record<string, string>,
-): RequirementsCheckResult {
-  const vellum = skill.metadata;
-  if (!vellum) {
-    return { eligible: true, missing: {} };
-  }
-
-  const missingBins: string[] = [];
-  const missingEnv: string[] = [];
-
-  // OS check
-  if (vellum.os && vellum.os.length > 0) {
-    if (!vellum.os.includes(process.platform)) {
-      return {
-        eligible: false,
-        missing: {
-          bins: [`(unsupported platform: ${process.platform}, requires: ${vellum.os.join(', ')})`],
-        },
-      };
-    }
-  }
-
-  const requires = vellum.requires;
-  if (!requires) {
-    return { eligible: true, missing: {} };
-  }
-
-  // bins: all must exist
-  if (requires.bins) {
-    for (const bin of requires.bins) {
-      if (!Bun.which(bin)) {
-        missingBins.push(bin);
-      }
-    }
-  }
-
-  // anyBins: at least one must exist
-  if (requires.anyBins && requires.anyBins.length > 0) {
-    const hasAny = requires.anyBins.some((bin) => Bun.which(bin) !== null);
-    if (!hasAny) {
-      missingBins.push(`(one of: ${requires.anyBins.join(', ')})`);
-    }
-  }
-
-  // env: check process.env or envOverrides
-  if (requires.env) {
-    const env = envOverrides ? { ...process.env, ...envOverrides } : process.env;
-    for (const key of requires.env) {
-      if (!env[key]) {
-        missingEnv.push(key);
-      }
-    }
-  }
-
-  // config: skip for now (needs config integration from M2)
-
-  const missing: RequirementsCheckResult['missing'] = {};
-  if (missingBins.length > 0) missing.bins = missingBins;
-  if (missingEnv.length > 0) missing.env = missingEnv;
-
-  return {
-    eligible: missingBins.length === 0 && missingEnv.length === 0,
-    missing,
-  };
-}
-
-// ─── Helpers ─────────────────────────────────────────────────────────────────
-
-export function getSkillsDir(): string {
-  return getWorkspaceSkillsDir();
-}
-
-export function getBundledSkillsDir(): string {
-  return join(import.meta.dir, 'bundled-skills');
-}
-
-function getSkillsIndexPath(skillsDir: string): string {
-  return join(skillsDir, 'SKILLS.md');
-}
-
-// ─── Frontmatter parsing ─────────────────────────────────────────────────────
-
-interface ParsedFrontmatter {
-  name: string;
-  description: string;
-  body: string;
-  homepage?: string;
-  userInvocable: boolean;
-  disableModelInvocation: boolean;
-  metadata?: VellumMetadata;
-  includes?: string[];
-}
-
-function parseIncludes(raw: string | undefined, skillFilePath: string): string[] | undefined {
-  if (!raw) return undefined;
-
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(raw);
-  } catch (err) {
-    log.warn({ err, skillFilePath }, 'Failed to parse includes JSON in frontmatter');
-    return undefined;
-  }
-
-  if (!Array.isArray(parsed)) {
-    log.warn({ skillFilePath }, 'includes must be a JSON array');
-    return undefined;
-  }
-
-  if (!parsed.every((item: unknown) => typeof item === 'string')) {
-    log.warn({ skillFilePath }, 'includes must be an array of strings');
-    return undefined;
-  }
-
-  // Normalize: trim, remove empty strings, deduplicate preserving first-seen order
-  const seen = new Set<string>();
-  const result: string[] = [];
-  for (const item of parsed as string[]) {
-    const trimmed = item.trim();
-    if (trimmed.length === 0) continue;
-    if (seen.has(trimmed)) continue;
-    seen.add(trimmed);
-    result.push(trimmed);
-  }
-
-  return result.length > 0 ? result : undefined;
-}
-
-function parseFrontmatter(content: string, skillFilePath: string): ParsedFrontmatter | null {
-  const match = content.match(FRONTMATTER_REGEX);
-  if (!match) {
-    log.warn({ skillFilePath }, 'Skipping skill without YAML frontmatter');
-    return null;
-  }
-
-  const frontmatter = match[1];
-  const fields: Record<string, string> = {};
-  for (const line of frontmatter.split(/\r?\n/)) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith('#')) continue;
-    const separatorIndex = trimmed.indexOf(':');
-    if (separatorIndex === -1) continue;
-
-    const key = trimmed.slice(0, separatorIndex).trim();
-    let value = trimmed.slice(separatorIndex + 1).trim();
-    const isDoubleQuoted = value.startsWith('"') && value.endsWith('"');
-    const isSingleQuoted = value.startsWith('\'') && value.endsWith('\'');
-    if (isDoubleQuoted || isSingleQuoted) {
-      value = value.slice(1, -1);
-      if (isDoubleQuoted) {
-        // Unescape sequences produced by buildSkillMarkdown's esc().
-        // Only for double-quoted values — single-quoted YAML treats backslashes literally.
-        // Single-pass to avoid misinterpreting \\n (escaped backslash + n) as a newline.
-        value = value.replace(/\\(["\\nr])/g, (_, ch) => {
-          if (ch === 'n') return '\n';
-          if (ch === 'r') return '\r';
-          return ch; // handles \\ → \ and \" → "
-        });
-      }
-    }
-    fields[key] = value;
-  }
-
-  const name = fields.name?.trim();
-  const description = fields.description?.trim();
-  if (!name || !description) {
-    log.warn({ skillFilePath }, 'Skipping skill missing required frontmatter keys "name" and/or "description"');
-    return null;
-  }
-
-  // Parse new optional fields
-  const homepage = fields.homepage?.trim() || undefined;
-
-  const userInvocableRaw = fields['user-invocable']?.trim().toLowerCase();
-  const userInvocable = userInvocableRaw !== 'false';
-
-  const disableModelInvocationRaw = fields['disable-model-invocation']?.trim().toLowerCase();
-  const disableModelInvocation = disableModelInvocationRaw === 'true';
-
-  // Parse metadata as single-line JSON string, extract .vellum namespace
-  let metadata: VellumMetadata | undefined;
-  const metadataRaw = fields.metadata?.trim();
-  if (metadataRaw) {
-    try {
-      const parsed = JSON.parse(metadataRaw);
-      if (parsed && typeof parsed === 'object' && parsed.vellum) {
-        metadata = parsed.vellum as VellumMetadata;
-      }
-    } catch (err) {
-      log.warn({ err, skillFilePath }, 'Failed to parse metadata JSON in frontmatter');
-    }
-  }
-
-  const includes = parseIncludes(fields.includes, skillFilePath);
-
-  return {
-    name,
-    description,
-    body: stripCommentLines(content.slice(match[0].length)),
-    homepage,
-    userInvocable,
-    disableModelInvocation,
-    metadata,
-    includes,
-  };
-}
-
-// ─── Path utilities ──────────────────────────────────────────────────────────
-
-function getCanonicalPath(path: string): string {
-  return existsSync(path) ? realpathSync(path) : resolve(path);
-}
-
-function getRelativeToSkillsRoot(skillsDir: string, candidatePath: string): string {
-  return relative(getCanonicalPath(skillsDir), getCanonicalPath(candidatePath));
-}
-
-function isOutsideSkillsRoot(skillsDir: string, candidatePath: string): boolean {
-  const relativePath = getRelativeToSkillsRoot(skillsDir, candidatePath);
-  return relativePath.startsWith('..') || isAbsolute(relativePath);
-}
-
-// ─── Tool manifest detection ─────────────────────────────────────────────────
-
-/**
- * Create a SkillToolManifestMeta with a lazily-computed versionHash.
- * The hash is only computed when first accessed, avoiding the cost of
- * recursively hashing the skill directory during catalog load.
- */
-function createManifestMeta(
-  base: Omit<SkillToolManifestMeta, 'versionHash'>,
-  directoryPath: string,
-): SkillToolManifestMeta {
-  let cached: string | undefined;
-  let computed = false;
-  return Object.defineProperty({ ...base }, 'versionHash', {
-    get() {
-      if (!computed) {
-        computed = true;
-        try {
-          cached = computeSkillVersionHash(directoryPath);
-        } catch (err) {
-          log.warn({ err, directoryPath }, 'Failed to compute skill version hash');
-        }
-      }
-      return cached;
-    },
-    enumerable: true,
-    configurable: true,
-  });
-}
-
-/**
- * Detect and parse a TOOLS.json manifest in a skill directory.
- * Returns the manifest metadata if the file exists, or undefined if it doesn't.
- * On parse failure, returns a degraded metadata object (present but invalid).
- */
-function detectToolManifest(directoryPath: string): SkillToolManifestMeta | undefined {
-  const manifestPath = join(directoryPath, 'TOOLS.json');
-  if (!existsSync(manifestPath)) {
-    return undefined;
-  }
-
-  try {
-    const manifest = parseToolManifestFile(manifestPath);
-    return createManifestMeta({
-      present: true,
-      valid: true,
-      toolCount: manifest.tools.length,
-      toolNames: manifest.tools.map((t) => t.name),
-    }, directoryPath);
-  } catch (err) {
-    log.warn({ err, manifestPath }, 'Failed to parse TOOLS.json manifest');
-    return createManifestMeta({
-      present: true,
-      valid: false,
-      toolCount: 0,
-      toolNames: [],
-    }, directoryPath);
-  }
-}
-
-// ─── Skill reading ───────────────────────────────────────────────────────────
-
-function readSkillFromDirectory(directoryPath: string, skillsDir: string, source: SkillSource): SkillDefinition | null {
-  const skillFilePath = join(directoryPath, 'SKILL.md');
-  if (!existsSync(skillFilePath)) {
-    log.warn({ directoryPath }, 'Skipping skill directory without SKILL.md');
-    return null;
-  }
-
-  try {
-    if (isOutsideSkillsRoot(skillsDir, directoryPath)) {
-      log.warn({ directoryPath }, 'Skipping skill directory that resolves outside ~/.vellum/workspace/skills');
-      return null;
-    }
-
-    const stat = statSync(skillFilePath);
-    if (!stat.isFile()) {
-      log.warn({ skillFilePath }, 'Skipping skill path because SKILL.md is not a file');
-      return null;
-    }
-
-    if (isOutsideSkillsRoot(skillsDir, skillFilePath)) {
-      log.warn({ skillFilePath }, 'Skipping SKILL.md that resolves outside ~/.vellum/workspace/skills');
-      return null;
-    }
-
-    const content = readFileSync(skillFilePath, 'utf-8');
-    const parsed = parseFrontmatter(content, skillFilePath);
-    if (!parsed) return null;
-
-    return {
-      id: basename(directoryPath),
-      name: parsed.name,
-      description: parsed.description,
-      directoryPath,
-      skillFilePath,
-      body: parsed.body,
-      emoji: parsed.metadata?.emoji,
-      homepage: parsed.homepage,
-      userInvocable: parsed.userInvocable,
-      disableModelInvocation: parsed.disableModelInvocation,
-      source,
-      metadata: parsed.metadata,
-      toolManifest: detectToolManifest(directoryPath),
-      includes: parsed.includes,
-    };
-  } catch (err) {
-    log.warn({ err, skillFilePath }, 'Failed to read skill file');
-    return null;
-  }
-}
-
-function readBundledSkillFromDirectory(directoryPath: string): SkillDefinition | null {
-  const skillFilePath = join(directoryPath, 'SKILL.md');
-  if (!existsSync(skillFilePath)) {
-    log.warn({ directoryPath }, 'Skipping bundled skill directory without SKILL.md');
-    return null;
-  }
-
-  try {
-    const stat = statSync(skillFilePath);
-    if (!stat.isFile()) {
-      log.warn({ skillFilePath }, 'Skipping bundled skill path because SKILL.md is not a file');
-      return null;
-    }
-
-    const content = readFileSync(skillFilePath, 'utf-8');
-    const parsed = parseFrontmatter(content, skillFilePath);
-    if (!parsed) return null;
-
-    return {
-      id: basename(directoryPath),
-      name: parsed.name,
-      description: parsed.description,
-      directoryPath,
-      skillFilePath,
-      body: parsed.body,
-      bundled: true,
-      emoji: parsed.metadata?.emoji,
-      homepage: parsed.homepage,
-      userInvocable: parsed.userInvocable,
-      disableModelInvocation: parsed.disableModelInvocation,
-      source: 'bundled',
-      metadata: parsed.metadata,
-      toolManifest: detectToolManifest(directoryPath),
-      includes: parsed.includes,
-    };
-  } catch (err) {
-    log.warn({ err, skillFilePath }, 'Failed to read bundled skill file');
-    return null;
-  }
-}
-
-// ─── Skill discovery ─────────────────────────────────────────────────────────
-
-function discoverBundledSkillDirectories(): string[] {
-  const bundledDir = getBundledSkillsDir();
-  if (!existsSync(bundledDir)) return [];
-
-  const dirs: string[] = [];
-  try {
-    const entries = readdirSync(bundledDir, { withFileTypes: true });
-    for (const entry of entries) {
-      if (!entry.isDirectory()) continue;
-      const directoryPath = join(bundledDir, entry.name);
-      if (existsSync(join(directoryPath, 'SKILL.md'))) {
-        dirs.push(directoryPath);
-      }
-    }
-  } catch (err) {
-    log.warn({ err, bundledDir }, 'Failed to discover bundled skill directories');
-    return [];
-  }
-
-  return dirs.sort((a, b) => a.localeCompare(b));
-}
-
-function loadBundledSkills(): SkillSummary[] {
-  const directories = discoverBundledSkillDirectories();
-  const skills: SkillSummary[] = [];
-
-  for (const directory of directories) {
-    const skill = readBundledSkillFromDirectory(directory);
-    if (!skill) continue;
-
-    skills.push({
-      id: skill.id,
-      name: skill.name,
-      description: skill.description,
-      directoryPath: skill.directoryPath,
-      skillFilePath: skill.skillFilePath,
-      bundled: true,
-      emoji: skill.emoji,
-      homepage: skill.homepage,
-      userInvocable: skill.userInvocable,
-      disableModelInvocation: skill.disableModelInvocation,
-      source: 'bundled',
-      metadata: skill.metadata,
-      toolManifest: skill.toolManifest,
-      includes: skill.includes,
-    });
-  }
-
-  return skills;
-}
-
-// ─── Index parsing ───────────────────────────────────────────────────────────
-
-function parseIndexEntry(line: string): string | null {
-  const bulletMatch = line.trim().match(/^[-*]\s+(.+)$/);
-  if (!bulletMatch) return null;
-
-  let entry = bulletMatch[1].trim();
-  const markdownLinkMatch = entry.match(/^\[[^\]]+\]\(([^)]+)\)$/);
-  if (markdownLinkMatch) {
-    entry = markdownLinkMatch[1].trim();
-  }
-
-  if (entry.startsWith('`') && entry.endsWith('`')) {
-    entry = entry.slice(1, -1).trim();
-  }
-
-  return entry.length > 0 ? entry : null;
-}
-
-function resolveIndexEntryToDirectory(skillsDir: string, entry: string): string | null {
-  if (isAbsolute(entry)) {
-    log.warn({ entry }, 'Skipping SKILLS.md entry because absolute paths are not allowed');
-    return null;
-  }
-
-  const resolvedEntryPath = resolve(skillsDir, entry);
-  const resolvedDirectory = basename(resolvedEntryPath).toLowerCase() === 'skill.md'
-    ? dirname(resolvedEntryPath)
-    : resolvedEntryPath;
-
-  const relativePath = getRelativeToSkillsRoot(skillsDir, resolvedDirectory);
-  if (relativePath.length === 0) {
-    log.warn({ entry }, 'Skipping SKILLS.md entry that resolves to the skills root');
-    return null;
-  }
-  if (isOutsideSkillsRoot(skillsDir, resolvedDirectory)) {
-    log.warn(
-      { entry, resolvedDirectory: getCanonicalPath(resolvedDirectory) },
-      'Skipping SKILLS.md entry that resolves outside ~/.vellum/workspace/skills',
-    );
-    return null;
-  }
-
-  return resolvedDirectory;
-}
-
-function getIndexedSkillDirectories(skillsDir: string): string[] | null {
-  const indexPath = getSkillsIndexPath(skillsDir);
-  if (!existsSync(indexPath)) return null;
-
-  let rawIndex = '';
-  try {
-    rawIndex = readFileSync(indexPath, 'utf-8');
-  } catch (err) {
-    log.warn({ err, indexPath }, 'Failed to read SKILLS.md; treating as empty catalog');
-    return [];
-  }
-
-  const directories: string[] = [];
-  const seen = new Set<string>();
-
-  for (const line of rawIndex.split(/\r?\n/)) {
-    const parsedEntry = parseIndexEntry(line);
-    if (!parsedEntry) continue;
-
-    const directory = resolveIndexEntryToDirectory(skillsDir, parsedEntry);
-    if (!directory || seen.has(directory)) continue;
-
-    seen.add(directory);
-    directories.push(directory);
-  }
-
-  return directories;
-}
-
-function discoverSkillDirectories(skillsDir: string): string[] {
-  if (!existsSync(skillsDir)) return [];
-
-  const dirs: string[] = [];
-  try {
-    const entries = readdirSync(skillsDir, { withFileTypes: true });
-    for (const entry of entries) {
-      if (!entry.isDirectory()) continue;
-      const directoryPath = join(skillsDir, entry.name);
-      if (existsSync(join(directoryPath, 'SKILL.md'))) {
-        dirs.push(directoryPath);
-      }
-    }
-  } catch (err) {
-    log.warn({ err, skillsDir }, 'Failed to discover skill directories');
-    return [];
-  }
-
-  return dirs.sort((a, b) => a.localeCompare(b));
-}
-
-// ─── Catalog loading ─────────────────────────────────────────────────────────
-
-function skillSummaryFromDefinition(skill: SkillDefinition, source: SkillSource): SkillSummary {
-  return {
-    id: skill.id,
-    name: skill.name,
-    description: skill.description,
-    directoryPath: skill.directoryPath,
-    skillFilePath: skill.skillFilePath,
-    bundled: skill.bundled,
-    emoji: skill.emoji,
-    homepage: skill.homepage,
-    userInvocable: skill.userInvocable,
-    disableModelInvocation: skill.disableModelInvocation,
-    source,
-    metadata: skill.metadata,
-    toolManifest: skill.toolManifest,
-    includes: skill.includes,
-  };
-}
-
-export function loadSkillCatalog(workspaceSkillsDir?: string, extraDirs?: string[]): SkillSummary[] {
-  const catalog: SkillSummary[] = [];
-  const seenIds = new Set<string>();
-
-  // Load extra directories first (lowest precedence, before bundled)
-  if (extraDirs) {
-    for (const dir of extraDirs) {
-      if (!existsSync(dir)) continue;
-      const dirs = discoverSkillDirectories(dir);
-      for (const directory of dirs) {
-        const skillFilePath = join(directory, 'SKILL.md');
-        if (!existsSync(skillFilePath)) continue;
-
-        try {
-          const stat = statSync(skillFilePath);
-          if (!stat.isFile()) continue;
-
-          const content = readFileSync(skillFilePath, 'utf-8');
-          const parsed = parseFrontmatter(content, skillFilePath);
-          if (!parsed) continue;
-
-          const id = basename(directory);
-          if (seenIds.has(id)) {
-            log.warn({ id, directory }, 'Skipping duplicate skill id from extraDirs');
-            continue;
-          }
-
-          seenIds.add(id);
-          catalog.push({
-            id,
-            name: parsed.name,
-            description: parsed.description,
-            directoryPath: directory,
-            skillFilePath,
-            emoji: parsed.metadata?.emoji,
-            homepage: parsed.homepage,
-            userInvocable: parsed.userInvocable,
-            disableModelInvocation: parsed.disableModelInvocation,
-            source: 'extra',
-            metadata: parsed.metadata,
-            toolManifest: detectToolManifest(directory),
-            includes: parsed.includes,
-          });
-        } catch (err) {
-          log.warn({ err, directory }, 'Failed to read skill from extraDirs');
-        }
-      }
-    }
-  }
-
-  // Load bundled skills (override extraDirs skills with same ID)
-  const bundledSkills = loadBundledSkills();
-  for (const skill of bundledSkills) {
-    if (seenIds.has(skill.id)) {
-      // Bundled wins over extraDirs
-      const existingIndex = catalog.findIndex((s) => s.id === skill.id);
-      if (existingIndex !== -1 && catalog[existingIndex].source === 'extra') {
-        log.info({ id: skill.id, directory: skill.directoryPath }, 'Bundled skill overrides extraDirs skill');
-        catalog[existingIndex] = skill;
-        continue;
-      }
-      log.warn({ id: skill.id, directory: skill.directoryPath }, 'Skipping duplicate bundled skill id');
-      continue;
-    }
-    seenIds.add(skill.id);
-    catalog.push(skill);
-  }
-
-  // Load managed (user) skills, which take precedence over bundled skills with the same ID
-  const skillsDir = getSkillsDir();
-  const indexedDirectories = getIndexedSkillDirectories(skillsDir);
-  const directories = indexedDirectories ?? discoverSkillDirectories(skillsDir);
-
-  for (const directory of directories) {
-    const skill = readSkillFromDirectory(directory, skillsDir, 'managed');
-    if (!skill) continue;
-
-    if (seenIds.has(skill.id)) {
-      // If the existing entry is bundled, the user skill overrides it
-      const existingIndex = catalog.findIndex((s) => s.id === skill.id);
-      if (existingIndex !== -1 && (catalog[existingIndex].bundled || catalog[existingIndex].source === 'extra')) {
-        log.info({ id: skill.id, directory }, 'User skill overrides bundled skill');
-        catalog[existingIndex] = skillSummaryFromDefinition(skill, 'managed');
-        continue;
-      }
-      log.warn({ id: skill.id, directory }, 'Skipping duplicate skill id');
-      continue;
-    }
-
-    seenIds.add(skill.id);
-    catalog.push(skillSummaryFromDefinition(skill, 'managed'));
-  }
-
-  // Load workspace skills with highest precedence
-  if (workspaceSkillsDir && existsSync(workspaceSkillsDir)) {
-    const workspaceDirs = discoverSkillDirectories(workspaceSkillsDir);
-
-    for (const directory of workspaceDirs) {
-      const skillFilePath = join(directory, 'SKILL.md');
-      if (!existsSync(skillFilePath)) continue;
-
-      try {
-        const stat = statSync(skillFilePath);
-        if (!stat.isFile()) continue;
-
-        const content = readFileSync(skillFilePath, 'utf-8');
-        const parsed = parseFrontmatter(content, skillFilePath);
-        if (!parsed) continue;
-
-        const id = basename(directory);
-        const workspaceSkill: SkillSummary = {
-          id,
-          name: parsed.name,
-          description: parsed.description,
-          directoryPath: directory,
-          skillFilePath,
-          emoji: parsed.metadata?.emoji,
-          homepage: parsed.homepage,
-          userInvocable: parsed.userInvocable,
-          disableModelInvocation: parsed.disableModelInvocation,
-          source: 'workspace',
-          metadata: parsed.metadata,
-          toolManifest: detectToolManifest(directory),
-          includes: parsed.includes,
-        };
-
-        if (seenIds.has(id)) {
-          // Workspace skills override any existing skill
-          const existingIndex = catalog.findIndex((s) => s.id === id);
-          if (existingIndex !== -1) {
-            log.info({ id, directory }, 'Workspace skill overrides existing skill');
-            catalog[existingIndex] = workspaceSkill;
-            continue;
-          }
-        }
-
-        seenIds.add(id);
-        catalog.push(workspaceSkill);
-      } catch (err) {
-        log.warn({ err, directory }, 'Failed to read workspace skill');
-      }
-    }
-  }
-
-  return catalog;
-}
-
-function loadSkillDefinition(skill: SkillSummary): SkillLookupResult {
-  let loaded: SkillDefinition | null;
-  if (skill.bundled) {
-    loaded = readBundledSkillFromDirectory(skill.directoryPath);
-  } else if (skill.source === 'workspace') {
-    // Workspace skills live outside ~/.vellum/workspace/skills, so use their parent
-    // directory as the root to avoid the isOutsideSkillsRoot rejection.
-    loaded = readSkillFromDirectory(skill.directoryPath, dirname(skill.directoryPath), skill.source);
-  } else {
-    loaded = readSkillFromDirectory(skill.directoryPath, getSkillsDir(), skill.source);
-  }
-  if (!loaded) {
-    return { error: `Failed to load SKILL.md for "${skill.id}"` };
-  }
-  // Replace {baseDir} placeholders with the actual skill directory path
-  loaded.body = loaded.body.replaceAll('{baseDir}', loaded.directoryPath);
-  return { skill: loaded };
-}
-
-export function resolveSkillSelector(selector: string, workspaceSkillsDir?: string): SkillSelectorResult {
-  const needle = selector.trim();
-  if (!needle) {
-    return { error: 'Skill selector is required and must be a non-empty string.' };
-  }
-
-  const catalog = loadSkillCatalog(workspaceSkillsDir);
-  if (catalog.length === 0) {
-    return { error: 'No skills are available. Configure ~/.vellum/workspace/skills/SKILLS.md or add skill directories.' };
-  }
-
-  const exactIdMatch = catalog.find((skill) => skill.id === needle);
-  if (exactIdMatch) {
-    return { skill: exactIdMatch };
-  }
-
-  const exactNameMatches = catalog.filter(
-    (skill) => skill.name.toLowerCase() === needle.toLowerCase(),
-  );
-  if (exactNameMatches.length === 1) {
-    return { skill: exactNameMatches[0] };
-  }
-  if (exactNameMatches.length > 1) {
-    const ids = exactNameMatches.map((skill) => skill.id).join(', ');
-    return { error: `Ambiguous skill name "${needle}". Matching IDs: ${ids}` };
-  }
-
-  const idPrefixMatches = catalog.filter((skill) => skill.id.startsWith(needle));
-  if (idPrefixMatches.length === 1) {
-    return { skill: idPrefixMatches[0] };
-  }
-  if (idPrefixMatches.length > 1) {
-    const ids = idPrefixMatches.map((skill) => skill.id).join(', ');
-    return { error: `Ambiguous skill id prefix "${needle}". Matching IDs: ${ids}` };
-  }
-
-  const knownSkills = catalog.map((skill) => skill.id).join(', ');
-  return { error: `No skill matched "${needle}". Available skills: ${knownSkills}` };
-}
-
-export function loadSkillBySelector(selector: string, workspaceSkillsDir?: string): SkillLookupResult {
-  const resolved = resolveSkillSelector(selector, workspaceSkillsDir);
-  if (!resolved.skill) {
-    return { error: resolved.error ?? 'Failed to resolve skill selector.' };
-  }
-  return loadSkillDefinition(resolved.skill);
-}
-
-// ─── Icon generation ─────────────────────────────────────────────────────────
-
-async function generateSkillIcon(name: string, description: string): Promise<string> {
-  const config = getConfig();
-  const apiKey = config.apiKeys.anthropic ?? process.env.ANTHROPIC_API_KEY;
-  if (!apiKey) {
-    throw new Error('No Anthropic API key available for icon generation');
-  }
-
-  const client = new Anthropic({ apiKey });
-  const response = await client.messages.create({
-    model: 'claude-haiku-4-5-20251001',
-    max_tokens: 1024,
-    system: 'You are a pixel art icon designer. When asked, return ONLY a single <svg> element — no explanation, no markdown, no code fences. The SVG must be a 16x16 grid pixel art icon using <rect> elements. Use a limited palette (3-5 colors). Keep it under 2KB. The viewBox should be "0 0 16 16" with each pixel being a 1x1 rect.',
-    messages: [{
-      role: 'user',
-      content: `Create a 16x16 pixel art SVG icon representing this skill:\nName: ${name}\nDescription: ${description}`,
-    }],
-  });
-
-  const text = response.content
-    .filter((block): block is Anthropic.TextBlock => block.type === 'text')
-    .map((block) => block.text)
-    .join('');
-
-  const svgMatch = text.match(/<svg[\s\S]*<\/svg>/i);
-  if (!svgMatch) {
-    throw new Error('No <svg> element found in response');
-  }
-
-  return svgMatch[0];
-}
-
-/**
- * Synchronously read a cached icon if it exists on disk. Returns undefined if not cached yet.
- */
-export function readCachedSkillIcon(directoryPath: string): string | undefined {
-  const iconPath = join(directoryPath, 'icon.svg');
-  if (existsSync(iconPath)) {
-    try {
-      return readFileSync(iconPath, 'utf-8');
-    } catch {
-      return undefined;
-    }
-  }
-  return undefined;
-}
-
-export async function ensureSkillIcon(directoryPath: string, name: string, description: string): Promise<string | undefined> {
-  const iconPath = join(directoryPath, 'icon.svg');
-
-  if (existsSync(iconPath)) {
-    try {
-      return readFileSync(iconPath, 'utf-8');
-    } catch {
-      log.warn({ iconPath }, 'Failed to read existing icon.svg');
-      return undefined;
-    }
-  }
-
-  try {
-    const svg = await generateSkillIcon(name, description);
-    try {
-      writeFileSync(iconPath, svg, 'utf-8');
-      log.info({ iconPath }, 'Generated skill icon');
-    } catch (writeErr) {
-      log.warn({ err: writeErr, iconPath }, 'Failed to cache icon.svg (returning generated icon anyway)');
-    }
-    return svg;
-  } catch (err) {
-    log.warn({ err, iconPath }, 'Failed to generate skill icon');
-    return undefined;
-  }
-}