min-agent 0.2.1 → 0.4.0

package/dist/skills.js

@@ -1,79 +1,452 @@
 import { tool, jsonSchema } from "ai";
-import { readFileSync, existsSync, readdirSync, statSync } from "fs";
+import { readFileSync, existsSync, readdirSync, realpathSync } from "fs";
 import os from "os";
 import path from "path";
+import { fileURLToPath } from "url";
 import { globSync } from "glob";
-import { loadConfig } from "./config.js";
+import { loadConfig, saveConfig, loadProjectConfig, saveProjectConfig } from "./config.js";
+import { truncateToolOutput } from "./tool-output.js";
+/** Packaged self-management skill; keep this name in sync with `skills/self-config/SKILL.md`. */
+export const SELF_CONFIG_SKILL = "self-config";
+function getPackageRoot() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+}
+export function getBuiltinSkillsDir() {
+    return path.join(getPackageRoot(), "skills");
+}
+function builtinSkillsAllowed() {
+    const value = process.env.MIN_AGENT_NO_BUILTIN_SKILLS?.trim().toLowerCase();
+    return value !== "1" && value !== "true";
+}
+function isUnderDir(root, filePath) {
+    const rel = path.relative(root, filePath);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+/** Coerce a config skill list to an array of names, tolerating hand-edited configs. */
+function skillNames(value) {
+    return Array.isArray(value) ? value.filter((n) => typeof n === "string") : [];
+}
+/**
+ * Effective enable state: project `.min-agent/config.json` wins over the global
+ * `~/.min-agent/config.json`, so disabling a repo-local skill in one project
+ * does not silently disable a same-named skill everywhere.
+ */
+function resolveSkillState() {
+    const project = loadProjectConfig();
+    const forced = new Set(skillNames(project.enabledSkills));
+    const disabled = new Set();
+    const scopeOf = new Map();
+    for (const name of skillNames(loadConfig().disabledSkills)) {
+        if (forced.has(name))
+            continue;
+        disabled.add(name);
+        scopeOf.set(name, "global");
+    }
+    for (const name of skillNames(project.disabledSkills)) {
+        disabled.add(name);
+        scopeOf.set(name, "project");
+    }
+    return { disabled, scopeOf };
+}
+function applyState(skill, state) {
+    const disabled = state.disabled.has(skill.name);
+    return {
+        ...skill,
+        enabled: !disabled,
+        ...(disabled ? { disabledScope: state.scopeOf.get(skill.name) } : {}),
+    };
+}
+/** Max SKILL.md depth below a skills root: `<skill>/SKILL.md` plus one nesting level. */
+const SKILL_SCAN_MAX_DEPTH = 3;
+/** Guard against pathological skill trees blowing up the system prompt. */
+const MAX_SKILL_FILES = 20;
+const SKILL_CONTENT_MAX_BYTES = 32 * 1024;
 /**
  * Skill scan order: later entries win on duplicate `name` in frontmatter.
  * Global user skills first, then project-local dirs so repo skills override ~/.agents.
+ * Computed lazily so process.cwd() changes are respected.
+ * `MIN_AGENT_SKILLS_DIRS` (path-delimiter separated) replaces the default user list.
+ * Packaged skills are scanned separately and win on name.
  */
-const SKILL_DIRS = [
-    path.join(os.homedir(), ".agents", "skills"),
-    path.join(process.cwd(), ".min-agent", "skills"),
-    path.join(process.cwd(), ".agent-demo", "skills"),
-    path.join(process.cwd(), ".opencode", "skills"),
-    path.join(process.cwd(), ".claude", "skills"),
-];
+function getSkillDirs() {
+    const override = process.env.MIN_AGENT_SKILLS_DIRS?.trim();
+    if (override) {
+        return override
+            .split(path.delimiter)
+            .map((dir) => dir.trim())
+            .filter(Boolean)
+            .map((dir) => path.resolve(dir));
+    }
+    return [
+        path.join(os.homedir(), ".agents", "skills"),
+        path.join(process.cwd(), ".min-agent", "skills"),
+        path.join(process.cwd(), ".agents", "skills"),
+        path.join(process.cwd(), ".opencode", "skills"),
+        path.join(process.cwd(), ".claude", "skills"),
+    ];
+}
 let loadedSkills = {};
-export function discoverSkills(opts) {
-    loadedSkills = {};
-    for (const dir of SKILL_DIRS) {
-        if (!existsSync(dir))
+const stderrWarn = (line) => process.stderr.write(`${line}\n`);
+/** Same underlying file? Symlinked skill libraries surface under several roots. */
+function sameFile(a, b) {
+    if (a === b)
+        return true;
+    try {
+        return realpathSync(a) === realpathSync(b);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Scan a skills root for SKILL.md files.
+ * Symlinked skill dirs are followed — sharing one skill library across
+ * `.claude/skills`, `.agents/skills`, … via symlink is a common setup.
+ * Within one root the shallowest SKILL.md wins for a given name, so the
+ * `<skill>/<skill>/SKILL.md` layout some installers produce doesn't shadow
+ * the canonical `<skill>/SKILL.md`.
+ */
+export function scanSkillDir(dir, warn = stderrWarn) {
+    if (!existsSync(dir))
+        return [];
+    const matches = globSync("**/SKILL.md", {
+        cwd: dir,
+        absolute: true,
+        follow: true,
+        maxDepth: SKILL_SCAN_MAX_DEPTH,
+        ignore: ["**/node_modules/**", "**/.git/**", "**/dist/**"],
+    }).sort((a, b) => a.split(path.sep).length - b.split(path.sep).length || a.localeCompare(b));
+    const byName = new Map();
+    for (const match of matches) {
+        const skill = parseSkillFile(match, warn);
+        if (!skill || byName.has(skill.name))
             continue;
-        const matches = globSync("**/SKILL.md", { cwd: dir, absolute: true });
-        for (const match of matches) {
-            const skill = parseSkillFile(match);
-            if (skill) {
-                if (loadedSkills[skill.name]) {
-                    console.warn(`\x1b[33m  ⚠ Duplicate skill "${skill.name}": ${match} overrides ${loadedSkills[skill.name].location}\x1b[0m`);
-                }
-                loadedSkills[skill.name] = skill;
-            }
+        byName.set(skill.name, skill);
+    }
+    return [...byName.values()];
+}
+function mergeSkill(next, skill, warn) {
+    const previous = next[skill.name];
+    if (previous && sameFile(previous.location, skill.location)) {
+        if (skill.builtin && !previous.builtin)
+            next[skill.name] = { ...previous, builtin: true };
+        return;
+    }
+    if (previous) {
+        const versionNote = previous.version && skill.version && previous.version !== skill.version
+            ? ` (version ${previous.version} → ${skill.version})`
+            : "";
+        warn?.(`\x1b[33m  ⚠ Duplicate skill "${skill.name}": ${skill.location} overrides ${previous.location}${versionNote}\x1b[0m`);
+    }
+    next[skill.name] = skill;
+}
+export function discoverSkills(opts) {
+    const warn = opts?.silent ? null : stderrWarn;
+    const next = {};
+    for (const dir of getSkillDirs()) {
+        for (const skill of scanSkillDir(dir, warn))
+            mergeSkill(next, skill, warn);
+    }
+    if (builtinSkillsAllowed()) {
+        const builtinDir = getBuiltinSkillsDir();
+        for (const skill of scanSkillDir(builtinDir, warn)) {
+            mergeSkill(next, { ...skill, builtin: isUnderDir(builtinDir, skill.location) }, warn);
         }
     }
+    const state = resolveSkillState();
+    loadedSkills = Object.fromEntries(Object.entries(next).map(([name, skill]) => [name, applyState(skill, state)]));
     const count = Object.keys(loadedSkills).length;
     if (count > 0 && !opts?.silent) {
-        const disabled = new Set(loadConfig().disabledSkills ?? []);
-        const enabledCount = Object.keys(loadedSkills).filter((n) => !disabled.has(n)).length;
-        console.log(`\x1b[90m  Skills: ${enabledCount} enabled${count > enabledCount ? `, ${count - enabledCount} disabled` : ""}\x1b[0m`);
+        const enabledCount = Object.values(loadedSkills).filter((s) => s.enabled).length;
+        warn?.(`\x1b[90m  Skills: ${enabledCount} enabled${count > enabledCount ? `, ${count - enabledCount} disabled` : ""}\x1b[0m`);
+    }
+}
+function unquote(value) {
+    const trimmed = value.trim();
+    const quoted = trimmed.match(/^"([\s\S]*)"$/) ?? trimmed.match(/^'([\s\S]*)'$/);
+    return quoted ? quoted[1] : trimmed;
+}
+/**
+ * Read one top-level frontmatter key.
+ * Supports `key: value`, quoted values, plain multi-line scalars, and block
+ * scalars (`|`, `>`, `|-`, `>-`) — all of which real-world SKILL.md files use
+ * for long descriptions.
+ */
+export function readFrontmatterValue(frontmatter, key) {
+    const lines = frontmatter.split("\n");
+    const index = lines.findIndex((line) => new RegExp(`^${key}:(\\s|$)`).test(line));
+    if (index === -1)
+        return null;
+    const inline = lines[index].slice(key.length + 1).trim();
+    const isBlockScalar = /^[|>][+-]?\d*$/.test(inline);
+    const body = [];
+    for (const line of lines.slice(index + 1)) {
+        if (line.trim() !== "" && !/^\s/.test(line))
+            break;
+        body.push(line.replace(/^\s+/, ""));
+    }
+    if (inline && !isBlockScalar) {
+        // Plain scalar: indented follow-up lines are continuations, joined by spaces.
+        const continuation = body.filter((l) => l !== "").join(" ");
+        return unquote(continuation ? `${inline} ${continuation}` : inline);
     }
+    const joined = isBlockScalar && inline.startsWith(">") ? body.join(" ") : body.join("\n");
+    const value = joined.trim();
+    return value === "" ? null : value;
 }
-function parseSkillFile(filePath) {
+/** Read a YAML list, either `key: [a, b]` or a `- item` block. */
+function readFrontmatterList(frontmatter, key) {
+    const lines = frontmatter.split("\n");
+    const index = lines.findIndex((line) => new RegExp(`^\\s*${key}:(\\s|$)`).test(line));
+    if (index === -1)
+        return [];
+    const header = lines[index];
+    const indent = header.match(/^\s*/)[0].length;
+    const inline = header.slice(header.indexOf(":") + 1).trim();
+    const flow = inline.match(/^\[([\s\S]*)\]$/);
+    if (flow) {
+        return flow[1]
+            .split(",")
+            .map((item) => unquote(item))
+            .filter(Boolean);
+    }
+    if (inline)
+        return [unquote(inline)].filter(Boolean);
+    const items = [];
+    for (const line of lines.slice(index + 1)) {
+        if (line.trim() === "")
+            continue;
+        const currentIndent = line.match(/^\s*/)[0].length;
+        if (currentIndent <= indent)
+            break;
+        const item = line.trim();
+        if (!item.startsWith("- "))
+            break;
+        items.push(unquote(item.slice(2)));
+    }
+    return items;
+}
+/**
+ * Read `metadata.requires.bins` from a frontmatter block. Resolves the nested
+ * path explicitly so a stray top-level `bins:` key cannot be misread.
+ */
+function readRequiredBins(frontmatter) {
+    const lines = frontmatter.split("\n");
+    const metaIdx = lines.findIndex((line) => /^metadata:(\s|$)/.test(line));
+    if (metaIdx === -1)
+        return [];
+    const metaIndent = lines[metaIdx].match(/^\s*/)[0].length;
+    const requiresIdx = lines.slice(metaIdx + 1).findIndex((line) => {
+        if (line.trim() === "" || /^\s*$/.test(line))
+            return false;
+        const indent = line.match(/^\s*/)[0].length;
+        return indent > metaIndent && /^requires:(\s|$)/.test(line.trim());
+    });
+    if (requiresIdx === -1)
+        return [];
+    const requiresLine = lines[metaIdx + 1 + requiresIdx];
+    const requiresIndent = requiresLine.match(/^\s*/)[0].length;
+    const binsIdx = lines.slice(metaIdx + 1 + requiresIdx + 1).findIndex((line) => {
+        if (line.trim() === "" || /^\s*$/.test(line))
+            return false;
+        const indent = line.match(/^\s*/)[0].length;
+        return indent > requiresIndent && /^bins:(\s|$)/.test(line.trim());
+    });
+    if (binsIdx === -1)
+        return [];
+    const block = lines.slice(metaIdx + 1 + requiresIdx + 1 + binsIdx).join("\n");
+    return readFrontmatterList(block, "bins");
+}
+function parseSkillFile(filePath, warn) {
+    let raw;
     try {
-        const raw = readFileSync(filePath, "utf-8");
-        const fmMatch = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
-        if (!fmMatch)
-            return null;
-        const frontmatter = fmMatch[1];
-        const content = fmMatch[2];
-        const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
-        const descMatch = frontmatter.match(/^description:\s*(.+)$/m);
-        if (!nameMatch || !descMatch)
-            return null;
-        return {
-            name: nameMatch[1].trim().replace(/^["']|["']$/g, ""),
-            description: descMatch[1].trim().replace(/^["']|["']$/g, ""),
-            location: filePath,
-            content: content.trim(),
-        };
+        raw = readFileSync(filePath, "utf-8")
+            .replace(/^\uFEFF/, "")
+            .replace(/\r\n/g, "\n");
     }
-    catch {
+    catch (err) {
+        warn?.(`\x1b[33m  ⚠ Skill skipped (unreadable): ${filePath} — ${err.message}\x1b[0m`);
+        return null;
+    }
+    const fmMatch = raw.match(/^---[ \t]*\n([\s\S]*?)\n---[ \t]*(?:\n([\s\S]*))?$/);
+    if (!fmMatch) {
+        warn?.(`\x1b[33m  ⚠ Skill skipped (missing --- frontmatter block): ${filePath}\x1b[0m`);
+        return null;
+    }
+    const frontmatter = fmMatch[1];
+    const name = readFrontmatterValue(frontmatter, "name");
+    const description = readFrontmatterValue(frontmatter, "description");
+    const missing = [!name && "name", !description && "description"].filter(Boolean);
+    if (!name || !description) {
+        warn?.(`\x1b[33m  ⚠ Skill skipped (frontmatter missing ${missing.join(", ")}): ${filePath}\x1b[0m`);
         return null;
     }
+    return {
+        name,
+        description,
+        location: filePath,
+        content: (fmMatch[2] ?? "").trim(),
+        enabled: true,
+        allowedTools: readFrontmatterList(frontmatter, "allowed-tools"),
+        requiredBins: readRequiredBins(frontmatter),
+        version: readFrontmatterValue(frontmatter, "version") ?? undefined,
+        builtin: false,
+        alwaysLoad: readFrontmatterBool(frontmatter, "always-load"),
+    };
+}
+function readFrontmatterBool(frontmatter, key) {
+    const raw = readFrontmatterValue(frontmatter, key);
+    if (raw == null)
+        return false;
+    const value = raw.trim().toLowerCase();
+    return value === "true" || value === "yes" || value === "1";
+}
+/** Every discovered skill, disabled ones included (`enabled` reflects config). */
+export function getAllSkills() {
+    const state = resolveSkillState();
+    return Object.values(loadedSkills).map((s) => applyState(s, state));
 }
 export function getSkills() {
-    const disabled = new Set(loadConfig().disabledSkills ?? []);
-    return Object.values(loadedSkills).filter((s) => !disabled.has(s.name));
+    return getAllSkills().filter((s) => s.enabled);
 }
 export function getSkill(name) {
-    return loadedSkills[name];
+    const skill = loadedSkills[name];
+    return skill ? applyState(skill, resolveSkillState()) : undefined;
+}
+/** Disabled or force-enabled names in either scope that match no discovered skill. */
+export function getStaleDisabledSkills() {
+    const project = loadProjectConfig();
+    const names = new Set([
+        ...skillNames(loadConfig().disabledSkills),
+        ...skillNames(project.disabledSkills),
+        ...skillNames(project.enabledSkills),
+    ]);
+    return [...names].filter((name) => !loadedSkills[name]);
+}
+/**
+ * Toggle skills in one scope.
+ * Project scope wins over global: enabling in project scope records an explicit
+ * override so a globally disabled skill stays available in this repo.
+ * Returns per-skill effective state plus the scope that still disables it, if any.
+ */
+export function setSkillEnabled(names, enabled, scope) {
+    if (scope === "global") {
+        const config = loadConfig();
+        const disabled = new Set(skillNames(config.disabledSkills));
+        for (const name of names) {
+            if (enabled)
+                disabled.delete(name);
+            else
+                disabled.add(name);
+        }
+        config.disabledSkills = [...disabled];
+        saveConfig(config);
+    }
+    else {
+        const project = loadProjectConfig();
+        const disabled = new Set(skillNames(project.disabledSkills));
+        const forced = new Set(skillNames(project.enabledSkills));
+        const globallyDisabled = new Set(skillNames(loadConfig().disabledSkills));
+        for (const name of names) {
+            if (enabled) {
+                disabled.delete(name);
+                if (globallyDisabled.has(name))
+                    forced.add(name);
+                else
+                    forced.delete(name);
+            }
+            else {
+                disabled.add(name);
+                forced.delete(name);
+            }
+        }
+        saveProjectConfig({ ...project, disabledSkills: [...disabled], enabledSkills: [...forced] });
+    }
+    const state = resolveSkillState();
+    return names.map((name) => {
+        const effective = !state.disabled.has(name);
+        return {
+            name,
+            enabled: effective,
+            ...(effective === enabled ? {} : { blockedBy: state.scopeOf.get(name) }),
+        };
+    });
+}
+function listSkillFiles(dir) {
+    const out = [];
+    let total = 0;
+    const walk = (current, depth) => {
+        let dirents;
+        try {
+            dirents = readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const d of dirents) {
+            if (d.name === "SKILL.md" || d.name.startsWith("."))
+                continue;
+            total++;
+            if (out.length < MAX_SKILL_FILES) {
+                out.push(d.isDirectory() ? `${path.join(current, d.name)}/` : path.join(current, d.name));
+            }
+            if (d.isDirectory() && depth > 0)
+                walk(path.join(current, d.name), depth - 1);
+        }
+    };
+    walk(dir, 2);
+    return { entries: out.sort(), total };
+}
+function missingBins(bins) {
+    if (bins.length === 0)
+        return [];
+    const dirs = (process.env.PATH ?? "").split(path.delimiter).filter(Boolean);
+    const exts = process.platform === "win32" ? ["", ".exe", ".cmd", ".bat", ".ps1"] : [""];
+    const has = (bin) => dirs.some((d) => exts.some((ext) => existsSync(path.join(d, `${bin}${ext}`))));
+    return bins.filter((bin) => !has(bin));
+}
+export function buildSkillContent(skill) {
+    const dir = path.dirname(skill.location);
+    const { entries, total } = listSkillFiles(dir);
+    const absent = missingBins(skill.requiredBins);
+    const body = [
+        `<skill_content name="${escapeXmlAttr(skill.name)}">`,
+        `# Skill: ${skill.name}`,
+        "",
+        `Base directory for this skill: ${dir}`,
+        "Relative paths in this skill (e.g., scripts/, reference/) are relative to this base directory.",
+        "",
+        skill.allowedTools.length
+            ? `This skill declares allowed-tools: ${escapeXml(skill.allowedTools.join(", "))}. Prefer these tools while the skill is active.`
+            : "",
+        absent.length
+            ? `⚠ Required binaries not found on PATH: ${absent.join(", ")}. Tell the user to install them before running this skill's commands.`
+            : "",
+        entries.length
+            ? [
+                "<skill_files>",
+                ...entries.map((f) => `  <file>${escapeXml(f)}</file>`),
+                total > entries.length
+                    ? `  <note>${total - entries.length} more entries not listed; use glob on the base directory</note>`
+                    : "",
+                "</skill_files>",
+            ]
+                .filter(Boolean)
+                .join("\n")
+            : "",
+        "",
+        skill.content,
+        `</skill_content>`,
+    ]
+        .filter(Boolean)
+        .join("\n");
+    return truncateToolOutput(body, { direction: "head", maxBytes: SKILL_CONTENT_MAX_BYTES }).content;
 }
 /**
  * Skill tool — content is loaded on-demand when the model calls this tool.
  * The tool description is kept minimal; the full skill list lives in the system prompt.
  */
-export function getSkillsTool() {
+export function getSkillsTool(tracker = new Set()) {
     return tool({
         description: "Load a specialized skill when the task at hand matches one of the skills listed in the system prompt. " +
             "Use this tool to inject the skill's instructions and resources into the current conversation. " +
@@ -86,60 +459,141 @@ export function getSkillsTool() {
             required: ["name"],
         }),
         execute: async ({ name }) => {
-            const disabled = new Set(loadConfig().disabledSkills ?? []);
-            if (disabled.has(name)) {
-                return `Skill "${name}" is disabled. Available skills: ${getSkills().map((s) => s.name).join(", ") || "none"}`;
+            const state = resolveSkillState();
+            const available = Object.keys(loadedSkills)
+                .filter((n) => !state.disabled.has(n))
+                .sort();
+            if (state.disabled.has(name)) {
+                return `Skill "${name}" is disabled (${state.scopeOf.get(name)} scope). Available skills: ${available.join(", ") || "none"}`;
             }
             const skill = loadedSkills[name];
             if (!skill) {
-                const available = getSkills().map((s) => s.name);
                 return `Skill "${name}" not found. Available skills: ${available.length ? available.join(", ") : "none"}`;
             }
-            const dir = path.dirname(skill.location);
-            let files = [];
-            try {
-                files = readdirSync(dir)
-                    .filter((f) => f !== "SKILL.md" && !statSync(path.join(dir, f)).isDirectory())
-                    .slice(0, 10);
+            if (tracker.has(name)) {
+                return `Skill "${name}" is already loaded in this conversation — its instructions are still in effect above. Base directory: ${path.dirname(skill.location)}`;
             }
-            catch { }
-            return [
-                `<skill_content name="${skill.name}">`,
-                `# Skill: ${skill.name}`,
-                "",
-                skill.content,
-                "",
-                `Base directory for this skill: ${dir}`,
-                "Relative paths in this skill (e.g., scripts/, reference/) are relative to this base directory.",
-                "",
-                files.length ? `<skill_files>\n${files.map((f) => `  <file>${path.join(dir, f)}</file>`).join("\n")}\n</skill_files>` : "",
-                `</skill_content>`,
-            ]
-                .filter(Boolean)
-                .join("\n");
+            tracker.add(name);
+            return buildSkillContent(skill);
         },
     });
 }
+function escapeXml(value) {
+    return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function escapeXmlAttr(value) {
+    return escapeXml(value).replace(/"/g, "&quot;");
+}
+/** Reverse of `escapeXmlAttr` — used to recover the raw skill name from a marker. */
+function unescapeXmlAttr(value) {
+    return value
+        .replace(/&quot;/g, '"')
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&amp;/g, "&");
+}
 /**
  * System prompt section — verbose XML format for better model comprehension.
  * Only name/description/location are injected; content is loaded on-demand via the skill tool.
  */
-export function getSkillsSystemPrompt() {
-    const skills = getSkills();
+export function buildSkillsPrompt(skills) {
     if (skills.length === 0)
         return "";
+    const hasAlwaysLoad = skills.some((s) => s.alwaysLoad);
     return [
         "Skills provide specialized instructions and workflows for specific tasks.",
         "Use the skill tool to load a skill when a task matches its description.",
+        hasAlwaysLoad
+            ? "Skills with always_load already have their full instructions in this prompt. Do not call the skill tool for those unless compaction dropped them."
+            : "",
         "",
         "<available_skills>",
         ...skills.flatMap((s) => [
             "  <skill>",
-            `    <name>${s.name}</name>`,
-            `    <description>${s.description}</description>`,
-            `    <location>${s.location}</location>`,
+            `    <name>${escapeXml(s.name)}</name>`,
+            `    <description>${escapeXml(s.description)}</description>`,
+            `    <location>${escapeXml(s.location)}</location>`,
+            s.alwaysLoad ? "    <always_load>true</always_load>" : "",
+            s.builtin ? "    <builtin>true</builtin>" : "",
             "  </skill>",
         ]),
         "</available_skills>",
+    ]
+        .filter((line) => line !== "")
+        .join("\n");
+}
+const SKILL_CONTENT_MARKER = /<skill_content name="([^"]*)"/g;
+function textOf(part) {
+    if (typeof part === "string")
+        return part;
+    if (!part || typeof part !== "object")
+        return "";
+    const rec = part;
+    if (typeof rec.text === "string")
+        return rec.text;
+    const output = rec.output;
+    if (typeof output === "string")
+        return output;
+    if (output && typeof output === "object" && typeof output.value === "string") {
+        return output.value;
+    }
+    return "";
+}
+/** Skills whose content is already present in the conversation. */
+export function collectLoadedSkillNames(messages) {
+    const names = new Set();
+    const scan = (text) => {
+        for (const m of text.matchAll(SKILL_CONTENT_MARKER))
+            names.add(unescapeXmlAttr(m[1]));
+    };
+    for (const msg of messages) {
+        if (typeof msg.content === "string")
+            scan(msg.content);
+        else if (Array.isArray(msg.content))
+            for (const part of msg.content)
+                scan(textOf(part));
+    }
+    return names;
+}
+/**
+ * Note appended to a compaction summary: the skill instructions themselves are
+ * gone with the summarized history, so the model is told what was active and
+ * how to get it back.
+ */
+export function buildSkillReloadNote(names) {
+    if (names.length === 0)
+        return "";
+    const withDirs = names.map((name) => {
+        const skill = loadedSkills[name];
+        return skill ? `${name} (base dir: ${path.dirname(skill.location)})` : name;
+    });
+    return [
+        "## Skills Previously Loaded",
+        ...withDirs.map((entry) => `- ${entry}`),
+        "Their full instructions were dropped during compaction. Re-call the skill tool if you still need them.",
+    ].join("\n");
+}
+/**
+ * Single entry point for wiring skills into an agent: registers the `skill`
+ * tool and returns the matching system-prompt section. Keeping both sides here
+ * prevents the tool from being registered without `available_skills` in the prompt.
+ */
+export function attachSkills(tools, tracker) {
+    const skills = getSkills();
+    if (skills.length === 0)
+        return "";
+    const loadTracker = tracker ?? new Set();
+    const auto = skills.filter((s) => s.alwaysLoad);
+    for (const skill of auto)
+        loadTracker.add(skill.name);
+    tools.skill = getSkillsTool(loadTracker);
+    const catalog = buildSkillsPrompt(skills);
+    if (auto.length === 0)
+        return catalog;
+    return [
+        catalog,
+        "",
+        "The following skills are already loaded for this conversation. Follow them without calling the skill tool again.",
+        ...auto.map(buildSkillContent),
     ].join("\n");
 }

package/dist/synthetic.js

@@ -0,0 +1,7 @@
+const synthetic = new WeakSet();
+export function markSyntheticMessage(msg) {
+    synthetic.add(msg);
+}
+export function isSyntheticMessage(msg) {
+    return synthetic.has(msg);
+}