freeturtle 0.1.28 → 0.1.30

package/dist/src/skills/loader.js

@@ -0,0 +1,211 @@
+/**
+ * Skill loader — discovers and loads Agent Skills from the filesystem.
+ *
+ * Follows the same progressive disclosure model as OpenClaw:
+ *   - Only name/description/location are injected into the system prompt
+ *   - Full SKILL.md body is loaded on-demand via the read_file tool
+ *   - XML format for the available_skills block
+ *
+ * Scan order (highest to lowest precedence):
+ *   1. Workspace skills:  <workspace>/skills/
+ *   2. Managed skills:    ~/.freeturtle/skills/  (shared across agents)
+ *   3. Extra dirs:        Configured via skills.extra_dirs in config.md
+ *
+ * Compatible with OpenClaw, Claude Code, and ClawHub-installed skills.
+ * Skills installed via `clawhub install` into <workspace>/skills/ are picked up automatically.
+ */
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, basename } from "node:path";
+import { homedir } from "node:os";
+import { parseSkillMd } from "./parser.js";
+const SKILL_FILENAME = "SKILL.md";
+// Limits aligned with OpenClaw defaults
+const MAX_SKILLS_IN_PROMPT = 150;
+const MAX_PROMPT_CHARS = 30_000;
+const MAX_SKILL_FILE_BYTES = 256 * 1024; // 256 KB
+const MAX_SKILLS_PER_SOURCE = 200;
+export async function loadSkills(workspaceDir, config, logger) {
+    if (config && !config.enabled) {
+        logger?.info("Skills disabled in config");
+        return [];
+    }
+    const skills = [];
+    const seenNames = new Set();
+    // 1. Workspace skills (highest precedence)
+    const workspaceSkillsDir = join(workspaceDir, "skills");
+    await scanSkillDir(workspaceSkillsDir, "workspace", skills, seenNames, logger);
+    // 2. Managed skills (shared across agents)
+    const managedDir = join(homedir(), ".freeturtle", "skills");
+    if (managedDir !== workspaceSkillsDir) {
+        await scanSkillDir(managedDir, "managed", skills, seenNames, logger);
+    }
+    // 3. Extra directories from config
+    if (config?.extra_dirs) {
+        for (const dir of config.extra_dirs) {
+            await scanSkillDir(dir, "extra", skills, seenNames, logger);
+        }
+    }
+    if (skills.length > 0) {
+        logger?.info(`Loaded ${skills.length} skill(s): ${skills.map((s) => s.name).join(", ")}`);
+    }
+    return skills;
+}
+async function scanSkillDir(dir, source, skills, seenNames, logger) {
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        // Directory doesn't exist — that's fine
+        return;
+    }
+    let loadedFromSource = 0;
+    for (const entry of entries) {
+        if (loadedFromSource >= MAX_SKILLS_PER_SOURCE) {
+            logger?.warn(`Hit max skills per source (${MAX_SKILLS_PER_SOURCE}) for ${dir}`);
+            break;
+        }
+        const skillDir = join(dir, entry);
+        // Must be a directory
+        try {
+            const s = await stat(skillDir);
+            if (!s.isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        // Must contain SKILL.md
+        const skillMdPath = join(skillDir, SKILL_FILENAME);
+        let raw;
+        try {
+            const s = await stat(skillMdPath);
+            if (s.size > MAX_SKILL_FILE_BYTES) {
+                logger?.warn(`SKILL.md in ${skillDir} exceeds ${MAX_SKILL_FILE_BYTES / 1024}KB — skipping`);
+                continue;
+            }
+            raw = await readFile(skillMdPath, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        // Parse the SKILL.md
+        const parsed = parseSkillMd(raw);
+        if (!parsed) {
+            logger?.warn(`Invalid SKILL.md in ${skillDir} — skipping`);
+            continue;
+        }
+        // Skill name: frontmatter.name or directory name
+        const name = parsed.frontmatter.name || basename(skillDir);
+        // Validate name format (Agent Skills spec: lowercase alphanumeric + hyphens)
+        if (!/^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/.test(name)) {
+            logger?.warn(`Skill "${name}" has invalid name format — skipping`);
+            continue;
+        }
+        // Higher-precedence skills shadow lower ones
+        if (seenNames.has(name)) {
+            logger?.info(`Skill "${name}" from ${source} shadowed by higher-precedence source`);
+            continue;
+        }
+        seenNames.add(name);
+        const allowedToolsRaw = parsed.frontmatter["allowed-tools"];
+        const allowedTools = allowedToolsRaw
+            ? allowedToolsRaw.split(/\s+/).filter((t) => t.length > 0)
+            : [];
+        skills.push({
+            name,
+            description: parsed.frontmatter.description || "",
+            body: parsed.body,
+            frontmatter: parsed.frontmatter,
+            dir: skillDir,
+            source,
+            modelInvocable: parsed.frontmatter["disable-model-invocation"] !== true,
+            userInvocable: parsed.frontmatter["user-invocable"] !== false,
+            allowedTools,
+        });
+        loadedFromSource++;
+    }
+}
+/**
+ * Compact a file path by replacing the home directory with ~.
+ * Saves tokens in the system prompt (same as OpenClaw).
+ */
+function compactPath(p) {
+    const home = homedir();
+    if (p.startsWith(home)) {
+        return "~" + p.slice(home.length);
+    }
+    return p;
+}
+/**
+ * Build the skills section for the system prompt.
+ *
+ * Uses the same progressive disclosure model as OpenClaw:
+ * - Only name/description/location are injected (not the full body)
+ * - The LLM reads the full SKILL.md via read_file when a skill matches
+ * - XML format for the available_skills block
+ * - Token budget enforcement via character limits
+ */
+export function buildSkillsPrompt(skills) {
+    const eligible = skills.filter((s) => s.modelInvocable);
+    if (eligible.length === 0)
+        return "";
+    // Apply limits: max skills in prompt
+    const capped = eligible.slice(0, MAX_SKILLS_IN_PROMPT);
+    const header = [
+        "## Skills (mandatory)",
+        "",
+        "Before replying, scan the <available_skills> descriptions below.",
+        "- If exactly one skill clearly applies: read its SKILL.md at the given location with `read_file`, then follow its instructions.",
+        "- If multiple could apply: choose the most specific one, then read and follow it.",
+        "- If none clearly apply: do not read any SKILL.md.",
+        "- Never read more than one skill up front; only read after selecting.",
+        "- When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md).",
+        "",
+    ].join("\n");
+    // Build XML block, enforcing character budget
+    const xmlOpen = "<available_skills>\n";
+    const xmlClose = "</available_skills>";
+    let promptChars = header.length + xmlOpen.length + xmlClose.length;
+    const skillEntries = [];
+    for (const skill of capped) {
+        const location = compactPath(join(skill.dir, SKILL_FILENAME));
+        const entry = [
+            "  <skill>",
+            `    <name>${escapeXml(skill.name)}</name>`,
+            `    <description>${escapeXml(skill.description)}</description>`,
+            `    <location>${escapeXml(location)}</location>`,
+            "  </skill>",
+        ].join("\n");
+        if (promptChars + entry.length + 1 > MAX_PROMPT_CHARS) {
+            break;
+        }
+        skillEntries.push(entry);
+        promptChars += entry.length + 1; // +1 for newline
+    }
+    if (skillEntries.length === 0)
+        return "";
+    return header + xmlOpen + skillEntries.join("\n") + "\n" + xmlClose;
+}
+function escapeXml(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+// --- Deprecated, kept for backward compat ---
+/** @deprecated Use buildSkillsPrompt instead */
+export function buildSkillIndex(skills) {
+    return buildSkillsPrompt(skills);
+}
+/** @deprecated Skills are now loaded on-demand via read_file */
+export function getSkillPrompt(skill) {
+    const parts = [`## Skill: ${skill.name}`, ""];
+    if (skill.frontmatter.compatibility) {
+        parts.push(`Compatibility: ${skill.frontmatter.compatibility}`, "");
+    }
+    parts.push(skill.body);
+    return parts.join("\n");
+}
+//# sourceMappingURL=loader.js.map

package/dist/src/skills/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../../src/skills/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAI3C,MAAM,cAAc,GAAG,UAAU,CAAC;AAElC,wCAAwC;AACxC,MAAM,oBAAoB,GAAG,GAAG,CAAC;AACjC,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAChC,MAAM,oBAAoB,GAAG,GAAG,GAAG,IAAI,CAAC,CAAC,SAAS;AAClD,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAElC,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,YAAoB,EACpB,MAAqB,EACrB,MAAe;IAEf,IAAI,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QAC9B,MAAM,EAAE,IAAI,CAAC,2BAA2B,CAAC,CAAC;QAC1C,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,MAAM,GAAkB,EAAE,CAAC;IACjC,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAC;IAEpC,2CAA2C;IAC3C,MAAM,kBAAkB,GAAG,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;IACxD,MAAM,YAAY,CAAC,kBAAkB,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;IAE/E,2CAA2C;IAC3C,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,aAAa,EAAE,QAAQ,CAAC,CAAC;IAC5D,IAAI,UAAU,KAAK,kBAAkB,EAAE,CAAC;QACtC,MAAM,YAAY,CAAC,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;IACvE,CAAC;IAED,mCAAmC;IACnC,IAAI,MAAM,EAAE,UAAU,EAAE,CAAC;QACvB,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;YACpC,MAAM,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;QAC9D,CAAC;IACH,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,EAAE,IAAI,CAAC,UAAU,MAAM,CAAC,MAAM,cAAc,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC5F,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,KAAK,UAAU,YAAY,CACzB,GAAW,EACX,MAA6B,EAC7B,MAAqB,EACrB,SAAsB,EACtB,MAAe;IAEf,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,wCAAwC;QACxC,OAAO;IACT,CAAC;IAED,IAAI,gBAAgB,GAAG,CAAC,CAAC;IAEzB,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,gBAAgB,IAAI,qBAAqB,EAAE,CAAC;YAC9C,MAAM,EAAE,IAAI,CAAC,8BAA8B,qBAAqB,SAAS,GAAG,EAAE,CAAC,CAAC;YAChF,MAAM;QACR,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAElC,sBAAsB;QACtB,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC/B,IAAI,CAAC,CAAC,CAAC,WAAW,EAAE;gBAAE,SAAS;QACjC,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QAED,wBAAwB;QACxB,MAAM,WAAW,GAAG,IAAI,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;QACnD,IAAI,GAAW,CAAC;QAChB,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,CAAC;YAClC,IAAI,CAAC,CAAC,IAAI,GAAG,oBAAoB,EAAE,CAAC;gBAClC,MAAM,EAAE,IAAI,CAAC,eAAe,QAAQ,YAAY,oBAAoB,GAAG,IAAI,eAAe,CAAC,CAAC;gBAC5F,SAAS;YACX,CAAC;YACD,GAAG,GAAG,MAAM,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QAC7C,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QAED,qBAAqB;QACrB,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,EAAE,IAAI,CAAC,uBAAuB,QAAQ,aAAa,CAAC,CAAC;YAC3D,SAAS;QACX,CAAC;QAED,iDAAiD;QACjD,MAAM,IAAI,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,IAAI,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAE3D,6EAA6E;QAC7E,IAAI,CAAC,yCAAyC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1D,MAAM,EAAE,IAAI,CAAC,UAAU,IAAI,sCAAsC,CAAC,CAAC;YACnE,SAAS;QACX,CAAC;QAED,6CAA6C;QAC7C,IAAI,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,MAAM,EAAE,IAAI,CAAC,UAAU,IAAI,UAAU,MAAM,uCAAuC,CAAC,CAAC;YACpF,SAAS;QACX,CAAC;QACD,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAEpB,MAAM,eAAe,GAAG,MAAM,CAAC,WAAW,CAAC,eAAe,CAAC,CAAC;QAC5D,MAAM,YAAY,GAAG,eAAe;YAClC,CAAC,CAAC,eAAe,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;YAC1D,CAAC,CAAC,EAAE,CAAC;QAEP,MAAM,CAAC,IAAI,CAAC;YACV,IAAI;YACJ,WAAW,EAAE,MAAM,CAAC,WAAW,CAAC,WAAW,IAAI,EAAE;YACjD,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,GAAG,EAAE,QAAQ;YACb,MAAM;YACN,cAAc,EAAE,MAAM,CAAC,WAAW,CAAC,0BAA0B,CAAC,KAAK,IAAI;YACvE,aAAa,EAAE,MAAM,CAAC,WAAW,CAAC,gBAAgB,CAAC,KAAK,KAAK;YAC7D,YAAY;SACb,CAAC,CAAC;QAEH,gBAAgB,EAAE,CAAC;IACrB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,WAAW,CAAC,CAAS;IAC5B,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IACvB,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACvB,OAAO,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAqB;IACrD,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC;IACxD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAErC,qCAAqC;IACrC,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,oBAAoB,CAAC,CAAC;IAEvD,MAAM,MAAM,GAAG;QACb,uBAAuB;QACvB,EAAE;QACF,kEAAkE;QAClE,iIAAiI;QACjI,mFAAmF;QACnF,oDAAoD;QACpD,uEAAuE;QACvE,8GAA8G;QAC9G,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEb,8CAA8C;IAC9C,MAAM,OAAO,GAAG,sBAAsB,CAAC;IACvC,MAAM,QAAQ,GAAG,qBAAqB,CAAC;IAEvC,IAAI,WAAW,GAAG,MAAM,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;IACnE,MAAM,YAAY,GAAa,EAAE,CAAC;IAElC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC,CAAC;QAC9D,MAAM,KAAK,GAAG;YACZ,WAAW;YACX,aAAa,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS;YAC3C,oBAAoB,SAAS,CAAC,KAAK,CAAC,WAAW,CAAC,gBAAgB;YAChE,iBAAiB,SAAS,CAAC,QAAQ,CAAC,aAAa;YACjD,YAAY;SACb,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEb,IAAI,WAAW,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,GAAG,gBAAgB,EAAE,CAAC;YACtD,MAAM;QACR,CAAC;QAED,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzB,WAAW,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,iBAAiB;IACpD,CAAC;IAED,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEzC,OAAO,MAAM,GAAG,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,QAAQ,CAAC;AACtE,CAAC;AAED,SAAS,SAAS,CAAC,CAAS;IAC1B,OAAO,CAAC;SACL,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;SACtB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AAC7B,CAAC;AAED,+CAA+C;AAE/C,gDAAgD;AAChD,MAAM,UAAU,eAAe,CAAC,MAAqB;IACnD,OAAO,iBAAiB,CAAC,MAAM,CAAC,CAAC;AACnC,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,cAAc,CAAC,KAAkB;IAC/C,MAAM,KAAK,GAAG,CAAC,aAAa,KAAK,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IAC9C,IAAI,KAAK,CAAC,WAAW,CAAC,aAAa,EAAE,CAAC;QACpC,KAAK,CAAC,IAAI,CAAC,kBAAkB,KAAK,CAAC,WAAW,CAAC,aAAa,EAAE,EAAE,EAAE,CAAC,CAAC;IACtE,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACvB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/src/skills/parser.d.ts

@@ -0,0 +1,13 @@
+/**
+ * SKILL.md frontmatter parser.
+ * Parses YAML frontmatter between --- markers without external dependencies.
+ */
+import type { SkillFrontmatter } from "./types.js";
+/**
+ * Parse a SKILL.md file into frontmatter + body.
+ * Returns null if the file doesn't have valid frontmatter.
+ */
+export declare function parseSkillMd(raw: string): {
+    frontmatter: SkillFrontmatter;
+    body: string;
+} | null;

package/dist/src/skills/parser.js

@@ -0,0 +1,84 @@
+/**
+ * SKILL.md frontmatter parser.
+ * Parses YAML frontmatter between --- markers without external dependencies.
+ */
+/**
+ * Parse a SKILL.md file into frontmatter + body.
+ * Returns null if the file doesn't have valid frontmatter.
+ */
+export function parseSkillMd(raw) {
+    const trimmed = raw.trimStart();
+    if (!trimmed.startsWith("---"))
+        return null;
+    const secondFence = trimmed.indexOf("---", 3);
+    if (secondFence === -1)
+        return null;
+    const yamlBlock = trimmed.slice(3, secondFence).trim();
+    const body = trimmed.slice(secondFence + 3).trim();
+    const frontmatter = parseSimpleYaml(yamlBlock);
+    if (!frontmatter.name && !frontmatter.description)
+        return null;
+    return { frontmatter: frontmatter, body };
+}
+/**
+ * Minimal YAML parser for flat key-value frontmatter.
+ * Handles strings, booleans, and simple nested metadata maps.
+ * Does NOT handle arrays, multi-line values, or complex YAML.
+ */
+function parseSimpleYaml(yaml) {
+    const result = {};
+    let currentKey = null;
+    let currentMap = null;
+    for (const line of yaml.split("\n")) {
+        // Blank line
+        if (line.trim() === "")
+            continue;
+        // Check indentation — if indented and we're in a map, it's a nested value
+        const indent = line.length - line.trimStart().length;
+        if (indent > 0 && currentMap !== null && currentKey !== null) {
+            const kvMatch = line.trim().match(/^([a-zA-Z0-9_.-]+):\s*(.*)/);
+            if (kvMatch) {
+                currentMap[kvMatch[1]] = unquote(kvMatch[2].trim());
+            }
+            continue;
+        }
+        // Close any open map
+        if (currentMap !== null && currentKey !== null) {
+            result[currentKey] = currentMap;
+            currentMap = null;
+            currentKey = null;
+        }
+        // Top-level key: value
+        const kvMatch = line.match(/^([a-zA-Z0-9_-]+):\s*(.*)/);
+        if (!kvMatch)
+            continue;
+        const key = kvMatch[1];
+        const rawValue = kvMatch[2].trim();
+        // Empty value — could be a map start
+        if (rawValue === "") {
+            currentKey = key;
+            currentMap = {};
+            continue;
+        }
+        result[key] = parseValue(rawValue);
+    }
+    // Close trailing map
+    if (currentMap !== null && currentKey !== null) {
+        result[currentKey] = currentMap;
+    }
+    return result;
+}
+function parseValue(raw) {
+    if (raw === "true")
+        return true;
+    if (raw === "false")
+        return false;
+    return unquote(raw);
+}
+function unquote(s) {
+    if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+        return s.slice(1, -1);
+    }
+    return s;
+}
+//# sourceMappingURL=parser.js.map

package/dist/src/skills/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../../../src/skills/parser.ts"],"names":[],"mappings":"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"}

package/dist/src/skills/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Agent Skills specification types.
+ * Compatible with OpenClaw, Claude Code, Codex, and ClawHub.
+ * Spec: https://agentskills.io/specification
+ */
+export interface SkillFrontmatter {
+    /** 1-64 chars, lowercase alphanumeric + hyphens, must match directory name */
+    name: string;
+    /** 1-1024 chars, describes what skill does and when to use it */
+    description: string;
+    /** License name or reference to bundled file */
+    license?: string;
+    /** Max 500 chars, environment requirements */
+    compatibility?: string;
+    /** Arbitrary key-value metadata (string to string) */
+    metadata?: Record<string, string>;
+    /** Space-delimited list of pre-approved tools */
+    "allowed-tools"?: string;
+    /** Expose as slash command (default: true) */
+    "user-invocable"?: boolean;
+    /** Prevent auto-invocation by LLM (default: false) */
+    "disable-model-invocation"?: boolean;
+    "argument-hint"?: string;
+    model?: string;
+    context?: string;
+    agent?: string;
+}
+export interface LoadedSkill {
+    /** Skill name (from frontmatter or directory name) */
+    name: string;
+    /** Short description for metadata-level loading */
+    description: string;
+    /** Full SKILL.md body (markdown after frontmatter) */
+    body: string;
+    /** Parsed frontmatter */
+    frontmatter: SkillFrontmatter;
+    /** Absolute path to skill directory */
+    dir: string;
+    /** Where the skill was loaded from */
+    source: "workspace" | "managed" | "bundled" | "extra";
+    /** Whether the LLM can auto-invoke this skill */
+    modelInvocable: boolean;
+    /** Whether the user can invoke as a slash command */
+    userInvocable: boolean;
+    /** Pre-approved tool names */
+    allowedTools: string[];
+}
+export interface SkillsConfig {
+    enabled: boolean;
+    /** Additional directories to scan for skills */
+    extra_dirs?: string[];
+}

package/dist/src/skills/types.js

@@ -0,0 +1,7 @@
+/**
+ * Agent Skills specification types.
+ * Compatible with OpenClaw, Claude Code, Codex, and ClawHub.
+ * Spec: https://agentskills.io/specification
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/skills/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/skills/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "freeturtle",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "description": "An open-source framework for deploying autonomous AI CEOs that run onchain businesses.",
   "type": "module",
   "main": "dist/bin/freeturtle.js",
@@ -17,7 +17,10 @@
     "build": "tsc",
     "dev": "tsc --watch",
     "lint": "eslint .",
-    "lint:fix": "eslint . --fix"
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
   },
   "keywords": [
     "ai",
@@ -36,9 +39,11 @@
     "@types/pg": "^8.18.0",
     "@types/qrcode-terminal": "^0.12.2",
     "@types/ws": "^8.18.1",
+    "@vitest/coverage-v8": "^4.0.18",
     "eslint": "^10.0.2",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.56.1"
+    "typescript-eslint": "^8.56.1",
+    "vitest": "^4.0.18"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.78.0",