@liquidmetal-ai/precip 1.0.0

package/src/skills/frontmatter.ts

@@ -0,0 +1,200 @@
+/**
+ * YAML frontmatter parser for SKILL.md files
+ *
+ * Parses the YAML frontmatter block delimited by --- lines at the top of a markdown file.
+ * Handles the fields defined by the Agent Skills specification:
+ *   - name (required)
+ *   - description (required)
+ *   - license (optional)
+ *   - compatibility (optional)
+ *   - metadata (optional)
+ *   - allowed-tools (optional)
+ *
+ * Uses a simple line-based parser — no external YAML dependency.
+ * Supports flat key-value pairs, one level of nested maps (metadata),
+ * and YAML block scalars (folded `>` and literal `|`).
+ */
+
+/**
+ * Parsed frontmatter from a SKILL.md file
+ */
+export interface SkillFrontmatter {
+  name: string;
+  description: string;
+  license?: string;
+  compatibility?: string;
+  metadata?: Record<string, string>;
+  allowedTools?: string;
+}
+
+/**
+ * Collect indented continuation lines starting at `startIndex` and join them
+ * according to the block scalar style.
+ *
+ * @returns A tuple of [joinedValue, nextIndex] where nextIndex is the index of
+ *          the first line that is NOT part of the block.
+ */
+function collectBlockScalar(
+  yamlLines: string[],
+  startIndex: number,
+  style: '>' | '|'
+): [string, number] {
+  const contentLines: string[] = [];
+  let i = startIndex;
+
+  while (i < yamlLines.length) {
+    const line = yamlLines[i]!;
+
+    // A non-empty, non-indented line ends the block
+    if (line.trim() !== '' && !line.startsWith('  ') && !line.startsWith('\t')) {
+      break;
+    }
+
+    // Preserve empty lines as empty strings; strip indentation from content lines
+    if (line.trim() === '') {
+      contentLines.push('');
+    } else {
+      contentLines.push(line.replace(/^[ \t]+/, ''));
+    }
+    i++;
+  }
+
+  // Trim trailing empty lines
+  while (contentLines.length > 0 && contentLines[contentLines.length - 1] === '') {
+    contentLines.pop();
+  }
+
+  let value: string;
+  if (style === '|') {
+    // Literal: preserve newlines exactly
+    value = contentLines.join('\n');
+  } else {
+    // Folded: join non-empty runs with spaces, empty lines become newlines
+    const parts: string[] = [];
+    let currentRun: string[] = [];
+
+    for (const cl of contentLines) {
+      if (cl === '') {
+        if (currentRun.length > 0) {
+          parts.push(currentRun.join(' '));
+          currentRun = [];
+        }
+        parts.push('');
+      } else {
+        currentRun.push(cl);
+      }
+    }
+    if (currentRun.length > 0) {
+      parts.push(currentRun.join(' '));
+    }
+
+    value = parts.join('\n');
+  }
+
+  return [value, i];
+}
+
+/**
+ * Parse YAML frontmatter from a SKILL.md file
+ *
+ * @param content The full text content of the SKILL.md file
+ * @returns Parsed frontmatter, or null if no valid frontmatter found
+ */
+export function parseFrontmatter(content: string): SkillFrontmatter | null {
+  const lines = content.split('\n');
+
+  // Must start with ---
+  if (lines[0]?.trim() !== '---') {
+    return null;
+  }
+
+  // Find closing ---
+  let endIndex = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i]!.trim() === '---') {
+      endIndex = i;
+      break;
+    }
+  }
+
+  if (endIndex === -1) {
+    return null;
+  }
+
+  const yamlLines = lines.slice(1, endIndex);
+  const fields: Record<string, string> = {};
+  let metadata: Record<string, string> | undefined;
+  let inMetadata = false;
+  let i = 0;
+
+  while (i < yamlLines.length) {
+    const line = yamlLines[i]!;
+
+    // Skip empty lines and comments
+    if (line.trim() === '' || line.trim().startsWith('#')) {
+      i++;
+      continue;
+    }
+
+    // Check for nested map entry (indented key: value under metadata)
+    if (inMetadata && (line.startsWith('  ') || line.startsWith('\t'))) {
+      const match = line.match(/^\s+(\S+)\s*:\s*"?([^"]*)"?\s*$/);
+      if (match) {
+        if (!metadata) metadata = {};
+        metadata[match[1]!] = match[2]!.trim();
+      }
+      i++;
+      continue;
+    }
+
+    // Top-level key: value
+    inMetadata = false;
+    const colonIndex = line.indexOf(':');
+    if (colonIndex === -1) {
+      i++;
+      continue;
+    }
+
+    const key = line.slice(0, colonIndex).trim();
+    const value = line.slice(colonIndex + 1).trim();
+
+    if (key === 'metadata') {
+      inMetadata = true;
+      i++;
+      continue;
+    }
+
+    // Check for block scalar indicators
+    if (value === '>' || value === '|') {
+      const [blockValue, nextIndex] = collectBlockScalar(
+        yamlLines,
+        i + 1,
+        value as '>' | '|'
+      );
+      fields[key] = blockValue;
+      i = nextIndex;
+      continue;
+    }
+
+    // Strip surrounding quotes if present
+    fields[key] = value.replace(/^["']|["']$/g, '');
+    i++;
+  }
+
+  // Validate required fields
+  if (!fields.name || !fields.description) {
+    return null;
+  }
+
+  const result: SkillFrontmatter = {
+    name: fields.name,
+    description: fields.description
+  };
+
+  if (fields.license) result.license = fields.license;
+  if (fields.compatibility) result.compatibility = fields.compatibility;
+  if (fields['allowed-tools']) result.allowedTools = fields['allowed-tools'];
+  if (metadata) result.metadata = metadata;
+
+  return result;
+}

package/src/skills/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Skills module - Agent Skills discovery and prompt generation
+ */
+
+export { parseFrontmatter } from './frontmatter.js';
+export type { SkillFrontmatter } from './frontmatter.js';
+
+export { discoverSkills, generateSkillsPrompt } from './skills-loader.js';
+export type { SkillMetadata, SkillsConfig } from './skills-loader.js';

package/src/skills/skills-loader.test.ts

@@ -0,0 +1,237 @@
+/**
+ * Tests for skills loader and prompt generation
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { discoverSkills, generateSkillsPrompt, type SkillMetadata } from './skills-loader.js';
+import { MountManager } from '../mounts/mount-manager.js';
+
+// Mock bucket that serves skill files
+function createMockSkillsBucket(files: Record<string, string>) {
+  return {
+    get: vi.fn(async (key: string) => {
+      const content = files[key];
+      if (!content) return null;
+      return {
+        text: async () => content,
+        body: null,
+        size: content.length,
+        uploaded: new Date(),
+        httpMetadata: {}
+      };
+    }),
+    put: vi.fn(),
+    list: vi.fn(async (opts?: { prefix?: string; delimiter?: string }) => {
+      const prefix = opts?.prefix || '';
+      const delimiter = opts?.delimiter;
+
+      if (delimiter) {
+        // Return subdirectories as delimitedPrefixes
+        const prefixes = new Set<string>();
+        for (const key of Object.keys(files)) {
+          if (key.startsWith(prefix)) {
+            const rest = key.slice(prefix.length);
+            const slashIndex = rest.indexOf('/');
+            if (slashIndex >= 0) {
+              prefixes.add(prefix + rest.slice(0, slashIndex + 1));
+            }
+          }
+        }
+        return {
+          objects: [],
+          delimitedPrefixes: Array.from(prefixes),
+          truncated: false
+        };
+      }
+
+      const objects = Object.keys(files)
+        .filter(key => key.startsWith(prefix))
+        .map(key => ({ key, size: files[key].length, uploaded: new Date() }));
+      return { objects, delimitedPrefixes: [], truncated: false };
+    }),
+    delete: vi.fn(),
+    head: vi.fn()
+  } as any;
+}
+
+describe('discoverSkills', () => {
+  it('should discover skills from a bucket mount', async () => {
+    const bucket = createMockSkillsBucket({
+      'skills/data-cleanup/SKILL.md': `---
+name: data-cleanup
+description: Normalize and deduplicate data across tables.
+---
+
+# Data Cleanup
+
+Instructions here.`,
+      'skills/report-builder/SKILL.md': `---
+name: report-builder
+description: Generate formatted reports from SQL query results.
+---
+
+# Report Builder
+
+Instructions here.`
+    });
+
+    const manager = new MountManager({
+      knowledge: { type: 'bucket', resource: bucket }
+    });
+
+    const skills = await discoverSkills(manager, { path: '/knowledge/skills/' });
+
+    expect(skills).toHaveLength(2);
+    expect(skills[0].name).toBe('data-cleanup');
+    expect(skills[0].description).toBe('Normalize and deduplicate data across tables.');
+    expect(skills[0].location).toBe('/knowledge/skills/data-cleanup/SKILL.md');
+    expect(skills[1].name).toBe('report-builder');
+  });
+
+  it('should return empty array for non-existent mount', async () => {
+    const manager = new MountManager({});
+    const skills = await discoverSkills(manager, { path: '/missing/skills/' });
+    expect(skills).toHaveLength(0);
+  });
+
+  it('should skip skills with invalid frontmatter', async () => {
+    const bucket = createMockSkillsBucket({
+      'skills/good-skill/SKILL.md': `---
+name: good-skill
+description: A valid skill.
+---
+
+Content.`,
+      'skills/bad-skill/SKILL.md': `# No frontmatter here
+
+Just markdown.`
+    });
+
+    const manager = new MountManager({
+      kb: { type: 'bucket', resource: bucket }
+    });
+
+    const skills = await discoverSkills(manager, { path: '/kb/skills/' });
+    expect(skills).toHaveLength(1);
+    expect(skills[0].name).toBe('good-skill');
+  });
+
+  it('should warn when directory name does not match skill name', async () => {
+    const bucket = createMockSkillsBucket({
+      'skills/wrong-dir/SKILL.md': `---
+name: correct-name
+description: Skill with mismatched directory.
+---`
+    });
+
+    const manager = new MountManager({
+      kb: { type: 'bucket', resource: bucket }
+    });
+
+    const logger = {
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      debug: vi.fn()
+    };
+
+    const skills = await discoverSkills(manager, { path: '/kb/skills/' }, logger);
+    expect(skills).toHaveLength(1);
+    expect(skills[0].name).toBe('correct-name');
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.stringContaining('does not match skill name')
+    );
+  });
+
+  it('should reject non-bucket mount types', async () => {
+    const mockKv = {
+      get: vi.fn(),
+      put: vi.fn(),
+      list: vi.fn(),
+      delete: vi.fn(),
+      getWithMetadata: vi.fn(),
+      clear: vi.fn()
+    } as any;
+
+    const manager = new MountManager({
+      cache: { type: 'kv', resource: mockKv }
+    });
+
+    const logger = {
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      debug: vi.fn()
+    };
+
+    const skills = await discoverSkills(manager, { path: '/cache/skills/' }, logger);
+    expect(skills).toHaveLength(0);
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.stringContaining('must be a bucket or smartbucket')
+    );
+  });
+});
+
+describe('generateSkillsPrompt', () => {
+  it('should generate valid XML for skills', () => {
+    const skills: SkillMetadata[] = [
+      {
+        name: 'data-cleanup',
+        description: 'Normalize and deduplicate data across tables.',
+        location: '/knowledge/skills/data-cleanup/SKILL.md',
+        frontmatter: {
+          name: 'data-cleanup',
+          description: 'Normalize and deduplicate data across tables.'
+        }
+      },
+      {
+        name: 'report-builder',
+        description: 'Generate formatted reports from SQL query results.',
+        location: '/knowledge/skills/report-builder/SKILL.md',
+        frontmatter: {
+          name: 'report-builder',
+          description: 'Generate formatted reports from SQL query results.'
+        }
+      }
+    ];
+
+    const prompt = generateSkillsPrompt(skills);
+
+    expect(prompt).toContain('<available_skills>');
+    expect(prompt).toContain('</available_skills>');
+    expect(prompt).toContain('<skill>');
+    expect(prompt).toContain('<name>data-cleanup</name>');
+    expect(prompt).toContain(
+      '<description>Normalize and deduplicate data across tables.</description>'
+    );
+    expect(prompt).toContain(
+      '<location>/knowledge/skills/data-cleanup/SKILL.md</location>'
+    );
+    expect(prompt).toContain('<name>report-builder</name>');
+  });
+
+  it('should return empty string for no skills', () => {
+    expect(generateSkillsPrompt([])).toBe('');
+  });
+
+  it('should escape XML special characters', () => {
+    const skills: SkillMetadata[] = [
+      {
+        name: 'test-skill',
+        description: 'Handles <html> & "quoted" values',
+        location: '/kb/skills/test-skill/SKILL.md',
+        frontmatter: {
+          name: 'test-skill',
+          description: 'Handles <html> & "quoted" values'
+        }
+      }
+    ];
+
+    const prompt = generateSkillsPrompt(skills);
+
+    expect(prompt).toContain('&lt;html&gt;');
+    expect(prompt).toContain('&amp;');
+    expect(prompt).toContain('&quot;quoted&quot;');
+    expect(prompt).not.toContain('<html>');
+  });
+});

package/src/skills/skills-loader.ts

@@ -0,0 +1,200 @@
+/**
+ * Skills Loader - Discovers and loads Agent Skills from mounted storage
+ *
+ * Implements the Agent Skills specification for progressive disclosure:
+ * 1. At startup, scans a configured path for skill directories containing SKILL.md
+ * 2. Parses YAML frontmatter (name + description) from each SKILL.md
+ * 3. Generates <available_skills> XML for injection into the system prompt
+ *
+ * The agent reads the full SKILL.md on demand (using existing read tools)
+ * and executes scripts via the run_script tool.
+ *
+ * @see https://agentskills.io/specification
+ */
+
+import type { Bucket } from '@liquidmetal-ai/raindrop-framework';
+import type { Logger } from '../types.js';
+import { MountManager } from '../mounts/mount-manager.js';
+import { parseFrontmatter, type SkillFrontmatter } from './frontmatter.js';
+
+/**
+ * Metadata for a discovered skill
+ */
+export interface SkillMetadata {
+  /** Skill name from frontmatter */
+  name: string;
+  /** Skill description from frontmatter */
+  description: string;
+  /** Full mount path to the SKILL.md file */
+  location: string;
+  /** Parsed frontmatter (includes optional fields) */
+  frontmatter: SkillFrontmatter;
+}
+
+/**
+ * Configuration for the skills loader
+ */
+export interface SkillsConfig {
+  /**
+   * Mount path where skills are stored.
+   * Skills are expected as subdirectories each containing a SKILL.md.
+   *
+   * Example: "/knowledge/skills/" scans for:
+   *   /knowledge/skills/data-cleanup/SKILL.md
+   *   /knowledge/skills/report-builder/SKILL.md
+   */
+  path: string;
+}
+
+/**
+ * Discover skills from a mounted bucket path.
+ *
+ * Scans the given path for subdirectories containing SKILL.md files,
+ * parses their frontmatter, and returns metadata for each valid skill.
+ */
+export async function discoverSkills(
+  mountManager: MountManager,
+  config: SkillsConfig,
+  logger?: Logger
+): Promise<SkillMetadata[]> {
+  const skills: SkillMetadata[] = [];
+
+  // Parse the skills path to find the mount and prefix
+  const parsed = mountManager.parsePath(config.path);
+  const mount = mountManager.getMount(parsed.mountName);
+
+  if (!mount) {
+    logger?.warn?.(`Skills mount not found: ${parsed.mountName}`);
+    return skills;
+  }
+
+  // Only bucket and smartbucket mounts support listing + reading files
+  if (mount.type !== 'bucket' && mount.type !== 'smartbucket') {
+    logger?.warn?.(`Skills mount must be a bucket or smartbucket, got: ${mount.type}`);
+    return skills;
+  }
+
+  const bucket = mount.resource as Bucket;
+  const prefix = parsed.path;
+
+  try {
+    // List contents at the skills path to find subdirectories.
+    // We look for SKILL.md files using a delimiter to find skill directories.
+    const listed = await bucket.list({
+      prefix: prefix ? (prefix.endsWith('/') ? prefix : prefix + '/') : undefined,
+      delimiter: '/'
+    });
+
+    // delimitedPrefixes gives us subdirectories (e.g., "skills/data-cleanup/")
+    const skillDirs = listed.delimitedPrefixes || [];
+
+    // Also check for SKILL.md files directly in the listing
+    // (in case the bucket implementation returns them as objects)
+    const skillMdFiles = listed.objects
+      .filter(obj => obj.key.endsWith('/SKILL.md') || obj.key === 'SKILL.md')
+      .map(obj => {
+        // Extract the directory path
+        const dir = obj.key.slice(0, obj.key.lastIndexOf('/') + 1);
+        return dir;
+      });
+
+    const allDirs = [...new Set([...skillDirs, ...skillMdFiles])];
+
+    for (const dir of allDirs) {
+      const skillMdPath = `${dir}SKILL.md`;
+
+      try {
+        const obj = await bucket.get(skillMdPath);
+        if (!obj) continue;
+
+        const content = await obj.text();
+        const frontmatter = parseFrontmatter(content);
+
+        if (!frontmatter) {
+          logger?.warn?.(`Invalid or missing frontmatter in ${skillMdPath}`);
+          continue;
+        }
+
+        // Validate that the directory name matches the skill name (per spec)
+        const dirName = dir.replace(/\/$/, '').split('/').pop();
+        if (dirName && dirName !== frontmatter.name) {
+          logger?.warn?.(
+            `Skill directory name "${dirName}" does not match skill name "${frontmatter.name}" in ${skillMdPath}`
+          );
+          // Continue anyway — this is a warning, not a hard error
+        }
+
+        const location = `/${parsed.mountName}/${skillMdPath}`.replace(/\/+/g, '/');
+
+        skills.push({
+          name: frontmatter.name,
+          description: frontmatter.description,
+          location,
+          frontmatter
+        });
+
+        logger?.debug?.(`Discovered skill: ${frontmatter.name} at ${location}`);
+      } catch (e) {
+        logger?.warn?.(`Failed to read skill at ${skillMdPath}: ${e}`);
+      }
+    }
+
+    // Sort by name for consistent ordering
+    skills.sort((a, b) => a.name.localeCompare(b.name));
+
+    logger?.info?.(`Discovered ${skills.length} skill(s) from ${config.path}`);
+  } catch (e) {
+    logger?.error?.(`Failed to scan skills path ${config.path}: ${e}`);
+  }
+
+  return skills;
+}
+
+/**
+ * Generate the <available_skills> XML block for the system prompt.
+ *
+ * Follows the Agent Skills specification format:
+ * ```xml
+ * <available_skills>
+ *   <skill>
+ *     <name>...</name>
+ *     <description>...</description>
+ *     <location>...</location>
+ *   </skill>
+ * </available_skills>
+ * ```
+ *
+ * @see https://agentskills.io/integrate-skills
+ */
+export function generateSkillsPrompt(skills: SkillMetadata[]): string {
+  if (skills.length === 0) {
+    return '';
+  }
+
+  const lines: string[] = [];
+  lines.push('');
+  lines.push('<available_skills>');
+
+  for (const skill of skills) {
+    lines.push('  <skill>');
+    lines.push(`    <name>${escapeXml(skill.name)}</name>`);
+    lines.push(`    <description>${escapeXml(skill.description)}</description>`);
+    lines.push(`    <location>${escapeXml(skill.location)}</location>`);
+    lines.push('  </skill>');
+  }
+
+  lines.push('</available_skills>');
+
+  return lines.join('\n');
+}
+
+/**
+ * Escape special XML characters
+ */
+function escapeXml(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}