@soulcraft/kit-schema 2.0.0

package/src/skills.ts

@@ -0,0 +1,127 @@
+/**
+ * @module @soulcraft/kit-schema/skills
+ * @description SKILL.md frontmatter parser for Soulcraft kit AI skills.
+ *
+ * Skills are AI capability definitions stored in `kits/{id}/skills/{name}/SKILL.md`.
+ * Each file has a YAML frontmatter block (between `---` markers) followed by
+ * Markdown content that forms the skill's instruction body.
+ *
+ * This module parses both sections and returns a typed {@link ParsedSkill} object
+ * suitable for inclusion in AI system prompts.
+ *
+ * @example
+ * ```ts
+ * import { parseSkillFile } from '@soulcraft/kit-schema/skills';
+ * import { readFile } from 'node:fs/promises';
+ *
+ * const raw = await readFile('kits/wicks-and-whiskers/skills/memory-narrative/SKILL.md', 'utf-8');
+ * const skill = parseSkillFile(raw, '/path/to/SKILL.md');
+ * // skill.frontmatter.type === 'invocable'
+ * // skill.body === '## Candle Memory Narrative\n...'
+ * ```
+ */
+
+import type { SkillFrontmatter, ParsedSkill } from './types.js';
+
+/**
+ * Parse a SKILL.md file's content into a {@link ParsedSkill} object.
+ *
+ * The file must begin with a YAML frontmatter block delimited by `---`.
+ * Required frontmatter fields: `id`, `name`, `description`, `type`.
+ *
+ * @param content - Full text content of the SKILL.md file.
+ * @param filePath - Absolute filesystem path to the SKILL.md file (used for error messages).
+ * @returns Parsed skill with validated frontmatter and body content.
+ * @throws {Error} If the frontmatter block is missing, malformed, or missing required fields.
+ *
+ * @example
+ * ```ts
+ * const skill = parseSkillFile(fileContent, '/kits/wicks/skills/memory-narrative/SKILL.md');
+ * console.log(skill.frontmatter.type); // "invocable"
+ * ```
+ */
+export function parseSkillFile(content: string, filePath: string): ParsedSkill {
+	if (!content.startsWith('---')) {
+		throw new Error(`SKILL.md at ${filePath} must begin with a YAML frontmatter block (---)`);
+	}
+
+	const endMarker = content.indexOf('\n---', 3);
+	if (endMarker === -1) {
+		throw new Error(`SKILL.md at ${filePath} has an unclosed frontmatter block (missing closing ---)`);
+	}
+
+	const frontmatterText = content.slice(3, endMarker).trim();
+	const body = content.slice(endMarker + 4).trim();
+
+	const frontmatter = parseYamlFrontmatter(frontmatterText, filePath);
+
+	return { filePath, frontmatter, body };
+}
+
+/**
+ * Minimal YAML parser for SKILL.md frontmatter.
+ *
+ * Supports the simple key: value format used in skill definitions.
+ * Does not support nested objects, arrays, or multi-line values —
+ * skill frontmatter intentionally uses only flat string/boolean fields.
+ *
+ * @param text - The raw YAML text between the `---` delimiters.
+ * @param filePath - File path for error messages.
+ * @returns Validated {@link SkillFrontmatter} object.
+ * @throws {Error} If required fields are missing or `type` has an invalid value.
+ */
+function parseYamlFrontmatter(text: string, filePath: string): SkillFrontmatter {
+	const record: Record<string, string | boolean> = {};
+
+	for (const line of text.split('\n')) {
+		const trimmed = line.trim();
+		if (!trimmed || trimmed.startsWith('#')) continue;
+
+		const colonIdx = trimmed.indexOf(':');
+		if (colonIdx === -1) continue;
+
+		const key = trimmed.slice(0, colonIdx).trim();
+		const rawValue = trimmed.slice(colonIdx + 1).trim();
+
+		// Unquote string values
+		const value = rawValue.startsWith('"') && rawValue.endsWith('"')
+			? rawValue.slice(1, -1)
+			: rawValue.startsWith("'") && rawValue.endsWith("'")
+				? rawValue.slice(1, -1)
+				: rawValue === 'true'
+					? true
+					: rawValue === 'false'
+						? false
+						: rawValue;
+
+		record[key] = value;
+	}
+
+	// Validate required fields
+	const { id, name, description, type, version, requiresVision, requiresData } = record;
+
+	if (!id || typeof id !== 'string') {
+		throw new Error(`SKILL.md at ${filePath} is missing required frontmatter field: 'id'`);
+	}
+	if (!name || typeof name !== 'string') {
+		throw new Error(`SKILL.md at ${filePath} is missing required frontmatter field: 'name'`);
+	}
+	if (!description || typeof description !== 'string') {
+		throw new Error(`SKILL.md at ${filePath} is missing required frontmatter field: 'description'`);
+	}
+	if (type !== 'background' && type !== 'invocable') {
+		throw new Error(
+			`SKILL.md at ${filePath} has invalid 'type': "${String(type)}". Must be "background" or "invocable".`
+		);
+	}
+
+	return {
+		id,
+		name,
+		description,
+		type,
+		version: typeof version === 'string' ? version : undefined,
+		requiresVision: typeof requiresVision === 'boolean' ? requiresVision : undefined,
+		requiresData: typeof requiresData === 'boolean' ? requiresData : undefined
+	};
+}