veryfront 0.1.48 → 0.1.49

package/esm/src/skill/parser.js

@@ -0,0 +1,162 @@
+/**
+ * Skill frontmatter parser
+ *
+ * Parses SKILL.md files with YAML frontmatter.
+ * Primary parser: gray-matter shim (#std/front-matter/yaml.ts)
+ * Fallback: regex + line-by-line parser
+ *
+ * @module
+ */
+import { createError, toError } from "../errors/veryfront-error.js";
+import { SKILL_ALLOWED_TOOL_PATTERN_REGEX, SKILL_DESCRIPTION_MAX_LENGTH, SKILL_NAME_REGEX, } from "./types.js";
+/**
+ * Parse SKILL.md content into frontmatter + body.
+ *
+ * Uses gray-matter shim as primary parser with a regex fallback
+ * for environments where gray-matter is not available.
+ */
+export async function parseSkillFrontmatter(content) {
+    // Try primary parser: gray-matter shim
+    try {
+        const { extract } = await import("../platform/compat/std/front-matter-yaml.js");
+        const result = extract(content);
+        return { frontmatter: result.attrs, body: result.body };
+    }
+    catch {
+        // Fall through to fallback
+    }
+    // Fallback: regex-based parser
+    return parseFrontmatterFallback(content);
+}
+/**
+ * Regex-based fallback parser for YAML frontmatter.
+ * Handles simple key: value pairs (no nested YAML).
+ */
+function parseFrontmatterFallback(content) {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+    if (!match) {
+        return { frontmatter: {}, body: content };
+    }
+    const rawFrontmatter = match[1];
+    const body = match[2];
+    const frontmatter = {};
+    for (const line of rawFrontmatter.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const colonIndex = trimmed.indexOf(":");
+        if (colonIndex === -1)
+            continue;
+        const key = trimmed.slice(0, colonIndex).trim();
+        const value = trimmed.slice(colonIndex + 1).trim();
+        frontmatter[key] = value;
+    }
+    return { frontmatter, body };
+}
+/**
+ * Validate and normalize parsed frontmatter into SkillMetadata.
+ *
+ * @param frontmatter - Parsed frontmatter object
+ * @param directoryName - Directory name used as fallback for skill name
+ */
+export function validateSkillMetadata(frontmatter, directoryName) {
+    // Name: from frontmatter or directory name
+    const rawName = typeof frontmatter.name === "string" ? frontmatter.name.trim() : directoryName;
+    if (!SKILL_NAME_REGEX.test(rawName)) {
+        throw toError(createError({
+            type: "agent",
+            message: `Invalid skill name "${rawName}": must be lowercase alphanumeric with hyphens, 1-64 characters`,
+        }));
+    }
+    // Description: required
+    const rawDescription = frontmatter.description;
+    if (!rawDescription || typeof rawDescription !== "string" || !rawDescription.trim()) {
+        throw toError(createError({
+            type: "agent",
+            message: `Skill "${rawName}" is missing a required "description" field`,
+        }));
+    }
+    const description = rawDescription.trim().slice(0, SKILL_DESCRIPTION_MAX_LENGTH);
+    // Allowed-tools: parse from space-delimited string or array
+    const allowedTools = parseAllowedTools(frontmatter["allowed-tools"], rawName);
+    // License: optional string passthrough
+    const license = typeof frontmatter.license === "string" ? frontmatter.license.trim() : undefined;
+    // Compatibility: optional string passthrough
+    const compatibility = typeof frontmatter.compatibility === "string"
+        ? frontmatter.compatibility.trim()
+        : undefined;
+    // Metadata: convert nested object values to strings
+    const metadata = parseMetadata(frontmatter.metadata);
+    return {
+        name: rawName,
+        description,
+        ...(allowedTools && { allowedTools }),
+        ...(license && { license }),
+        ...(compatibility && { compatibility }),
+        ...(metadata && { metadata }),
+    };
+}
+/**
+ * Parse `allowed-tools` from frontmatter.
+ * Accepts a space-delimited string or an array of strings.
+ * Validates each pattern against SKILL_ALLOWED_TOOL_PATTERN_REGEX.
+ */
+function parseAllowedTools(value, skillName) {
+    if (value === undefined || value === null)
+        return undefined;
+    let patterns;
+    if (typeof value === "string") {
+        patterns = value.split(/\s+/).filter(Boolean);
+    }
+    else if (Array.isArray(value)) {
+        patterns = [];
+        for (const rawPattern of value) {
+            if (typeof rawPattern !== "string") {
+                throw toError(createError({
+                    type: "agent",
+                    message: `Skill "${skillName}" has invalid allowed-tools value: expected all entries to be strings`,
+                }));
+            }
+            const pattern = rawPattern.trim();
+            if (!pattern) {
+                throw toError(createError({
+                    type: "agent",
+                    message: `Skill "${skillName}" has invalid allowed-tools pattern: empty value`,
+                }));
+            }
+            patterns.push(pattern);
+        }
+    }
+    else {
+        throw toError(createError({
+            type: "agent",
+            message: `Skill "${skillName}" has invalid allowed-tools value: expected a string or array of strings, got ${typeof value}`,
+        }));
+    }
+    if (patterns.length === 0)
+        return undefined;
+    // Validate each pattern (fail closed)
+    for (const pattern of patterns) {
+        if (!SKILL_ALLOWED_TOOL_PATTERN_REGEX.test(pattern)) {
+            throw toError(createError({
+                type: "agent",
+                message: `Skill "${skillName}" has invalid allowed-tools pattern "${pattern}". ` +
+                    `Only exact tool IDs (e.g. "Read") and prefix wildcards (e.g. "api:*") are supported.`,
+            }));
+        }
+    }
+    return patterns;
+}
+/** Convert metadata object values to strings */
+function parseMetadata(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const entries = Object.entries(value);
+    if (entries.length === 0)
+        return undefined;
+    const result = {};
+    for (const [k, v] of entries) {
+        result[k] = String(v);
+    }
+    return result;
+}

package/esm/src/skill/path-safety.d.ts

@@ -0,0 +1,22 @@
+import type { FileSystemAdapter } from "../platform/adapters/base.js";
+/**
+ * Validate that a requested path is safe within a skill's root directory.
+ *
+ * @param skillRoot - Absolute path to the skill directory
+ * @param requestedPath - Relative path requested (e.g. "references/CLAUSES.md")
+ * @param allowedSubdirs - Allowed top-level subdirectories (e.g. ["references", "assets"])
+ * @param fsAdapter - Optional file system adapter for VFS/cloud-backed projects
+ * @returns The validated canonical path
+ * @throws If the path is invalid, escapes the skill root, or the file doesn't exist
+ */
+export declare function validateSkillPath(skillRoot: string, requestedPath: string, allowedSubdirs: string[], fsAdapter?: FileSystemAdapter): Promise<string>;
+/**
+ * List files in a skill subdirectory.
+ *
+ * @param skillRoot - Absolute path to the skill directory
+ * @param subdir - Subdirectory name (e.g. "references", "scripts")
+ * @param fsAdapter - Optional file system adapter for VFS/cloud-backed projects
+ * @returns Array of relative paths like "references/filename.md"
+ */
+export declare function listSkillSubdir(skillRoot: string, subdir: string, fsAdapter?: FileSystemAdapter): Promise<string[]>;
+//# sourceMappingURL=path-safety.d.ts.map

package/esm/src/skill/path-safety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-safety.d.ts","sourceRoot":"","sources":["../../../src/src/skill/path-safety.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAiFtE;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,EAAE,EACxB,SAAS,CAAC,EAAE,iBAAiB,GAC5B,OAAO,CAAC,MAAM,CAAC,CA2DjB;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,iBAAiB,GAC5B,OAAO,CAAC,MAAM,EAAE,CAAC,CAkBnB"}

package/esm/src/skill/path-safety.js

@@ -0,0 +1,156 @@
+/**
+ * Skill path safety
+ *
+ * Validates file paths within skill directories to prevent traversal attacks.
+ * Uses centralized validatePath() from #veryfront/security.
+ *
+ * @module
+ */
+import * as dntShim from "../../_dnt.shims.js";
+import { validatePath } from "../security/index.js";
+import { isAbsolute, join, relative, resolve } from "../platform/compat/path/index.js";
+import { exists, readDir, stat } from "../platform/compat/fs.js";
+import { createError, toError } from "../errors/veryfront-error.js";
+function isInsideDir(baseDir, targetPath) {
+    const rel = relative(baseDir, targetPath);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+async function pathExists(path, fsAdapter) {
+    return fsAdapter ? await fsAdapter.exists(path) : await exists(path);
+}
+async function assertIsFile(path, fsAdapter) {
+    const info = fsAdapter ? await fsAdapter.stat(path) : await stat(path);
+    if (!info.isFile) {
+        throw toError(createError({
+            type: "agent",
+            message: `Skill path must point to a file: "${path}"`,
+        }));
+    }
+}
+async function resolveLocalRealPath(path) {
+    if (typeof dntShim.Deno !== "undefined") {
+        return await dntShim.Deno.realPath(path);
+    }
+    const fs = await import("node:fs/promises");
+    return await fs.realpath(path);
+}
+async function isLocalSymlink(path) {
+    try {
+        if (typeof dntShim.Deno !== "undefined") {
+            const info = await dntShim.Deno.lstat(path);
+            return info.isSymlink;
+        }
+        const fs = await import("node:fs/promises");
+        const info = await fs.lstat(path);
+        return info.isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+async function isAdapterSymlink(fsAdapter, parentDir, segment) {
+    for await (const entry of fsAdapter.readDir(parentDir)) {
+        if (entry.name !== segment)
+            continue;
+        return entry.isSymlink;
+    }
+    return false;
+}
+async function hasSymlinkInPath(skillRoot, canonicalPath, fsAdapter) {
+    const resolvedRoot = resolve(skillRoot);
+    const resolvedTarget = resolve(canonicalPath);
+    const rel = relative(resolvedRoot, resolvedTarget).replaceAll("\\", "/");
+    if (!rel)
+        return false;
+    if (rel.startsWith("..") || isAbsolute(rel))
+        return true;
+    let current = resolvedRoot;
+    for (const segment of rel.split("/").filter(Boolean)) {
+        if (fsAdapter) {
+            if (await isAdapterSymlink(fsAdapter, current, segment))
+                return true;
+        }
+        else if (await isLocalSymlink(join(current, segment))) {
+            return true;
+        }
+        current = join(current, segment);
+    }
+    return false;
+}
+/**
+ * Validate that a requested path is safe within a skill's root directory.
+ *
+ * @param skillRoot - Absolute path to the skill directory
+ * @param requestedPath - Relative path requested (e.g. "references/CLAUSES.md")
+ * @param allowedSubdirs - Allowed top-level subdirectories (e.g. ["references", "assets"])
+ * @param fsAdapter - Optional file system adapter for VFS/cloud-backed projects
+ * @returns The validated canonical path
+ * @throws If the path is invalid, escapes the skill root, or the file doesn't exist
+ */
+export async function validateSkillPath(skillRoot, requestedPath, allowedSubdirs, fsAdapter) {
+    const result = await validatePath(requestedPath, {
+        baseDir: skillRoot,
+        allowedDirs: allowedSubdirs,
+        level: "strict",
+        allowAbsolute: false,
+    });
+    if (!result.valid) {
+        throw toError(createError({
+            type: "agent",
+            message: `Skill path validation failed for "${requestedPath}": ${result.error ?? "access denied"}`,
+        }));
+    }
+    const canonicalPath = result.canonicalPath;
+    // Verify the path exists and points to a file.
+    if (!(await pathExists(canonicalPath, fsAdapter))) {
+        throw toError(createError({
+            type: "agent",
+            message: `File not found: "${requestedPath}" in skill directory`,
+        }));
+    }
+    await assertIsFile(canonicalPath, fsAdapter);
+    // Enforce strict no-symlink policy for skill files.
+    if (await hasSymlinkInPath(skillRoot, canonicalPath, fsAdapter)) {
+        throw toError(createError({
+            type: "agent",
+            message: `Skill path contains a symlink and is not allowed: "${requestedPath}"`,
+        }));
+    }
+    // Defense-in-depth: local realpath check to block symlink escapes.
+    if (!fsAdapter) {
+        const [realRoot, realTarget] = await Promise.all([
+            resolveLocalRealPath(skillRoot),
+            resolveLocalRealPath(canonicalPath),
+        ]);
+        if (!isInsideDir(realRoot, realTarget)) {
+            throw toError(createError({
+                type: "agent",
+                message: `Skill path escapes root directory via symlink: "${requestedPath}"`,
+            }));
+        }
+    }
+    return canonicalPath;
+}
+/**
+ * List files in a skill subdirectory.
+ *
+ * @param skillRoot - Absolute path to the skill directory
+ * @param subdir - Subdirectory name (e.g. "references", "scripts")
+ * @param fsAdapter - Optional file system adapter for VFS/cloud-backed projects
+ * @returns Array of relative paths like "references/filename.md"
+ */
+export async function listSkillSubdir(skillRoot, subdir, fsAdapter) {
+    const dirPath = join(skillRoot, subdir);
+    const dirExists = fsAdapter ? await fsAdapter.exists(dirPath) : await exists(dirPath);
+    if (!dirExists) {
+        return [];
+    }
+    const files = [];
+    const entries = fsAdapter ? fsAdapter.readDir(dirPath) : readDir(dirPath);
+    for await (const entry of entries) {
+        if (entry.isFile) {
+            files.push(`${subdir}/${entry.name}`);
+        }
+    }
+    return files;
+}

package/esm/src/skill/prompt-augmentation.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Skill Prompt Augmentation
+ *
+ * Builds the skill manifest section that gets appended to agent system prompts.
+ *
+ * @module
+ */
+import type { Skill } from "./types.js";
+/**
+ * Build the skill manifest prompt section for an agent's system prompt.
+ *
+ * Lists all available skills with their descriptions and instructions
+ * on how to use the skill tools (load-skill, load-skill-reference, execute-skill-script).
+ *
+ * @param skills - Map of resolved skills for the agent
+ * @returns Prompt section string, or empty string if no skills
+ */
+export declare function buildSkillManifestPrompt(skills: Map<string, Skill>): string;
+//# sourceMappingURL=prompt-augmentation.d.ts.map

package/esm/src/skill/prompt-augmentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-augmentation.d.ts","sourceRoot":"","sources":["../../../src/src/skill/prompt-augmentation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,MAAM,CA4B3E"}

package/esm/src/skill/prompt-augmentation.js

@@ -0,0 +1,36 @@
+/**
+ * Skill Prompt Augmentation
+ *
+ * Builds the skill manifest section that gets appended to agent system prompts.
+ *
+ * @module
+ */
+/**
+ * Build the skill manifest prompt section for an agent's system prompt.
+ *
+ * Lists all available skills with their descriptions and instructions
+ * on how to use the skill tools (load-skill, load-skill-reference, execute-skill-script).
+ *
+ * @param skills - Map of resolved skills for the agent
+ * @returns Prompt section string, or empty string if no skills
+ */
+export function buildSkillManifestPrompt(skills) {
+    if (skills.size === 0)
+        return "";
+    const lines = [
+        "## Available Skills",
+        "",
+        "You have access to skills via tool calling. IMPORTANT: You MUST call the load-skill tool (not write it as text) to activate a skill before performing skill-related tasks.",
+        "",
+    ];
+    for (const [id, skill] of skills) {
+        lines.push(`- **${id}**: ${skill.metadata.description}`);
+    }
+    lines.push("");
+    lines.push("### Skill Tools (call these as tools, never write them as text)");
+    lines.push("");
+    lines.push("- load-skill: Call with { skillId } to load a skill's full instructions and available references/scripts");
+    lines.push("- load-skill-reference: Call with { skillId, reference } to read a reference file from the skill");
+    lines.push("- execute-skill-script: Call with { skillId, script, args?, env?, timeoutMs? } to execute a script");
+    return lines.join("\n");
+}

package/esm/src/skill/registry.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Skill Registry
+ *
+ * Project-scoped registry for discovered skills.
+ * Follows the same pattern as src/tool/registry.ts.
+ *
+ * @module
+ */
+import type { Skill } from "./types.js";
+import { ScopedRegistryFacade } from "../ai/registry-facade.js";
+declare class SkillRegistryClass extends ScopedRegistryFacade<Skill> {
+    /**
+     * Resolve skills for an agent configuration.
+     *
+     * @param skillsConfig - `true` for all skills, or array of specific skill IDs
+     * @returns Map of resolved skills (missing IDs are silently skipped)
+     */
+    resolveForAgent(skillsConfig: true | string[]): Map<string, Skill>;
+}
+export declare const skillRegistry: SkillRegistryClass;
+export declare function registerSkill(id: string, skill: Skill): void;
+export declare function getSkill(id: string): Skill | undefined;
+export declare function getAllSkills(): Map<string, Skill>;
+export {};
+//# sourceMappingURL=registry.d.ts.map

package/esm/src/skill/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/src/skill/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAIhE,cAAM,kBAAmB,SAAQ,oBAAoB,CAAC,KAAK,CAAC;IAC1D;;;;;OAKG;IACH,eAAe,CAAC,YAAY,EAAE,IAAI,GAAG,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC;CAcnE;AAED,eAAO,MAAM,aAAa,oBAAuC,CAAC;AAElE,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAE5D;AAED,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAEtD;AAED,wBAAgB,YAAY,IAAI,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAEjD"}

package/esm/src/skill/registry.js

@@ -0,0 +1,42 @@
+/**
+ * Skill Registry
+ *
+ * Project-scoped registry for discovered skills.
+ * Follows the same pattern as src/tool/registry.ts.
+ *
+ * @module
+ */
+import { ProjectScopedRegistryManager } from "../ai/registry-manager.js";
+import { ScopedRegistryFacade } from "../ai/registry-facade.js";
+const skillManager = new ProjectScopedRegistryManager("skill");
+class SkillRegistryClass extends ScopedRegistryFacade {
+    /**
+     * Resolve skills for an agent configuration.
+     *
+     * @param skillsConfig - `true` for all skills, or array of specific skill IDs
+     * @returns Map of resolved skills (missing IDs are silently skipped)
+     */
+    resolveForAgent(skillsConfig) {
+        if (skillsConfig === true) {
+            return this.getAll();
+        }
+        const result = new Map();
+        for (const id of skillsConfig) {
+            const skill = this.get(id);
+            if (skill) {
+                result.set(id, skill);
+            }
+        }
+        return result;
+    }
+}
+export const skillRegistry = new SkillRegistryClass(skillManager);
+export function registerSkill(id, skill) {
+    skillRegistry.register(id, skill);
+}
+export function getSkill(id) {
+    return skillRegistry.get(id);
+}
+export function getAllSkills() {
+    return skillRegistry.getAll();
+}

package/esm/src/skill/tools.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Skill Tools
+ *
+ * Three tools exposed to agents for interacting with skills:
+ * - load-skill: Load a skill's full instructions
+ * - load-skill-reference: Read a reference file from a skill
+ * - execute-skill-script: Execute a script from a skill
+ *
+ * @module
+ */
+import type { Tool } from "../tool/index.js";
+/**
+ * Create the load-skill tool.
+ * Loads a skill's full instructions, available references, and scripts.
+ */
+export declare function createLoadSkillTool(): Tool;
+/**
+ * Create the load-skill-reference tool.
+ * Reads a reference file from a skill's references/ or assets/ directory.
+ */
+export declare function createLoadSkillReferenceTool(): Tool;
+/**
+ * Create the execute-skill-script tool.
+ * Executes a script from a skill's scripts/ directory.
+ */
+export declare function createExecuteSkillScriptTool(): Tool;
+//# sourceMappingURL=tools.d.ts.map

package/esm/src/skill/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/src/skill/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AA2B7C;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAyD1C;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,IAAI,IAAI,CAkCnD;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,IAAI,IAAI,CAiDnD"}

package/esm/src/skill/tools.js

@@ -0,0 +1,149 @@
+/**
+ * Skill Tools
+ *
+ * Three tools exposed to agents for interacting with skills:
+ * - load-skill: Load a skill's full instructions
+ * - load-skill-reference: Read a reference file from a skill
+ * - execute-skill-script: Execute a script from a skill
+ *
+ * @module
+ */
+import { z } from "zod";
+import { tool } from "../tool/factory.js";
+import { readTextFile } from "../platform/compat/fs.js";
+import { join } from "../platform/compat/path/index.js";
+import { createError, toError } from "../errors/veryfront-error.js";
+import { skillRegistry } from "./registry.js";
+import { parseSkillFrontmatter } from "./parser.js";
+import { listSkillSubdir, validateSkillPath } from "./path-safety.js";
+import { getSkillScriptExecutor } from "./executor.js";
+import { SKILL_ASSETS_DIR, SKILL_MD_FILENAME, SKILL_REFERENCES_DIR, SKILL_SCRIPTS_DIR, } from "./types.js";
+/**
+ * Read a file from a skill directory.
+ * Uses skill.fsAdapter if available (VFS/cloud), otherwise falls back to compat readTextFile.
+ */
+async function readSkillFile(skill, path) {
+    if (skill.fsAdapter) {
+        return await skill.fsAdapter.readFile(path);
+    }
+    return await readTextFile(path);
+}
+/**
+ * Create the load-skill tool.
+ * Loads a skill's full instructions, available references, and scripts.
+ */
+export function createLoadSkillTool() {
+    return tool({
+        id: "load-skill",
+        description: "Load a skill's full instructions. Returns the skill's markdown instructions, " +
+            "allowed tools policy, and lists of available reference files and scripts.",
+        inputSchema: z.object({
+            skillId: z.string().describe("The ID of the skill to load"),
+        }),
+        execute: async (input) => {
+            const skill = skillRegistry.get(input.skillId);
+            if (!skill) {
+                const available = skillRegistry.getAllIds().join(", ");
+                throw toError(createError({
+                    type: "agent",
+                    message: `Skill "${input.skillId}" not found. Available skills: ${available || "none"}`,
+                }));
+            }
+            // Read SKILL.md
+            const skillMdPath = join(skill.rootPath, SKILL_MD_FILENAME);
+            const content = await readSkillFile(skill, skillMdPath);
+            // Parse frontmatter to get instructions
+            const parsed = await parseSkillFrontmatter(content);
+            // List available references and scripts
+            const references = await listSkillSubdir(skill.rootPath, SKILL_REFERENCES_DIR, skill.fsAdapter);
+            const scripts = await listSkillSubdir(skill.rootPath, SKILL_SCRIPTS_DIR, skill.fsAdapter);
+            return {
+                instructions: parsed.body,
+                allowedTools: skill.metadata.allowedTools,
+                references,
+                scripts,
+                ...(scripts.length === 0 && references.length === 0
+                    ? {
+                        note: "This skill has no scripts or reference files. Do NOT call execute-skill-script or load-skill-reference.",
+                    }
+                    : scripts.length === 0
+                        ? { note: "This skill has no scripts. Do NOT call execute-skill-script." }
+                        : references.length === 0
+                            ? { note: "This skill has no reference files. Do NOT call load-skill-reference." }
+                            : {}),
+            };
+        },
+    });
+}
+/**
+ * Create the load-skill-reference tool.
+ * Reads a reference file from a skill's references/ or assets/ directory.
+ */
+export function createLoadSkillReferenceTool() {
+    return tool({
+        id: "load-skill-reference",
+        description: "Read a reference file from a skill. Only files in the skill's " +
+            "references/ and assets/ directories are accessible.",
+        inputSchema: z.object({
+            skillId: z.string().describe("The ID of the skill"),
+            reference: z.string().describe("Relative path to the reference file (e.g. 'references/CLAUSES.md')"),
+        }),
+        execute: async (input) => {
+            const skill = skillRegistry.get(input.skillId);
+            if (!skill) {
+                throw toError(createError({
+                    type: "agent",
+                    message: `Skill "${input.skillId}" not found`,
+                }));
+            }
+            // Validate path safety (only references/ and assets/ allowed)
+            const validatedPath = await validateSkillPath(skill.rootPath, input.reference, [SKILL_REFERENCES_DIR, SKILL_ASSETS_DIR], skill.fsAdapter);
+            const content = await readSkillFile(skill, validatedPath);
+            return { content, path: input.reference };
+        },
+    });
+}
+/**
+ * Create the execute-skill-script tool.
+ * Executes a script from a skill's scripts/ directory.
+ */
+export function createExecuteSkillScriptTool() {
+    return tool({
+        id: "execute-skill-script",
+        description: "Execute a script from a skill's scripts/ directory. Returns stdout, stderr, and exit code.",
+        inputSchema: z.object({
+            skillId: z.string().describe("The ID of the skill"),
+            script: z.string().describe("Relative path to the script (e.g. 'scripts/setup.sh')"),
+            args: z.array(z.string()).optional().describe("Arguments to pass to the script"),
+            env: z.record(z.string()).optional().describe("Environment variables for the script"),
+            timeoutMs: z
+                .number()
+                .int()
+                .positive()
+                .max(300_000)
+                .optional()
+                .describe("Optional execution timeout in milliseconds (max 300000)"),
+        }),
+        execute: async (input) => {
+            const skill = skillRegistry.get(input.skillId);
+            if (!skill) {
+                throw toError(createError({
+                    type: "agent",
+                    message: `Skill "${input.skillId}" not found`,
+                }));
+            }
+            // Validate path safety (only scripts/ allowed)
+            const validatedPath = await validateSkillPath(skill.rootPath, input.script, [SKILL_SCRIPTS_DIR], skill.fsAdapter);
+            const scriptContent = await readSkillFile(skill, validatedPath);
+            const executor = getSkillScriptExecutor();
+            return await executor.execute({
+                scriptPath: validatedPath,
+                scriptContent,
+                args: input.args,
+                env: input.env,
+                cwd: skill.rootPath,
+                timeoutMs: input.timeoutMs,
+            });
+        },
+    });
+}