llmist 16.1.0 → 16.2.0

package/dist/index.cjs

@@ -358,15 +358,15 @@ var init_execution_tree = __esm({
         const parentId = params.parentId ?? this.parentNodeId;
         const parent = parentId ? this.nodes.get(parentId) : null;
         const depth = parent ? parent.depth + 1 : this.baseDepth;
-        const path = parent ? [...parent.path] : [];
+        const path3 = parent ? [...parent.path] : [];
         const id = this.generateLLMCallId(params.iteration, parentId);
-        path.push(id);
+        path3.push(id);
         const node = {
           id,
           type: "llm_call",
           parentId,
           depth,
-          path,
+          path: path3,
           createdAt: Date.now(),
           completedAt: null,
           iteration: params.iteration,
@@ -477,15 +477,15 @@ var init_execution_tree = __esm({
         const parentId = params.parentId ?? this.getCurrentLLMCallId() ?? this.parentNodeId;
         const parent = parentId ? this.nodes.get(parentId) : null;
         const depth = parent ? parent.depth + 1 : this.baseDepth;
-        const path = parent ? [...parent.path] : [];
+        const path3 = parent ? [...parent.path] : [];
         const id = this.generateGadgetId(params.invocationId);
-        path.push(id);
+        path3.push(id);
         const node = {
           id,
           type: "gadget",
           parentId,
           depth,
-          path,
+          path: path3,
           createdAt: Date.now(),
           completedAt: null,
           invocationId: params.invocationId,
@@ -1424,8 +1424,8 @@ ${this.endPrefix}`
         });
         if (media && media.length > 0 && mediaIds && mediaIds.length > 0) {
           const idRefs = media.map((m, i) => {
-            const path = storedMedia?.[i]?.path;
-            const pathInfo = path ? ` \u2192 saved to: ${path}` : "";
+            const path3 = storedMedia?.[i]?.path;
+            const pathInfo = path3 ? ` \u2192 saved to: ${path3}` : "";
             return `[Media: ${mediaIds[i]} (${m.kind})${pathInfo}]`;
           }).join("\n");
           const textWithIds = `Result (${invocationId}): ${result}
@@ -4032,29 +4032,29 @@ function schemaToJSONSchema(schema, options) {
 }
 function detectDescriptionMismatch(schema, jsonSchema) {
   const mismatches = [];
-  function checkSchema(zodSchema, json, path) {
+  function checkSchema(zodSchema, json, path3) {
     if (!zodSchema || typeof zodSchema !== "object") return;
     const def = zodSchema._def;
     const jsonObj = json;
     if (def?.description && !jsonObj?.description) {
-      mismatches.push(path || "root");
+      mismatches.push(path3 || "root");
     }
     if (def?.typeName === "ZodObject" && def?.shape) {
       const shape = typeof def.shape === "function" ? def.shape() : def.shape;
       for (const [key, fieldSchema] of Object.entries(shape)) {
         const properties = jsonObj?.properties;
         const jsonProp = properties?.[key];
-        checkSchema(fieldSchema, jsonProp, path ? `${path}.${key}` : key);
+        checkSchema(fieldSchema, jsonProp, path3 ? `${path3}.${key}` : key);
       }
     }
     if (def?.typeName === "ZodArray" && def?.type) {
-      checkSchema(def.type, jsonObj?.items, path ? `${path}[]` : "[]");
+      checkSchema(def.type, jsonObj?.items, path3 ? `${path3}[]` : "[]");
     }
     if ((def?.typeName === "ZodOptional" || def?.typeName === "ZodNullable") && def?.innerType) {
-      checkSchema(def.innerType, json, path);
+      checkSchema(def.innerType, json, path3);
     }
     if (def?.typeName === "ZodDefault" && def?.innerType) {
-      checkSchema(def.innerType, json, path);
+      checkSchema(def.innerType, json, path3);
     }
   }
   checkSchema(schema, jsonSchema, "");
@@ -4147,7 +4147,7 @@ Example fixes:
     );
   }
 }
-function findUnknownTypes(schema, path = []) {
+function findUnknownTypes(schema, path3 = []) {
   const issues = [];
   if (!schema || typeof schema !== "object") {
     return issues;
@@ -4159,7 +4159,7 @@ function findUnknownTypes(schema, path = []) {
   }
   if (schema.properties) {
     for (const [propName, propSchema] of Object.entries(schema.properties)) {
-      const propPath = [...path, propName];
+      const propPath = [...path3, propName];
       if (hasNoType(propSchema)) {
         issues.push(propPath.join(".") || propName);
       }
@@ -4167,7 +4167,7 @@ function findUnknownTypes(schema, path = []) {
     }
   }
   if (schema.items) {
-    const itemPath = [...path, "[]"];
+    const itemPath = [...path3, "[]"];
     if (hasNoType(schema.items)) {
       issues.push(itemPath.join("."));
     }
@@ -4175,17 +4175,17 @@ function findUnknownTypes(schema, path = []) {
   }
   if (schema.anyOf) {
     schema.anyOf.forEach((subSchema, index) => {
-      issues.push(...findUnknownTypes(subSchema, [...path, `anyOf[${index}]`]));
+      issues.push(...findUnknownTypes(subSchema, [...path3, `anyOf[${index}]`]));
     });
   }
   if (schema.oneOf) {
     schema.oneOf.forEach((subSchema, index) => {
-      issues.push(...findUnknownTypes(subSchema, [...path, `oneOf[${index}]`]));
+      issues.push(...findUnknownTypes(subSchema, [...path3, `oneOf[${index}]`]));
     });
   }
   if (schema.allOf) {
     schema.allOf.forEach((subSchema, index) => {
-      issues.push(...findUnknownTypes(subSchema, [...path, `allOf[${index}]`]));
+      issues.push(...findUnknownTypes(subSchema, [...path3, `allOf[${index}]`]));
     });
   }
   return issues;
@@ -5203,6 +5203,626 @@ var init_registry = __esm({
   }
 });
 
+// src/skills/activation.ts
+function substituteArguments(instructions, args) {
+  if (!args) {
+    return instructions.replace(/\$ARGUMENTS\[\d+\]/g, "").replace(/\$ARGUMENTS/g, "").replace(/\$\d+/g, "");
+  }
+  const parts = splitArguments(args);
+  let result = instructions.replace(/\$ARGUMENTS\[(\d+)\]/g, (_match, index) => {
+    const i = Number.parseInt(index, 10);
+    return parts[i] ?? "";
+  });
+  result = result.replace(/\$ARGUMENTS/g, args);
+  result = result.replace(/\$(\d+)/g, (_match, index) => {
+    const i = Number.parseInt(index, 10);
+    return parts[i] ?? "";
+  });
+  return result;
+}
+function preprocessShellCommands(instructions, options) {
+  const { cwd, shell = "bash", timeoutMs = 1e4 } = options ?? {};
+  return instructions.replace(/!`([^`]+)`/g, (_match, command) => {
+    try {
+      const output = (0, import_node_child_process.execSync)(command, {
+        cwd,
+        shell: shell === "powershell" ? "powershell" : "/bin/bash",
+        timeout: timeoutMs,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"]
+      });
+      return output.trim();
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      return `[Error executing \`${command}\`: ${msg}]`;
+    }
+  });
+}
+function substituteVariables(instructions, variables) {
+  return instructions.replace(/\$\{(\w+)\}/g, (_match, varName) => {
+    return variables[varName] ?? "";
+  });
+}
+function resolveInstructions(instructions, options) {
+  let resolved = instructions;
+  if (options?.variables) {
+    resolved = substituteVariables(resolved, options.variables);
+  }
+  resolved = substituteArguments(resolved, options?.arguments);
+  if (options?.enableShellPreprocessing !== false) {
+    resolved = preprocessShellCommands(resolved, {
+      cwd: options?.cwd,
+      shell: options?.shell,
+      timeoutMs: options?.shellTimeoutMs
+    });
+  }
+  return resolved;
+}
+function splitArguments(args) {
+  const parts = [];
+  let current = "";
+  let inQuote = null;
+  for (const char of args) {
+    if (inQuote) {
+      if (char === inQuote) {
+        inQuote = null;
+      } else {
+        current += char;
+      }
+    } else if (char === '"' || char === "'") {
+      inQuote = char;
+    } else if (char === " " || char === "	") {
+      if (current) {
+        parts.push(current);
+        current = "";
+      }
+    } else {
+      current += char;
+    }
+  }
+  if (current) parts.push(current);
+  return parts;
+}
+var import_node_child_process;
+var init_activation = __esm({
+  "src/skills/activation.ts"() {
+    "use strict";
+    import_node_child_process = require("child_process");
+  }
+});
+
+// src/skills/parser.ts
+function parseFrontmatter(content) {
+  const trimmed = content.trimStart();
+  if (!trimmed.startsWith("---")) {
+    return { frontmatter: {}, body: content };
+  }
+  const endIndex = trimmed.indexOf("\n---", 3);
+  if (endIndex === -1) {
+    return { frontmatter: {}, body: content };
+  }
+  const yamlBlock = trimmed.slice(3, endIndex).trim();
+  const body = trimmed.slice(endIndex + 4).trim();
+  const parsed = import_js_yaml.default.load(yamlBlock);
+  const frontmatter = typeof parsed === "object" && parsed !== null ? parsed : {};
+  return { frontmatter, body };
+}
+function parseMetadata(frontmatter, fallbackName) {
+  const name = parseString(frontmatter.name) ?? fallbackName ?? "unnamed-skill";
+  const description = parseString(frontmatter.description) ?? "";
+  return {
+    name,
+    description,
+    argumentHint: parseString(frontmatter["argument-hint"]),
+    allowedTools: parseStringArray(frontmatter["allowed-tools"]),
+    model: parseString(frontmatter.model),
+    context: parseContext(frontmatter.context),
+    agent: parseString(frontmatter.agent),
+    paths: parseStringArray(frontmatter.paths),
+    gadgets: parseStringArray(frontmatter.gadgets),
+    disableModelInvocation: parseBool(frontmatter["disable-model-invocation"]),
+    userInvocable: parseBool(frontmatter["user-invocable"]),
+    shell: parseShell(frontmatter.shell),
+    version: parseString(frontmatter.version)
+  };
+}
+function scanResources(skillDir) {
+  const resources = [];
+  for (const category of RESOURCE_CATEGORIES) {
+    const categoryDir = import_node_path3.default.join(skillDir, category);
+    if (!import_node_fs2.default.existsSync(categoryDir)) continue;
+    const stat = import_node_fs2.default.statSync(categoryDir);
+    if (!stat.isDirectory()) continue;
+    for (const file of walkDirectory(categoryDir)) {
+      resources.push({
+        relativePath: import_node_path3.default.relative(skillDir, file),
+        absolutePath: file,
+        category
+      });
+    }
+  }
+  return resources;
+}
+function parseSkillFile(skillMdPath, source, loadInstructions = false) {
+  const content = import_node_fs2.default.readFileSync(skillMdPath, "utf-8");
+  return parseSkillContent(content, skillMdPath, source, loadInstructions);
+}
+function parseSkillContent(content, sourcePath, source, loadInstructions = false) {
+  const sourceDir = import_node_path3.default.dirname(sourcePath);
+  const fallbackName = import_node_path3.default.basename(sourceDir);
+  const { frontmatter, body } = parseFrontmatter(content);
+  const metadata = parseMetadata(frontmatter, fallbackName);
+  const resources = import_node_fs2.default.existsSync(sourceDir) ? scanResources(sourceDir) : [];
+  return {
+    metadata,
+    instructions: loadInstructions ? body : null,
+    resources,
+    sourcePath,
+    sourceDir,
+    source
+  };
+}
+function validateMetadata(metadata) {
+  const issues = [];
+  if (!metadata.name) {
+    issues.push("Skill name is required");
+  } else {
+    if (metadata.name.length > MAX_NAME_LENGTH) {
+      issues.push(`Skill name exceeds ${MAX_NAME_LENGTH} characters`);
+    }
+    if (!NAME_PATTERN.test(metadata.name)) {
+      issues.push(
+        "Skill name must contain only lowercase letters, numbers, and hyphens, and must start with a letter or number"
+      );
+    }
+  }
+  if (!metadata.description) {
+    issues.push("Skill description is required");
+  } else if (metadata.description.length > MAX_DESCRIPTION_LENGTH) {
+    issues.push(`Skill description exceeds ${MAX_DESCRIPTION_LENGTH} characters`);
+  }
+  if (metadata.context && metadata.context !== "fork" && metadata.context !== "inline") {
+    issues.push('Skill context must be "fork" or "inline"');
+  }
+  return issues;
+}
+function parseString(value) {
+  if (value == null) return void 0;
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  return void 0;
+}
+function parseStringArray(value) {
+  if (value == null) return void 0;
+  if (Array.isArray(value)) {
+    return value.filter((v) => typeof v === "string" || typeof v === "number").map(String);
+  }
+  if (typeof value === "string") return [value];
+  return void 0;
+}
+function parseContext(value) {
+  if (value === "fork" || value === "inline") return value;
+  return void 0;
+}
+function parseShell(value) {
+  if (value === "bash" || value === "powershell") return value;
+  return void 0;
+}
+function parseBool(value) {
+  if (value === true || value === false) return value;
+  if (value === "true") return true;
+  if (value === "false") return false;
+  return void 0;
+}
+function* walkDirectory(dir) {
+  const entries = import_node_fs2.default.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = import_node_path3.default.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield* walkDirectory(fullPath);
+    } else if (entry.isFile()) {
+      yield fullPath;
+    }
+  }
+}
+var import_node_fs2, import_node_path3, import_js_yaml, RESOURCE_CATEGORIES, MAX_NAME_LENGTH, MAX_DESCRIPTION_LENGTH, NAME_PATTERN;
+var init_parser = __esm({
+  "src/skills/parser.ts"() {
+    "use strict";
+    import_node_fs2 = __toESM(require("fs"), 1);
+    import_node_path3 = __toESM(require("path"), 1);
+    import_js_yaml = __toESM(require("js-yaml"), 1);
+    RESOURCE_CATEGORIES = ["scripts", "references", "assets"];
+    MAX_NAME_LENGTH = 64;
+    MAX_DESCRIPTION_LENGTH = 1024;
+    NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+  }
+});
+
+// src/skills/registry.ts
+var registry_exports = {};
+__export(registry_exports, {
+  SkillRegistry: () => SkillRegistry
+});
+var import_minimatch, DEFAULT_CHAR_BUDGET, SUMMARY_DESCRIPTION_LIMIT, SkillRegistry;
+var init_registry2 = __esm({
+  "src/skills/registry.ts"() {
+    "use strict";
+    import_minimatch = require("minimatch");
+    DEFAULT_CHAR_BUDGET = 8e3;
+    SUMMARY_DESCRIPTION_LIMIT = 250;
+    SkillRegistry = class _SkillRegistry {
+      skills = /* @__PURE__ */ new Map();
+      /**
+       * Register a skill. Overwrites any existing skill with the same name.
+       *
+       * Unlike GadgetRegistry (which throws on duplicates), SkillRegistry allows
+       * overwriting because skills are loaded from multiple sources with intentional
+       * priority ordering (project > user > default).
+       */
+      register(skill) {
+        this.skills.set(skill.name.toLowerCase(), skill);
+      }
+      /** Register multiple skills. */
+      registerMany(skills) {
+        for (const skill of skills) {
+          this.register(skill);
+        }
+      }
+      /** Remove a skill by name (case-insensitive). Returns true if removed. */
+      remove(name) {
+        return this.skills.delete(name.toLowerCase());
+      }
+      /** Remove all registered skills. */
+      clear() {
+        this.skills.clear();
+      }
+      /** Get a skill by name (case-insensitive). */
+      get(name) {
+        return this.skills.get(name.toLowerCase());
+      }
+      /** Check if a skill exists by name (case-insensitive). */
+      has(name) {
+        return this.skills.has(name.toLowerCase());
+      }
+      /** Get all registered skills. */
+      getAll() {
+        return [...this.skills.values()];
+      }
+      /** Get all skill names. */
+      getNames() {
+        return [...this.skills.keys()];
+      }
+      /** Number of registered skills. */
+      get size() {
+        return this.skills.size;
+      }
+      /**
+       * Get skills that are visible to the LLM for auto-triggering.
+       * Excludes skills with disableModelInvocation: true.
+       */
+      getModelInvocable() {
+        return this.getAll().filter((s) => s.isModelInvocable);
+      }
+      /**
+       * Get skills that the user can invoke via /skill-name.
+       * Excludes skills with userInvocable: false.
+       */
+      getUserInvocable() {
+        return this.getAll().filter((s) => s.isUserInvocable);
+      }
+      /**
+       * Generate metadata summaries for system prompt injection (Tier 1).
+       *
+       * Each skill contributes a one-line summary: "name — description".
+       * Output is truncated to fit the character budget.
+       *
+       * @param charBudget - Maximum characters for all summaries combined.
+       */
+      getMetadataSummaries(charBudget = DEFAULT_CHAR_BUDGET) {
+        const invocable = this.getModelInvocable();
+        if (invocable.length === 0) return "";
+        const lines = [];
+        let totalChars = 0;
+        for (const skill of invocable) {
+          const desc = skill.description.length > SUMMARY_DESCRIPTION_LIMIT ? `${skill.description.slice(0, SUMMARY_DESCRIPTION_LIMIT - 3)}...` : skill.description;
+          const line = `- ${skill.name}: ${desc}`;
+          if (totalChars + line.length > charBudget) break;
+          lines.push(line);
+          totalChars += line.length + 1;
+        }
+        return lines.join("\n");
+      }
+      /**
+       * Find skills whose `paths` patterns match a given file path.
+       * Used for auto-activation when the user is working on specific files.
+       */
+      findByFilePath(filePath) {
+        return this.getModelInvocable().filter((skill) => {
+          const patterns = skill.metadata.paths;
+          if (!patterns || patterns.length === 0) return false;
+          return patterns.some((pattern) => (0, import_minimatch.minimatch)(filePath, pattern));
+        });
+      }
+      /**
+       * Merge another registry into this one.
+       * Skills from the other registry overwrite existing skills with the same name.
+       */
+      merge(other) {
+        for (const skill of other.getAll()) {
+          this.register(skill);
+        }
+      }
+      /** Create a registry from an array of skills. */
+      static from(skills) {
+        const registry = new _SkillRegistry();
+        registry.registerMany(skills);
+        return registry;
+      }
+    };
+  }
+});
+
+// src/skills/skill.ts
+var import_promises2, Skill;
+var init_skill = __esm({
+  "src/skills/skill.ts"() {
+    "use strict";
+    import_promises2 = __toESM(require("fs/promises"), 1);
+    init_activation();
+    init_parser();
+    Skill = class _Skill {
+      metadata;
+      sourcePath;
+      sourceDir;
+      source;
+      _instructions;
+      _resources;
+      _resourceCache = /* @__PURE__ */ new Map();
+      _resourceLoading = /* @__PURE__ */ new Map();
+      constructor(parsed) {
+        this.metadata = parsed.metadata;
+        this.sourcePath = parsed.sourcePath;
+        this.sourceDir = parsed.sourceDir;
+        this.source = parsed.source;
+        this._instructions = parsed.instructions;
+        this._resources = parsed.resources;
+      }
+      /** Skill name for registry lookup. */
+      get name() {
+        return this.metadata.name;
+      }
+      /** Skill description for LLM matching. */
+      get description() {
+        return this.metadata.description;
+      }
+      /** Whether the LLM can auto-trigger this skill. */
+      get isModelInvocable() {
+        return this.metadata.disableModelInvocation !== true;
+      }
+      /** Whether the user can invoke this skill via /skill-name. */
+      get isUserInvocable() {
+        return this.metadata.userInvocable !== false;
+      }
+      /**
+       * Load and cache Tier 2 instructions.
+       * If instructions were loaded during parsing, returns the cached value.
+       */
+      async getInstructions() {
+        if (this._instructions !== null) return this._instructions;
+        const content = await import_promises2.default.readFile(this.sourcePath, "utf-8");
+        const { body } = parseFrontmatter(content);
+        this._instructions = body;
+        return body;
+      }
+      /**
+       * List Tier 3 resources.
+       * Resources are discovered at parse time but content is loaded on demand.
+       */
+      getResources() {
+        return this._resources;
+      }
+      /**
+       * Load a specific Tier 3 resource by relative path.
+       * Results are cached for the lifetime of this Skill instance.
+       * Concurrent calls for the same resource share a single read.
+       */
+      async getResource(relativePath) {
+        if (relativePath.includes("..")) {
+          throw new Error(`Invalid resource path (path traversal): ${relativePath}`);
+        }
+        const cached = this._resourceCache.get(relativePath);
+        if (cached !== void 0) return cached;
+        const existing = this._resourceLoading.get(relativePath);
+        if (existing) return existing;
+        const resource = this._resources.find((r) => r.relativePath === relativePath);
+        if (!resource) {
+          throw new Error(`Resource not found: ${relativePath} in skill ${this.name}`);
+        }
+        const loadPromise = import_promises2.default.readFile(resource.absolutePath, "utf-8").then(
+          (content) => {
+            this._resourceCache.set(relativePath, content);
+            this._resourceLoading.delete(relativePath);
+            return content;
+          },
+          (error) => {
+            this._resourceLoading.delete(relativePath);
+            throw new Error(
+              `Failed to load resource ${relativePath} in skill ${this.name}: ${error instanceof Error ? error.message : String(error)}`
+            );
+          }
+        );
+        this._resourceLoading.set(relativePath, loadPromise);
+        return loadPromise;
+      }
+      /**
+       * Activate this skill with optional arguments.
+       *
+       * Performs:
+       * 1. Variable substitution (${SKILL_DIR}, etc.)
+       * 2. Argument substitution ($ARGUMENTS, $0, $1)
+       * 3. Shell preprocessing (!`command`)
+       * 4. Resource loading (if eagerResources is true)
+       */
+      async activate(options) {
+        const instructions = await this.getInstructions();
+        const resolvedInstructions = resolveInstructions(instructions, {
+          arguments: options?.arguments,
+          variables: {
+            SKILL_DIR: this.sourceDir,
+            CLAUDE_SKILL_DIR: this.sourceDir
+          },
+          cwd: options?.cwd ?? this.sourceDir,
+          shell: this.metadata.shell,
+          enableShellPreprocessing: options?.enableShellPreprocessing,
+          shellTimeoutMs: options?.shellTimeoutMs
+        });
+        const loadedResources = /* @__PURE__ */ new Map();
+        if (options?.eagerResources) {
+          for (const resource of this._resources) {
+            const content = await this.getResource(resource.relativePath);
+            loadedResources.set(resource.relativePath, content);
+          }
+        }
+        return {
+          skillName: this.name,
+          resolvedInstructions,
+          gadgets: [],
+          // Gadgets are resolved by the CLI layer
+          loadedResources
+        };
+      }
+      /**
+       * Create a Skill from a SKILL.md content string.
+       * Useful for testing or dynamic skill creation.
+       */
+      static fromContent(content, sourcePath, source = { type: "directory", path: sourcePath }) {
+        const parsed = parseSkillContent(content, sourcePath, source, true);
+        return new _Skill(parsed);
+      }
+    };
+  }
+});
+
+// src/skills/loader.ts
+function loadSkillsFromDirectory(dir, source, onWarning) {
+  if (!import_node_fs3.default.existsSync(dir)) return [];
+  const stat = import_node_fs3.default.statSync(dir);
+  if (!stat.isDirectory()) return [];
+  const skills = [];
+  scanForSkills(dir, source, skills, onWarning);
+  return skills;
+}
+function discoverSkills(options) {
+  const registry = new SkillRegistry();
+  const userSkillsDir = options?.userDir ?? import_node_path4.default.join(import_node_os2.default.homedir(), CONFIG_DIR_NAME, SKILLS_DIR_NAME);
+  const userSkills = loadSkillsFromDirectory(userSkillsDir, {
+    type: "user",
+    path: userSkillsDir
+  });
+  registry.registerMany(userSkills);
+  if (options?.projectDir) {
+    const projectSkillsDir = import_node_path4.default.join(options.projectDir, CONFIG_DIR_NAME, SKILLS_DIR_NAME);
+    const projectSkills = loadSkillsFromDirectory(projectSkillsDir, {
+      type: "project",
+      path: projectSkillsDir
+    });
+    registry.registerMany(projectSkills);
+  }
+  if (options?.additionalDirs) {
+    for (const dir of options.additionalDirs) {
+      const resolvedDir = dir.startsWith("~") ? import_node_path4.default.join(import_node_os2.default.homedir(), dir.slice(1)) : dir;
+      const skills = loadSkillsFromDirectory(resolvedDir, {
+        type: "directory",
+        path: resolvedDir
+      });
+      registry.registerMany(skills);
+    }
+  }
+  return registry;
+}
+function scanForSkills(dir, source, results, onWarning) {
+  let entries;
+  try {
+    entries = import_node_fs3.default.readdirSync(dir, { withFileTypes: true });
+  } catch (error) {
+    onWarning?.(
+      `Cannot read skill directory ${dir}: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return;
+  }
+  const skillMdPath = import_node_path4.default.join(dir, "SKILL.md");
+  if (import_node_fs3.default.existsSync(skillMdPath)) {
+    try {
+      const parsed = parseSkillFile(skillMdPath, source, false);
+      results.push(new Skill(parsed));
+    } catch (error) {
+      onWarning?.(
+        `Failed to parse ${skillMdPath}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory() && !entry.name.startsWith(".")) {
+      scanForSkills(import_node_path4.default.join(dir, entry.name), source, results, onWarning);
+    }
+  }
+}
+var import_node_fs3, import_node_os2, import_node_path4, SKILLS_DIR_NAME, CONFIG_DIR_NAME;
+var init_loader = __esm({
+  "src/skills/loader.ts"() {
+    "use strict";
+    import_node_fs3 = __toESM(require("fs"), 1);
+    import_node_os2 = __toESM(require("os"), 1);
+    import_node_path4 = __toESM(require("path"), 1);
+    init_parser();
+    init_registry2();
+    init_skill();
+    SKILLS_DIR_NAME = "skills";
+    CONFIG_DIR_NAME = ".llmist";
+  }
+});
+
+// src/skills/use-skill-gadget.ts
+function createUseSkillGadget(registry) {
+  const summaries = registry.getMetadataSummaries();
+  const skillNames = registry.getModelInvocable().map((s) => s.name);
+  const description = [
+    "Activate a skill to get specialized instructions for a task.",
+    "Available skills:",
+    summaries
+  ].join("\n");
+  return createGadget({
+    name: USE_SKILL_GADGET_NAME,
+    description,
+    schema: import_zod2.z.object({
+      skill: import_zod2.z.enum(skillNames).describe("Name of the skill to activate"),
+      arguments: import_zod2.z.string().optional().describe("Arguments for the skill (e.g., a filename, issue number, or search query)")
+    }),
+    execute: async ({ skill: skillName, arguments: args }) => {
+      const skill = registry.get(skillName);
+      if (!skill) {
+        return `Unknown skill: "${skillName}". Available skills: ${skillNames.join(", ")}`;
+      }
+      const activation = await skill.activate({
+        arguments: args,
+        cwd: process.cwd()
+      });
+      return activation.resolvedInstructions;
+    }
+  });
+}
+var import_zod2, USE_SKILL_GADGET_NAME;
+var init_use_skill_gadget = __esm({
+  "src/skills/use-skill-gadget.ts"() {
+    "use strict";
+    import_zod2 = require("zod");
+    init_create_gadget();
+    USE_SKILL_GADGET_NAME = "UseSkill";
+  }
+});
+
 // src/agent/builder-utils.ts
 function formatGadgetCall(gadgetName, invocationId, parameters, prefixes) {
   const startPrefix = prefixes?.start ?? GADGET_START_PREFIX;
@@ -5336,7 +5956,7 @@ function resolveLoggingDirectory(state, baseDirectory, counterPadding, subagentC
   if (!fullPath) {
     const chronoNumber = getNextCounter(state, parentDir);
     const subdirName = `${formatCallNumber(chronoNumber, counterPadding)}-${parentGadgetInvocationId}`;
-    fullPath = (0, import_node_path3.join)(parentDir, subdirName);
+    fullPath = (0, import_node_path5.join)(parentDir, subdirName);
     state.subagentDirectories.set(subagentKey, fullPath);
   }
   state.activeDirectoryByContext.set(contextKey, fullPath);
@@ -5355,8 +5975,8 @@ function formatCallNumber(n, padding = 4) {
   return n.toString().padStart(padding, "0");
 }
 async function writeLogFile(dir, filename, content) {
-  await (0, import_promises2.mkdir)(dir, { recursive: true });
-  await (0, import_promises2.writeFile)((0, import_node_path3.join)(dir, filename), content, "utf-8");
+  await (0, import_promises3.mkdir)(dir, { recursive: true });
+  await (0, import_promises3.writeFile)((0, import_node_path5.join)(dir, filename), content, "utf-8");
 }
 function createFileLoggingHooks(options, state = getDefaultState()) {
   const {
@@ -5366,7 +5986,7 @@ function createFileLoggingHooks(options, state = getDefaultState()) {
     formatRequest = formatLlmRequest,
     onFileWritten
   } = options;
-  const baseDirectory = (0, import_node_path3.resolve)(options.directory);
+  const baseDirectory = (0, import_node_path5.resolve)(options.directory);
   if (!state.counters.has(baseDirectory)) {
     state.counters.set(baseDirectory, startingCounter - 1);
   }
@@ -5394,7 +6014,7 @@ function createFileLoggingHooks(options, state = getDefaultState()) {
           await writeLogFile(currentDirectory, filename, content);
           if (onFileWritten) {
             onFileWritten({
-              filePath: (0, import_node_path3.join)(currentDirectory, filename),
+              filePath: (0, import_node_path5.join)(currentDirectory, filename),
               type: "request",
               callNumber: currentCallNumber,
               contentLength: content.length,
@@ -5423,7 +6043,7 @@ function createFileLoggingHooks(options, state = getDefaultState()) {
           await writeLogFile(currentDirectory, filename, content);
           if (onFileWritten) {
             onFileWritten({
-              filePath: (0, import_node_path3.join)(currentDirectory, filename),
+              filePath: (0, import_node_path5.join)(currentDirectory, filename),
               type: "response",
               callNumber: currentCallNumber,
               contentLength: content.length,
@@ -5445,12 +6065,12 @@ function getEnvFileLoggingHooks() {
   }
   return createFileLoggingHooks({ directory });
 }
-var import_promises2, import_node_path3, defaultState, ENV_LOG_RAW_DIRECTORY;
+var import_promises3, import_node_path5, defaultState, ENV_LOG_RAW_DIRECTORY;
 var init_file_logging = __esm({
   "src/agent/file-logging.ts"() {
     "use strict";
-    import_promises2 = require("fs/promises");
-    import_node_path3 = require("path");
+    import_promises3 = require("fs/promises");
+    import_node_path5 = require("path");
     init_messages();
     ENV_LOG_RAW_DIRECTORY = "LLMIST_LOG_RAW_DIRECTORY";
   }
@@ -12207,6 +12827,10 @@ var init_builder = __esm({
     "use strict";
     init_model_shortcuts();
     init_registry();
+    init_activation();
+    init_loader();
+    init_parser();
+    init_use_skill_gadget();
     init_agent();
     init_agent_internal_key();
     init_builder_utils();
@@ -12218,12 +12842,14 @@ var init_builder = __esm({
       retry;
       subagents;
       policies;
+      skills;
       constructor(client) {
         this.core = { client, initialMessages: [] };
         this.gadgets = { gadgets: [] };
         this.retry = {};
         this.subagents = {};
         this.policies = {};
+        this.skills = { preActivated: [], skillDirs: [] };
       }
       /** Set the model to use. Supports aliases like "sonnet", "flash". */
       withModel(model) {
@@ -12360,6 +12986,38 @@ var init_builder = __esm({
         this.policies.compactionConfig = { enabled: false };
         return this;
       }
+      // ─── Skills ──────────────────────────────────────────────────────────────────
+      /** Register a skill registry for this agent. */
+      withSkills(registry) {
+        this.skills.registry = registry;
+        return this;
+      }
+      /**
+       * Pre-activate a specific skill before the agent starts.
+       * Instructions are injected into the system prompt.
+       *
+       * Note: each call replaces (not appends) the pre-activated skill for that name.
+       * This is safe for REPL loops where the same builder is reused.
+       */
+      withSkill(name, args) {
+        const existing = this.skills.preActivated.findIndex((s) => s.name === name);
+        if (existing !== -1) {
+          this.skills.preActivated[existing] = { name, args };
+        } else {
+          this.skills.preActivated.push({ name, args });
+        }
+        return this;
+      }
+      /** Clear all pre-activated skills. Call between REPL iterations. */
+      clearPreActivatedSkills() {
+        this.skills.preActivated = [];
+        return this;
+      }
+      /** Add a directory to scan for skills. */
+      withSkillsFrom(dir) {
+        this.skills.skillDirs.push(dir);
+        return this;
+      }
       /** Configure retry behavior for LLM API calls. */
       withRetry(config) {
         this.retry.retryConfig = { ...config, enabled: config.enabled ?? true };
@@ -12451,16 +13109,75 @@ var init_builder = __esm({
       composeHooks() {
         return HookComposer.compose(this.core.hooks, this.core.trailingMessage);
       }
+      resolveSkillRegistry() {
+        if (this.skills.registry) {
+          if (this.skills.skillDirs.length > 0) {
+            for (const dir of this.skills.skillDirs) {
+              const skills = loadSkillsFromDirectory(dir, { type: "directory", path: dir });
+              this.skills.registry.registerMany(skills);
+            }
+          }
+          return this.skills.registry;
+        }
+        if (this.skills.skillDirs.length > 0) {
+          const { SkillRegistry: SR } = (init_registry2(), __toCommonJS(registry_exports));
+          const reg = new SR();
+          for (const dir of this.skills.skillDirs) {
+            const skills = loadSkillsFromDirectory(dir, { type: "directory", path: dir });
+            reg.registerMany(skills);
+          }
+          return reg;
+        }
+        return void 0;
+      }
+      /**
+       * Resolve pre-activated skill instructions synchronously.
+       * Reads SKILL.md from disk via readFileSync (skills are local files).
+       */
+      resolvePreActivatedInstructions(skillRegistry) {
+        if (this.skills.preActivated.length === 0) return void 0;
+        const fs4 = require("fs");
+        const blocks = [];
+        for (const { name, args } of this.skills.preActivated) {
+          const skill = skillRegistry.get(name);
+          if (!skill) continue;
+          const content = fs4.readFileSync(skill.sourcePath, "utf-8");
+          const { body } = parseFrontmatter(content);
+          const resolved = resolveInstructions(body, {
+            arguments: args,
+            variables: { SKILL_DIR: skill.sourceDir, CLAUDE_SKILL_DIR: skill.sourceDir },
+            cwd: skill.sourceDir,
+            shell: skill.metadata.shell
+          });
+          blocks.push(`## Skill: ${name}
+
+${resolved}`);
+        }
+        return blocks.length > 0 ? blocks.join("\n\n---\n\n") : void 0;
+      }
       buildAgentOptions(userPrompt) {
         if (!this.core.client) {
           const { LLMist: LLMistClass } = (init_client(), __toCommonJS(client_exports));
           this.core.client = new LLMistClass();
         }
         const registry = GadgetRegistry.from(this.gadgets.gadgets);
+        let systemPrompt = this.core.systemPrompt;
+        const skillRegistry = this.resolveSkillRegistry();
+        if (skillRegistry && skillRegistry.size > 0) {
+          if (skillRegistry.getModelInvocable().length > 0) {
+            registry.registerByClass(createUseSkillGadget(skillRegistry));
+          }
+          const preActivatedBlock = this.resolvePreActivatedInstructions(skillRegistry);
+          if (preActivatedBlock) {
+            systemPrompt = systemPrompt ? `${systemPrompt}
+
+${preActivatedBlock}` : preActivatedBlock;
+          }
+        }
         return {
           client: this.core.client,
           model: this.core.model ?? "openai:gpt-5-nano",
-          systemPrompt: this.core.systemPrompt,
+          systemPrompt,
           userPrompt,
           registry,
           maxIterations: this.core.maxIterations,
@@ -13145,8 +13862,8 @@ var init_error_formatter = __esm({
         const parts = [];
         parts.push(`Error: Invalid parameters for '${gadgetName}':`);
         for (const issue of zodError.issues) {
-          const path = issue.path.join(".") || "root";
-          parts.push(`  - ${path}: ${issue.message}`);
+          const path3 = issue.path.join(".") || "root";
+          parts.push(`  - ${path3}: ${issue.message}`);
         }
         parts.push("");
         parts.push("Gadget Usage:");
@@ -13211,7 +13928,7 @@ function stripMarkdownFences(content) {
   return cleaned.trim();
 }
 var globalInvocationCounter, GadgetCallParser;
-var init_parser = __esm({
+var init_parser2 = __esm({
   "src/gadgets/parser.ts"() {
     "use strict";
     init_constants();
@@ -13423,15 +14140,15 @@ function getHostExportsInternal() {
     createGadget,
     ExecutionTree,
     LLMist,
-    z: import_zod2.z
+    z: import_zod3.z
   };
 }
-var import_fast_deep_equal, import_zod2, GadgetExecutor;
+var import_fast_deep_equal, import_zod3, GadgetExecutor;
 var init_executor = __esm({
   "src/gadgets/executor.ts"() {
     "use strict";
     import_fast_deep_equal = __toESM(require("fast-deep-equal"), 1);
-    import_zod2 = require("zod");
+    import_zod3 = require("zod");
     init_builder();
     init_hook_utils();
     init_client();
@@ -13443,7 +14160,7 @@ var init_executor = __esm({
     init_create_gadget();
     init_error_formatter();
     init_exceptions();
-    init_parser();
+    init_parser2();
     init_typed_gadget();
     GadgetExecutor = class {
       registry;
@@ -15044,7 +15761,7 @@ var init_stream_processor = __esm({
   "src/agent/stream-processor.ts"() {
     "use strict";
     init_executor();
-    init_parser();
+    init_parser2();
     init_logger();
     init_gadget_concurrency_manager();
     init_gadget_dependency_resolver();
@@ -16206,11 +16923,14 @@ __export(index_exports, {
   OpenRouterProvider: () => OpenRouterProvider,
   RateLimitTracker: () => RateLimitTracker,
   SimpleSessionManager: () => SimpleSessionManager,
+  Skill: () => Skill,
+  SkillRegistry: () => SkillRegistry,
   SlidingWindowStrategy: () => SlidingWindowStrategy,
   StreamProcessor: () => StreamProcessor,
   SummarizationStrategy: () => SummarizationStrategy,
   TaskCompletionSignal: () => TaskCompletionSignal,
   TimeoutException: () => TimeoutException,
+  USE_SKILL_GADGET_NAME: () => USE_SKILL_GADGET_NAME,
   audioFromBase64: () => audioFromBase64,
   audioFromBuffer: () => audioFromBuffer,
   collectEvents: () => collectEvents,
@@ -16228,10 +16948,12 @@ __export(index_exports, {
   createOpenAIProviderFromEnv: () => createOpenAIProviderFromEnv,
   createOpenRouterProviderFromEnv: () => createOpenRouterProviderFromEnv,
   createSubagent: () => createSubagent,
+  createUseSkillGadget: () => createUseSkillGadget,
   defaultLogger: () => defaultLogger,
   detectAudioMimeType: () => detectAudioMimeType,
   detectImageMimeType: () => detectImageMimeType,
   discoverProviderAdapters: () => discoverProviderAdapters,
+  discoverSkills: () => discoverSkills,
   extractMessageText: () => extractMessageText,
   extractRetryAfterMs: () => extractRetryAfterMs,
   filterByDepth: () => filterByDepth,
@@ -16274,15 +16996,21 @@ __export(index_exports, {
   iterationProgressHint: () => iterationProgressHint,
   listPresets: () => listPresets,
   listSubagents: () => listSubagents,
+  loadSkillsFromDirectory: () => loadSkillsFromDirectory,
   normalizeMessageContent: () => normalizeMessageContent,
   parallelGadgetHint: () => parallelGadgetHint,
   parseDataUrl: () => parseDataUrl,
+  parseFrontmatter: () => parseFrontmatter,
   parseManifest: () => parseManifest,
+  parseMetadata: () => parseMetadata,
   parseRetryAfterHeader: () => parseRetryAfterHeader,
+  parseSkillContent: () => parseSkillContent,
+  parseSkillFile: () => parseSkillFile,
   randomDelay: () => randomDelay,
   resetFileLoggingState: () => resetFileLoggingState,
   resolveConfig: () => resolveConfig,
   resolveHintTemplate: () => resolveHintTemplate,
+  resolveInstructions: () => resolveInstructions,
   resolveModel: () => resolveModel,
   resolvePromptTemplate: () => resolvePromptTemplate,
   resolveRateLimitConfig: () => resolveRateLimitConfig,
@@ -16297,9 +17025,12 @@ __export(index_exports, {
   resultWithImages: () => resultWithImages,
   resultWithMedia: () => resultWithMedia,
   runWithHandlers: () => runWithHandlers,
+  scanResources: () => scanResources,
   schemaToJSONSchema: () => schemaToJSONSchema,
   stream: () => stream,
   stripProviderPrefix: () => stripProviderPrefix,
+  substituteArguments: () => substituteArguments,
+  substituteVariables: () => substituteVariables,
   text: () => text,
   timing: () => timing,
   toBase64: () => toBase64,
@@ -16307,13 +17038,14 @@ __export(index_exports, {
   validateAndApplyDefaults: () => validateAndApplyDefaults,
   validateGadgetParams: () => validateGadgetParams,
   validateGadgetSchema: () => validateGadgetSchema,
+  validateMetadata: () => validateMetadata,
   withErrorHandling: () => withErrorHandling,
   withRetry: () => withRetry,
   withTimeout: () => withTimeout,
-  z: () => import_zod3.z
+  z: () => import_zod4.z
 });
 module.exports = __toCommonJS(index_exports);
-var import_zod3 = require("zod");
+var import_zod4 = require("zod");
 init_agent();
 init_builder();
 init_event_handlers();
@@ -16627,7 +17359,7 @@ function resultWithFile(result, fileData, mimeType, options) {
 
 // src/index.ts
 init_output_viewer();
-init_parser();
+init_parser2();
 init_registry();
 init_typed_gadget();
 init_constants2();
@@ -16894,6 +17626,14 @@ var SimpleSessionManager = class extends BaseSessionManager {
   }
 };
 
+// src/skills/index.ts
+init_activation();
+init_loader();
+init_parser();
+init_registry2();
+init_skill();
+init_use_skill_gadget();
+
 // src/utils/format.ts
 function truncate(text3, maxLength, suffix = "...") {
   if (text3.length <= maxLength) return text3;
@@ -17090,11 +17830,14 @@ function getHostExports2(ctx) {
   OpenRouterProvider,
   RateLimitTracker,
   SimpleSessionManager,
+  Skill,
+  SkillRegistry,
   SlidingWindowStrategy,
   StreamProcessor,
   SummarizationStrategy,
   TaskCompletionSignal,
   TimeoutException,
+  USE_SKILL_GADGET_NAME,
   audioFromBase64,
   audioFromBuffer,
   collectEvents,
@@ -17112,10 +17855,12 @@ function getHostExports2(ctx) {
   createOpenAIProviderFromEnv,
   createOpenRouterProviderFromEnv,
   createSubagent,
+  createUseSkillGadget,
   defaultLogger,
   detectAudioMimeType,
   detectImageMimeType,
   discoverProviderAdapters,
+  discoverSkills,
   extractMessageText,
   extractRetryAfterMs,
   filterByDepth,
@@ -17158,15 +17903,21 @@ function getHostExports2(ctx) {
   iterationProgressHint,
   listPresets,
   listSubagents,
+  loadSkillsFromDirectory,
   normalizeMessageContent,
   parallelGadgetHint,
   parseDataUrl,
+  parseFrontmatter,
   parseManifest,
+  parseMetadata,
   parseRetryAfterHeader,
+  parseSkillContent,
+  parseSkillFile,
   randomDelay,
   resetFileLoggingState,
   resolveConfig,
   resolveHintTemplate,
+  resolveInstructions,
   resolveModel,
   resolvePromptTemplate,
   resolveRateLimitConfig,
@@ -17181,9 +17932,12 @@ function getHostExports2(ctx) {
   resultWithImages,
   resultWithMedia,
   runWithHandlers,
+  scanResources,
   schemaToJSONSchema,
   stream,
   stripProviderPrefix,
+  substituteArguments,
+  substituteVariables,
   text,
   timing,
   toBase64,
@@ -17191,6 +17945,7 @@ function getHostExports2(ctx) {
   validateAndApplyDefaults,
   validateGadgetParams,
   validateGadgetSchema,
+  validateMetadata,
   withErrorHandling,
   withRetry,
   withTimeout,