Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

24.3 KB
Raw Blame
import { existsSync, readFileSync, readdirSync, mkdirSync, writeFileSync, rmSync, unlinkSync, renameSync } from 'node:fs';
import { createHash } from 'node:crypto';
import { join, resolve, sep } from 'node:path';
import { homedir } from 'node:os';
import { parse as parseYaml } from 'yaml';
import { getMercuryHome } from '../utils/config.js';
import type { SkillDiscovery, Skill, SkillMeta } from './types.js';
import { recordSelfMadeUse, SELF_MADE_CATEGORY, SELF_MADE_LABEL } from './self-made.js';
import { IntentRouter } from './intent-router.js';
import { logger } from '../utils/logger.js';
import { DEFAULT_SKILL_SEEDS, PREVIOUS_SEED_CONTENTS, RETIRED_SEEDS, getCategoryLabel } from './default-skills.js';

/**
 * The web-search skill dir holds a skill that tells the model to fetch a
 * search engine's HTML results page and never mentions the web_search tool.
 * Those pages answer automated requests with a bot challenge, so such a
 * skill only ever returns nothing.
 */
export function isBrokenSearchSkill(dirName: string, content: string): boolean {
  if (dirName !== 'web-search') return false;
  if (/\bweb_search\b/.test(content)) return false;
  return /(html|lite)\.duckduckgo\.com|duckduckgo\.com\/html|google\.[a-z.]+\/search\?|bing\.com\/search\?q=/i.test(content);
}

const SKILL_FILE = 'SKILL.md';
/** Which built-in skills were installed once (see ensureDefaultSkills). */
const SEEDED_FILE = '.seeded-defaults.json';
const DISABLED_FILE = '.disabled';

/**
 * Skill folders other agents share: `~/.agents/skills` (the cross-agent
 * standard that `npx skills add` installs into) and `~/.claude/skills`.
 * Skills there (HyperFrames, for one) are usable by name in Mercury too,
 * read-only. Mercury's own skills win on a name clash. Off with
 * MERCURY_SHARED_SKILLS=0.
 */
export function sharedSkillDirs(home = homedir()): string[] {
  if (process.env.MERCURY_SHARED_SKILLS === '0') return [];
  return [join(home, '.agents', 'skills'), join(home, '.claude', 'skills')];
}

/** A shared skill's description for the always-sent list: its first sentence, short. */
function briefDescription(d: string, max = 160): string {
  const t = d.replace(/\s+/g, ' ').trim();
  const first = /^(.{20,}?[.!?])(\s|$)/.exec(t)?.[1] ?? t;
  return first.length <= max ? first : `${first.slice(0, max - 1).replace(/\s+\S*$/, '')}…`;
}

function parseSkillMd(content: string): { meta: SkillMeta; instructions: string } | null {
  const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/);
  if (!fmMatch) return null;

  try {
    const meta = parseYaml(fmMatch[1]) as SkillMeta;
    const instructions = fmMatch[2].trim();
    if (!meta.name || !meta.description) {
      logger.warn({ meta }, 'SKILL.md missing required fields (name, description)');
      return null;
    }
    return { meta, instructions };
  } catch (err) {
    logger.warn({ err }, 'Failed to parse SKILL.md frontmatter');
    return null;
  }
}

export class SkillLoader {
  private skillsDir: string;
  /** Additional read-only skill roots (e.g. a bot's own skills dir). Own-dir entries load after the primary dir, so they win on name collision. */
  private extraDirs: string[];
  /** Folders other agents share (sharedSkillDirs): read before the primary dir, so Mercury's own skills win. */
  private sharedDirs: string[];
  private sharedPaths = new Set<string>();
  private seedDefaults: boolean;
  private discovered: Map<string, SkillDiscovery> = new Map();
  private loaded: Map<string, Skill> = new Map();
  readonly intentRouter: IntentRouter;

  constructor(skillsDir?: string, options?: { extraDirs?: string[]; seedDefaults?: boolean; sharedDirs?: string[] }) {
    this.skillsDir = skillsDir || join(getMercuryHome(), 'skills');
    this.extraDirs = options?.extraDirs ?? [];
    // Only the owner's own loader reads shared folders (not bots, not a custom root).
    this.sharedDirs = options?.sharedDirs ?? (skillsDir ? [] : sharedSkillDirs());
    this.seedDefaults = options?.seedDefaults !== false;
    this.intentRouter = new IntentRouter();
  }

  discover(): SkillDiscovery[] {
    this.discovered.clear();
    this.loaded.clear();
    if (!existsSync(this.skillsDir)) {
      if (!this.seedDefaults) return [];
      mkdirSync(this.skillsDir, { recursive: true });
      this.seedTemplate();
    }

    if (this.seedDefaults) {
      this.retireOldDefaults();
      this.ensureDefaultSkills();
    }

    // Walk both layouts:
    //   - flat:   <skillsDir>/<name>/SKILL.md            (legacy + user-authored)
    //   - nested: <skillsDir>/<category>/<slug>/SKILL.md (mercury skills install)
    // User-installed nested skills win over flat ones on name collision (registered last).
    const skillPaths = this.findSkillFiles();
    const parsedSkills: Array<{ meta: SkillMeta; path: string }> = [];
    for (const skillPath of skillPaths) {
      try {
        const raw = readFileSync(skillPath, 'utf-8');
        const parsed = parseSkillMd(raw);
        if (!parsed) continue;
        this.discovered.set(parsed.meta.name, {
          name: parsed.meta.name,
          description: parsed.meta.description,
          ...(this.sharedPaths.has(skillPath) ? { shared: true } : {}),
        });
        parsedSkills.push({ meta: parsed.meta, path: skillPath });
      } catch (err) {
        logger.warn({ path: skillPath, err }, 'Failed to load skill');
      }
    }

    // Reset the router with the bare list first, then enrich every entry with
    // its category, intents and tags. (The other order wiped the metadata on
    // every scan, so grouping and intent routing silently fell back to names.)
    this.intentRouter.buildIndex([...this.discovered.values()]);
    for (const { meta, path } of parsedSkills) {
      this.intentRouter.registerSkillMeta(meta);
      logger.info({ skill: meta.name, path, category: meta.category, intents: meta.intents?.length }, 'Skill discovered');
    }

    return [...this.discovered.values()];
  }

  load(name: string): Skill | null {
    const cached = this.loaded.get(name);
    if (cached) return cached;

    const skillPaths = this.findSkillFiles();
    let lastMatch: Skill | null = null;
    for (const skillPath of skillPaths) {
      try {
        const raw = readFileSync(skillPath, 'utf-8');
        const parsed = parseSkillMd(raw);
        if (!parsed || parsed.meta.name !== name) continue;

        const skillDir = join(skillPath, '..');
        const skill: Skill = {
          ...parsed.meta,
          instructions: parsed.instructions,
          dir: skillDir,
          ...(this.sharedPaths.has(skillPath) ? { shared: true } : {}),
          scriptsDir: existsSync(join(skillDir, 'scripts')) ? join(skillDir, 'scripts') : undefined,
          referencesDir: existsSync(join(skillDir, 'references')) ? join(skillDir, 'references') : undefined,
        };
        // Nested wins over flat — keep walking and prefer the deepest match.
        lastMatch = skill;
      } catch (err) {
        logger.warn({ err, name }, 'Failed to load skill');
      }
    }
    if (lastMatch) {
      this.loaded.set(name, lastMatch);
      return lastMatch;
    }
    return null;
  }

  /**
   * Walk the skills directory and return absolute paths to every SKILL.md found,
   * supporting both flat (<dir>/SKILL.md) and nested (<category>/<slug>/SKILL.md)
   * layouts. Skips directories starting with "_" and any tree containing a
   * `.disabled` marker.
   */
  private findSkillFiles(): string[] {
    const out: string[] = [];
    // Shared first: later entries win on a name clash, so Mercury's own skills override.
    for (const dir of this.sharedDirs) {
      const before = out.length;
      this.findSkillFilesIn(dir, out);
      for (const p of out.slice(before)) this.sharedPaths.add(p);
    }
    // The same skill in two shared folders (~/.agents and ~/.claude): keep one.
    const seen = new Set<string>();
    for (let i = out.length - 1; i >= 0; i--) {
      const name = out[i].split(sep).slice(-2, -1)[0];
      if (seen.has(name)) out.splice(i, 1); else seen.add(name);
    }
    for (const dir of [this.skillsDir, ...this.extraDirs]) {
      this.findSkillFilesIn(dir, out);
    }
    return out;
  }

  /** The discovered skill closest to a name the user or model wrote ("hyperframe", "Hyper Frames"). */
  closest(name: string): string | null {
    const sq = (s: string) => s.toLowerCase().replace(/[\s._-]+/g, '').replace(/s$/, '');
    const n = sq(name);
    if (n.length < 3) return null;
    const names = [...this.discovered.keys()];
    return names.find((k) => sq(k) === n)
      ?? names.filter((k) => sq(k).startsWith(n) || n.startsWith(sq(k))).sort((a, b) => a.length - b.length)[0]
      ?? null;
  }

  /** Walk one skills root (flat + one nested category level), appending SKILL.md paths. */
  private findSkillFilesIn(skillsDir: string, out: string[]): string[] {
    if (!existsSync(skillsDir)) return out;

    for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
      if (!entry.isDirectory() || entry.name.startsWith('_') || entry.name.startsWith('.')) continue;
      const dir = join(skillsDir, entry.name);
      if (existsSync(join(dir, DISABLED_FILE))) continue;

      const flat = join(dir, SKILL_FILE);
      if (existsSync(flat)) {
        out.push(flat);
        continue;
      }
      // Treat as category folder: look one level deeper for <slug>/SKILL.md.
      let children: import('node:fs').Dirent[] = [];
      try {
        children = readdirSync(dir, { withFileTypes: true });
      } catch { continue; }
      for (const child of children) {
        if (!child.isDirectory() || child.name.startsWith('_') || child.name.startsWith('.')) continue;
        const childDir = join(dir, child.name);
        if (existsSync(join(childDir, DISABLED_FILE))) continue;
        const nested = join(childDir, SKILL_FILE);
        if (existsSync(nested)) out.push(nested);
      }
    }
    return out;
  }

  getDiscovered(): SkillDiscovery[] {
    return [...this.discovered.values()];
  }

  /** The primary skills root (where self-made skills are written). */
  rootDir(): string {
    return this.skillsDir;
  }

  /** Count a use of a self-made skill (no-op for curated ones). */
  noteUse(name: string): void {
    recordSelfMadeUse(this.skillsDir, name);
  }

  getSkillSummariesText(): string {
    const skills = this.getDiscovered();
    if (skills.length === 0) return '';
    const sharedNames = new Set(skills.filter((s) => s.shared).map((s) => s.name));
    const own = skills.filter((s) => !s.shared);

    // Group skills by category using IntentRouter
    const categories = this.intentRouter.getAllCategories();
    const hasCategories = categories.size > 0;

    let text = '**Available Skills** (invoke with the `use_skill` tool):\n';

    if (hasCategories && categories.size > 1) {
      // Group by category. A skill in several categories is listed once,
      // under the first (every line here is re-sent with each request).
      const listed = new Set<string>();
      for (const [category, catSkills] of categories) {
        const fresh = catSkills.filter((s) => !listed.has(s.name) && !sharedNames.has(s.name));
        if (fresh.length === 0) continue;
        const label = category === SELF_MADE_CATEGORY ? SELF_MADE_LABEL : getCategoryLabel(category);
        text += `\n**${label}:**\n`;
        for (const s of fresh) {
          listed.add(s.name);
          const discovered = this.discovered.get(s.name);
          const desc = discovered?.description || s.description;
          text += `- ${s.name}: ${desc}\n`;
        }
      }
    } else {
      // Flat list (no categorization or only one category)
      text += own.map(s => `- ${s.name}: ${s.description}`).join('\n');
    }

    // Skills other agents share, compactly: a family (hyperframes, hyperframes-core, …) is one line.
    const shared = skills.filter((s) => s.shared).sort((a, b) => a.name.localeCompare(b.name));
    if (shared.length) {
      text += '\n\n**Shared skills** (installed for other agents too; load the same way):\n';
      const children = new Map<string, string[]>();
      const heads = shared.filter((s) => !shared.some((p) => p !== s && s.name.startsWith(`${p.name}-`)));
      for (const s of shared) {
        const head = heads.find((h) => h !== s && s.name.startsWith(`${h.name}-`));
        if (head) children.set(head.name, [...(children.get(head.name) ?? []), s.name]);
      }
      for (const h of heads) {
        const kids = children.get(h.name);
        text += `- ${h.name}: ${briefDescription(h.description)}${kids?.length ? ` (with ${kids.join(', ')})` : ''}\n`;
      }
    }

    // Skills are optional procedures, never a gate in front of the answer
    // (ADR-039). These lines used to say "you MUST invoke the web-search
    // skill immediately" and "MUST invoke tweet-notifier", which pulled every
    // model toward a skill even for local questions ("which Docker
    // containers are running?").
    const hasWebSearchSkill = skills.some(s => s.name === 'web-search');
    if (hasWebSearchSkill) {
      text += '\n\n**Current information:** for news, prices or anything newer than your training data, look it up '
        + '(the web_search tool, or the `web-search` skill when you want its full procedure) instead of answering from memory. '
        + 'Questions about this computer, its files or programs are not web questions.';
    }

    text += '\n\n**Using skills** — When a request clearly matches a skill, invoke it via `use_skill`. '
      + 'A skill is optional help, not a requirement: if none fits, just do the task. '
      + 'If the request could match several skills equally, pick the best fit or ask with `ask_user`. '
      + 'A message that starts with `#skill-name` means the user already picked that skill.'
      + '\n\n**When the user names a skill, tool or service** ("use hyperframes", "with ElevenLabs", "render it with Remotion"), that is the method: '
      + 'load the skill whose name matches, even written loosely ("hyperframe", "hyper frames"), follow it to the finished file (render it, don\'t stop at the source), '
      + 'and pass the named service to the media tools. Never swap in a different method (an AI video model for a HyperFrames render, Google for ElevenLabs) on your own: '
      + 'if the named one isn\'t available or fails, say so and ask. It holds for the rest of the chat, not only the message that named it.';

    return text;
  }

  saveSkill(name: string, content: string): string {
    const skillDir = this.resolveSkillDir(name);
    if (!existsSync(skillDir)) {
      mkdirSync(skillDir, { recursive: true });
    }
    writeFileSync(join(skillDir, SKILL_FILE), content, 'utf-8');
    const disabledPath = join(skillDir, DISABLED_FILE);
    if (existsSync(disabledPath)) {
      unlinkSync(disabledPath);
    }
    logger.info({ skill: name }, 'Skill saved');
    this.discover();
    return skillDir;
  }

  /**
   * Resolve a skill name to its directory inside the skills root. Rejects
   * empty names and names that escape the root (absolute paths, `..`
   * traversal), so a remote SKILL.md frontmatter `name` cannot cause writes
   * outside `skillsDir`.
   */
  private resolveSkillDir(name: string): string {
    const trimmed = (name ?? '').trim();
    const root = resolve(this.skillsDir);
    const candidate = resolve(root, trimmed);
    if (!trimmed || candidate === root || !candidate.startsWith(root + sep)) {
      throw new Error(`Invalid skill name ${JSON.stringify(name)}: resolves outside the skills root`);
    }
    return candidate;
  }

  getAllSkills(): Array<SkillDiscovery & { active: boolean }> {
    const list: Array<SkillDiscovery & { active: boolean }> = [];
    if (!existsSync(this.skillsDir)) return list;

    // Include disabled too — walk both layouts but don't honor .disabled here.
    const candidates = this.walkAllSkillPaths();
    for (const { skillPath, disabled } of candidates) {
      try {
        const raw = readFileSync(skillPath, 'utf-8');
        const parsed = parseSkillMd(raw);
        if (!parsed) continue;
        list.push({
          name: parsed.meta.name,
          description: parsed.meta.description,
          ...(parsed.meta.category ? { category: parsed.meta.category } : {}),
          active: !disabled,
        });
      } catch (err) {
        logger.warn({ err, path: skillPath }, 'Failed to read skill metadata');
      }
    }

    return list.sort((a, b) => a.name.localeCompare(b.name));
  }

  setSkillActive(name: string, active: boolean): boolean {
    const entry = this.findSkillEntryByName(name);
    if (!entry) return false;
    const disabledPath = join(entry.skillDir, DISABLED_FILE);
    if (active) {
      if (existsSync(disabledPath)) unlinkSync(disabledPath);
    } else {
      writeFileSync(disabledPath, 'disabled\n', 'utf-8');
    }
    this.discover();
    return true;
  }

  deleteSkill(name: string): boolean {
    const entry = this.findSkillEntryByName(name);
    if (!entry) return false;
    rmSync(entry.skillDir, { recursive: true, force: true });
    this.discover();
    logger.info({ skill: name }, 'Skill deleted');
    return true;
  }

  async installFromUrl(url: string): Promise<{ name: string; skillDir: string }> {
    const response = await fetch(url);
    if (!response.ok) {
      throw new Error(`Failed to fetch skill from URL: ${response.status} ${response.statusText}`);
    }
    const content = await response.text();
    return this.installFromContent(content);
  }

  installFromContent(content: string): { name: string; skillDir: string } {
    const parsed = parseSkillMd(content);
    if (!parsed) {
      throw new Error('Invalid SKILL.md: missing or malformed YAML frontmatter with name and description');
    }
    const skillDir = this.saveSkill(parsed.meta.name, content);
    return { name: parsed.meta.name, skillDir };
  }

  private findSkillEntryByName(name: string): { skillDir: string } | null {
    if (!existsSync(this.skillsDir)) return null;
    const candidates = this.walkAllSkillPaths();
    let lastMatch: string | null = null;
    for (const { skillPath } of candidates) {
      try {
        const raw = readFileSync(skillPath, 'utf-8');
        const parsed = parseSkillMd(raw);
        if (parsed?.meta.name === name) {
          lastMatch = join(skillPath, '..');
        }
      } catch {
        continue;
      }
    }
    return lastMatch ? { skillDir: lastMatch } : null;
  }

  /** Like findSkillFiles, but also returns disabled entries (used by getAllSkills). */
  private walkAllSkillPaths(): Array<{ skillPath: string; disabled: boolean }> {
    const out: Array<{ skillPath: string; disabled: boolean }> = [];
    if (!existsSync(this.skillsDir)) return out;
    for (const entry of readdirSync(this.skillsDir, { withFileTypes: true })) {
      if (!entry.isDirectory() || entry.name.startsWith('_') || entry.name.startsWith('.')) continue;
      const dir = join(this.skillsDir, entry.name);
      const flat = join(dir, SKILL_FILE);
      if (existsSync(flat)) {
        out.push({ skillPath: flat, disabled: existsSync(join(dir, DISABLED_FILE)) });
        continue;
      }
      let children: import('node:fs').Dirent[] = [];
      try { children = readdirSync(dir, { withFileTypes: true }); } catch { continue; }
      for (const child of children) {
        if (!child.isDirectory() || child.name.startsWith('_') || child.name.startsWith('.')) continue;
        const childDir = join(dir, child.name);
        const nested = join(childDir, SKILL_FILE);
        if (existsSync(nested)) {
          out.push({ skillPath: nested, disabled: existsSync(join(childDir, DISABLED_FILE)) });
        }
      }
    }
    return out;
  }

  private seedTemplate(): void {
    const templateDir = join(this.skillsDir, '_template');
    mkdirSync(templateDir, { recursive: true });

    const content = `---
name: template-skill
description: A template skill for Mercury. Use this as a starting point to create your own skills.
version: 0.1.0
category: development
tags:
  - template
allowed-tools:
  - read_file
  - list_dir
---

# Template Skill

This is a template skill for Mercury. Copy this directory and edit SKILL.md to create your own skill.

## What It Does

Describe what this skill enables Mercury to do. When invoked via the use_skill tool, these instructions are injected into Mercury's context as guidance.

## Instructions

1. Step one of what Mercury should do
2. Step two
3. Continue with specific guidance

## Tips

- Keep instructions concise to save tokens
- List only the tools you need in allowed-tools
- The skill name must be unique among installed skills
- Add \`category\` and \`tags\` in frontmatter to group the skill in lists; the description is what Mercury reads to decide when to use it
`;

    writeFileSync(join(templateDir, SKILL_FILE), content, 'utf-8');
    logger.info('Seeded template skill');
  }

  /**
   * Built-in skills Mercury no longer ships (ADR-040). A copy that is byte
   * for byte one Mercury seeded was never touched by the owner: it moves to
   * `_retired-<name>` (underscore folders are not loaded, nothing is
   * deleted). An edited copy is the owner's own skill and stays where it is.
   */
  private retireOldDefaults(): void {
    for (const [dirName, hashes] of Object.entries(RETIRED_SEEDS)) {
      const skillDir = join(this.skillsDir, dirName);
      const skillFile = join(skillDir, SKILL_FILE);
      if (!existsSync(skillFile)) continue;
      try {
        const hash = createHash('sha256').update(readFileSync(skillFile)).digest('hex');
        if (!hashes.includes(hash)) continue;
        let target = join(this.skillsDir, `_retired-${dirName}`);
        if (existsSync(target)) target = `${target}-${Date.now()}`;
        renameSync(skillDir, target);
        logger.info({ skill: dirName, movedTo: target }, 'Retired a built-in skill Mercury no longer ships');
      } catch (err) {
        logger.warn({ err, skill: dirName }, 'Could not retire an old built-in skill');
      }
    }
  }

  /**
   * Defaults are installed once (ADR-040). Which ones were installed is kept
   * in `.seeded-defaults.json`, so a default the owner deletes stays deleted
   * instead of coming back on the next start; a new default Mercury adds
   * later is still installed once.
   */
  private readSeededDefaults(): Set<string> {
    try {
      const parsed = JSON.parse(readFileSync(join(this.skillsDir, SEEDED_FILE), 'utf-8')) as { seeded?: unknown };
      return new Set(Array.isArray(parsed.seeded) ? parsed.seeded.filter((n): n is string => typeof n === 'string') : []);
    } catch {
      return new Set();
    }
  }

  private writeSeededDefaults(seeded: Set<string>): void {
    try {
      writeFileSync(join(this.skillsDir, SEEDED_FILE), JSON.stringify({ seeded: [...seeded].sort() }, null, 2) + '\n', 'utf-8');
    } catch (err) {
      logger.warn({ err }, 'Could not record installed default skills');
    }
  }

  private ensureDefaultSkills(): void {
    const seeded = this.readSeededDefaults();
    const before = seeded.size;
    for (const seed of DEFAULT_SKILL_SEEDS) {
      const skillDir = join(this.skillsDir, seed.dirName);
      const skillFile = join(skillDir, seed.fileName);
      if (existsSync(skillFile)) {
        seeded.add(seed.dirName);
        // Upgrade an untouched copy of an older built-in version; never overwrite edits.
        try {
          const current = readFileSync(skillFile, 'utf-8');
          if (current !== seed.content && (PREVIOUS_SEED_CONTENTS[seed.dirName] ?? []).includes(current)) {
            writeFileSync(skillFile, seed.content, 'utf-8');
            logger.info({ skill: seed.dirName }, 'Upgraded default skill');
          } else if (current !== seed.content && isBrokenSearchSkill(seed.dirName, current)) {
            // A web-search skill that scrapes a search engine's HTML page
            // (usually DuckDuckGo, which now answers bots with a challenge)
            // never works. Keep the owner's copy beside it and use the
            // built-in one, which calls the web_search tool.
            writeFileSync(`${skillFile}.replaced.bak`, current, 'utf-8');
            writeFileSync(skillFile, seed.content, 'utf-8');
            logger.info({ skill: seed.dirName, backup: `${skillFile}.replaced.bak` }, 'Replaced a web-search skill that scrapes a blocked search page');
          }
        } catch { /* leave it */ }
        continue;
      }

      // Installed before and gone now: the owner removed it. Leave it removed.
      if (seeded.has(seed.dirName)) continue;
      mkdirSync(skillDir, { recursive: true });
      writeFileSync(skillFile, seed.content, 'utf-8');
      seeded.add(seed.dirName);
      logger.info({ skill: seed.dirName }, 'Seeded default skill');
    }
    if (seeded.size !== before) this.writeSeededDefaults(seeded);
  }
}