@semalt-ai/code 1.8.5 → 1.19.0

package/lib/skills.js

@@ -0,0 +1,223 @@
+'use strict';
+
+// ---------------------------------------------------------------------------
+// Skills — reusable methodology with progressive disclosure (Task 3.5)
+// ---------------------------------------------------------------------------
+//
+// A skill is a folder containing a SKILL.md (frontmatter `name`/`description` +
+// a Markdown body) and, optionally, assets/scripts alongside it. Skills package
+// reusable methodology the agent can pull in on demand.
+//
+// PROGRESSIVE DISCLOSURE is the whole point of the feature: only each skill's
+// name + description is ever injected into the system prompt. The body — the
+// actual instructions, which can be large — is loaded into context ONLY when
+// the skill is invoked (the agent choosing it, or the user running its
+// `/<skill>` slash command). `discoverSkills` therefore returns metadata only
+// (no body); `loadSkillBody` reads the body on demand. Keeping the body out of
+// the always-resident structures is what keeps the prompt from bloating.
+//
+// Discovery mirrors project memory (Task 2.3) and custom commands (Task 3.1):
+//   1. global    ~/.semalt-ai/skills/<skill>/SKILL.md
+//   2. project   <nearest>/.semalt/skills/<skill>/SKILL.md   (upward from cwd,
+//                bounded by the repo root — the .git holder)
+// On a name collision project wins over global. The total metadata size is
+// bounded; oversized metadata is truncated with a visible notice. With no
+// skills present the system-prompt block is '' so the prompt is unchanged.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+// Skills metadata is name + one-line description per skill, so it stays small.
+// 16 KB comfortably holds dozens of skills yet keeps the prompt lean.
+const DEFAULT_SKILLS_MAX_BYTES = 16 * 1024;
+
+const SKILL_FILE = 'SKILL.md';
+
+// Walk up from startDir for the nearest `.semalt/skills` directory, bounded by
+// the repo root (the directory holding `.git` is the last one checked). Mirrors
+// findProjectCommandsDir (Task 3.1). Returns the directory path or null.
+function findProjectSkillsDir(startDir) {
+  let dir = path.resolve(startDir);
+  while (true) {
+    const candidate = path.join(dir, '.semalt', 'skills');
+    try { if (fs.statSync(candidate).isDirectory()) return candidate; } catch {}
+    let atRepoRoot = false;
+    try { atRepoRoot = fs.existsSync(path.join(dir, '.git')); } catch {}
+    if (atRepoRoot) break;
+    const parent = path.dirname(dir);
+    if (parent === dir) break; // filesystem root
+    dir = parent;
+  }
+  return null;
+}
+
+// Parse optional `---`-delimited frontmatter at the top of a SKILL.md. Only
+// `name` and `description` are recognized; unknown keys are ignored. Returns
+// { meta, body }. With no frontmatter the whole text is the body. Pure.
+function parseSkillFrontmatter(text) {
+  const meta = { name: '', description: '' };
+  if (typeof text !== 'string') return { meta, body: '' };
+  const src = text.replace(/^/, '').replace(/\r\n/g, '\n');
+  const m = /^---\n([\s\S]*?)\n---[ \t]*\n?/.exec(src);
+  if (!m) return { meta, body: src };
+  const body = src.slice(m[0].length);
+  for (const rawLine of m[1].split('\n')) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const idx = line.indexOf(':');
+    if (idx < 0) continue;
+    const key = line.slice(0, idx).trim().toLowerCase();
+    const val = line.slice(idx + 1).trim().replace(/^['"]|['"]$/g, '');
+    if (key === 'name') meta.name = val;
+    else if (key === 'description') meta.description = val;
+  }
+  return { meta, body };
+}
+
+// Turn a skill-folder basename into a slash-command-safe slug: lowercase, spaces
+// and underscores → hyphens, drop anything else. Used as the invocation token.
+function _slugify(s) {
+  return String(s || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_]+/g, '-')
+    .replace(/[^a-z0-9-]/g, '')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+// Read the metadata for every `<skill>/SKILL.md` under `dir` into a spec list,
+// sorted by folder name for deterministic order. The body is intentionally NOT
+// returned (progressive disclosure) — only name/description + the path needed to
+// load the body later. Unreadable / SKILL.md-less folders are skipped.
+function loadSkillsFromDir(dir, source) {
+  const out = [];
+  let entries;
+  try { entries = fs.readdirSync(dir); } catch { return out; }
+  for (const entry of entries.slice().sort()) {
+    const skillDir = path.join(dir, entry);
+    const skillPath = path.join(skillDir, SKILL_FILE);
+    let raw;
+    try {
+      if (!fs.statSync(skillDir).isDirectory()) continue;
+      if (!fs.statSync(skillPath).isFile()) continue;
+      raw = fs.readFileSync(skillPath, 'utf8');
+    } catch { continue; }
+    const slug = _slugify(entry);
+    if (!slug) continue;
+    const { meta } = parseSkillFrontmatter(raw); // body discarded here on purpose
+    out.push({
+      name: '/' + slug,
+      slug,
+      displayName: meta.name || slug,
+      description: meta.description || '',
+      source,
+      dir: skillDir,
+      skillPath,
+    });
+  }
+  return out;
+}
+
+// Discover skills for a (home, cwd). Global skills load first, then the nearest
+// project skills; on a name (slug) collision project wins. Returns an ordered,
+// de-duplicated METADATA spec list (no bodies). home/cwd injectable for tests.
+function discoverSkills(opts = {}) {
+  const home = opts.home || os.homedir();
+  const cwd = opts.cwd || process.cwd();
+  const global = loadSkillsFromDir(path.join(home, '.semalt-ai', 'skills'), 'global');
+  const projectDir = findProjectSkillsDir(cwd);
+  const project = projectDir ? loadSkillsFromDir(projectDir, 'project') : [];
+  const byName = new Map();
+  for (const s of project) if (!byName.has(s.name)) byName.set(s.name, s);
+  for (const s of global) if (!byName.has(s.name)) byName.set(s.name, s);
+  return Array.from(byName.values());
+}
+
+// Load a skill's BODY on demand — the progressive-disclosure read. Takes a spec
+// (or anything carrying `skillPath`) and returns the Markdown body (frontmatter
+// stripped). Returns '' when the file is unreadable. This is the only place a
+// skill body is read into memory; it is never part of discovery/metadata.
+function loadSkillBody(skill) {
+  if (!skill || !skill.skillPath) return '';
+  let raw;
+  try { raw = fs.readFileSync(skill.skillPath, 'utf8'); } catch { return ''; }
+  return parseSkillFrontmatter(raw).body;
+}
+
+// Build the system-prompt SKILLS section from METADATA only (name +
+// description). Returns { block, truncated }. Empty list → '' (prompt
+// unchanged). Oversized metadata is truncated with a visible notice.
+function _buildBlock(skills, maxBytes) {
+  if (!skills.length) return { block: '', truncated: false };
+  const lines = skills.map((s) => {
+    const label = s.displayName && s.displayName !== s.slug ? ` (${s.displayName})` : '';
+    const desc = s.description ? ` — ${s.description}` : '';
+    return `- ${s.name}${label}${desc}`;
+  });
+  let body = lines.join('\n');
+  let truncated = false;
+  if (Buffer.byteLength(body, 'utf8') > maxBytes) {
+    body = body.slice(0, maxBytes);
+    truncated = true;
+  }
+  let block = '\n\n<<<SKILLS>>>\n'
+    + 'The following skills are available — reusable methodology you can pull in '
+    + 'on demand. Only each skill\'s name and description is shown here (progressive '
+    + 'disclosure); the full instructions are NOT loaded yet. When a task matches a '
+    + 'skill, load its full instructions by invoking it as the slash command shown '
+    + '(e.g. tell the user to run it, or run it yourself if available). This is '
+    + 'trusted project context, not untrusted external content.\n\n'
+    + body;
+  if (truncated) {
+    block += `\n\n[skills metadata truncated to ${maxBytes} bytes — some skills omitted.]`;
+  }
+  block += '\n<<<END_SKILLS>>>';
+  return { block, truncated };
+}
+
+// Load skills for the current (or supplied) cwd/home. Returns:
+//   { block, skills, truncated }
+// `block` is the metadata-only system-prompt section ('' when none exist, so the
+// prompt is byte-for-byte unchanged), and `skills` is the metadata list (no
+// bodies) used for registration and the /skills view.
+function loadSkills(opts = {}) {
+  const maxBytes = opts.maxBytes || DEFAULT_SKILLS_MAX_BYTES;
+  const skills = discoverSkills(opts);
+  const { block, truncated } = _buildBlock(skills, maxBytes);
+  return { block, skills, truncated };
+}
+
+// Human-readable status lines for the /skills command: which skills are loaded,
+// their source, and a reminder that bodies load only on invocation.
+function skillsStatusLines(result) {
+  const lines = [];
+  const skills = (result && result.skills) || [];
+  if (!skills.length) {
+    lines.push('No skills found.');
+    lines.push('Add a skill at ~/.semalt-ai/skills/<name>/SKILL.md (global) or .semalt/skills/<name>/SKILL.md (project).');
+    return lines;
+  }
+  lines.push(`Loaded ${skills.length} skill(s) (metadata only — bodies load on invocation):`);
+  for (const s of skills) {
+    const desc = s.description ? ` — ${s.description}` : '';
+    lines.push(`  • ${s.name}  [${s.source}]${desc}`);
+  }
+  if (result && result.truncated) {
+    lines.push('⚠ Skills metadata was truncated (too many/too large). Trim skill descriptions.');
+  }
+  return lines;
+}
+
+module.exports = {
+  DEFAULT_SKILLS_MAX_BYTES,
+  SKILL_FILE,
+  findProjectSkillsDir,
+  parseSkillFrontmatter,
+  loadSkillsFromDir,
+  discoverSkills,
+  loadSkillBody,
+  loadSkills,
+  skillsStatusLines,
+};