llmist 16.1.0 → 16.2.1

package/dist/index.js

@@ -2,6 +2,12 @@ var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
 var __esm = (fn, res) => function __init() {
   return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
 };
@@ -347,15 +353,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,
@@ -466,15 +472,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,
@@ -1413,8 +1419,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}
@@ -4022,29 +4028,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, "");
@@ -4136,7 +4142,7 @@ Example fixes:
     );
   }
 }
-function findUnknownTypes(schema, path = []) {
+function findUnknownTypes(schema, path3 = []) {
   const issues = [];
   if (!schema || typeof schema !== "object") {
     return issues;
@@ -4148,7 +4154,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);
       }
@@ -4156,7 +4162,7 @@ function findUnknownTypes(schema, path = []) {
     }
   }
   if (schema.items) {
-    const itemPath = [...path, "[]"];
+    const itemPath = [...path3, "[]"];
     if (hasNoType(schema.items)) {
       issues.push(itemPath.join("."));
     }
@@ -4164,17 +4170,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;
@@ -5190,6 +5196,625 @@ var init_registry = __esm({
   }
 });
 
+// src/skills/activation.ts
+import { execSync } from "child_process";
+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 = 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 init_activation = __esm({
+  "src/skills/activation.ts"() {
+    "use strict";
+  }
+});
+
+// src/skills/parser.ts
+import fs from "fs";
+import path from "path";
+import yaml from "js-yaml";
+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 = yaml.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 = path.join(skillDir, category);
+    if (!fs.existsSync(categoryDir)) continue;
+    const stat = fs.statSync(categoryDir);
+    if (!stat.isDirectory()) continue;
+    for (const file of walkDirectory(categoryDir)) {
+      resources.push({
+        relativePath: path.relative(skillDir, file),
+        absolutePath: file,
+        category
+      });
+    }
+  }
+  return resources;
+}
+function parseSkillFile(skillMdPath, source, loadInstructions = false) {
+  const content = fs.readFileSync(skillMdPath, "utf-8");
+  return parseSkillContent(content, skillMdPath, source, loadInstructions);
+}
+function parseSkillContent(content, sourcePath, source, loadInstructions = false) {
+  const sourceDir = path.dirname(sourcePath);
+  const fallbackName = path.basename(sourceDir);
+  const { frontmatter, body } = parseFrontmatter(content);
+  const metadata = parseMetadata(frontmatter, fallbackName);
+  const resources = fs.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 = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield* walkDirectory(fullPath);
+    } else if (entry.isFile()) {
+      yield fullPath;
+    }
+  }
+}
+var RESOURCE_CATEGORIES, MAX_NAME_LENGTH, MAX_DESCRIPTION_LENGTH, NAME_PATTERN;
+var init_parser = __esm({
+  "src/skills/parser.ts"() {
+    "use strict";
+    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
+});
+import { minimatch } from "minimatch";
+var DEFAULT_CHAR_BUDGET, SUMMARY_DESCRIPTION_LIMIT, SkillRegistry;
+var init_registry2 = __esm({
+  "src/skills/registry.ts"() {
+    "use strict";
+    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) => 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
+import fs2 from "fs/promises";
+var Skill;
+var init_skill = __esm({
+  "src/skills/skill.ts"() {
+    "use strict";
+    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 fs2.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 = fs2.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
+import fs3 from "fs";
+import os from "os";
+import path2 from "path";
+function loadSkillsFromDirectory(dir, source, onWarning) {
+  if (!fs3.existsSync(dir)) return [];
+  const stat = fs3.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 ?? path2.join(os.homedir(), CONFIG_DIR_NAME, SKILLS_DIR_NAME);
+  const userSkills = loadSkillsFromDirectory(userSkillsDir, {
+    type: "user",
+    path: userSkillsDir
+  });
+  registry.registerMany(userSkills);
+  if (options?.projectDir) {
+    const projectSkillsDir = path2.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("~") ? path2.join(os.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 = fs3.readdirSync(dir, { withFileTypes: true });
+  } catch (error) {
+    onWarning?.(
+      `Cannot read skill directory ${dir}: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return;
+  }
+  const skillMdPath = path2.join(dir, "SKILL.md");
+  if (fs3.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(path2.join(dir, entry.name), source, results, onWarning);
+    }
+  }
+}
+var SKILLS_DIR_NAME, CONFIG_DIR_NAME;
+var init_loader = __esm({
+  "src/skills/loader.ts"() {
+    "use strict";
+    init_parser();
+    init_registry2();
+    init_skill();
+    SKILLS_DIR_NAME = "skills";
+    CONFIG_DIR_NAME = ".llmist";
+  }
+});
+
+// src/skills/use-skill-gadget.ts
+import { z as z4 } from "zod";
+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: z4.object({
+      skill: z4.enum(skillNames).describe("Name of the skill to activate"),
+      arguments: z4.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 USE_SKILL_GADGET_NAME;
+var init_use_skill_gadget = __esm({
+  "src/skills/use-skill-gadget.ts"() {
+    "use strict";
+    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;
@@ -12194,6 +12819,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();
@@ -12205,12 +12834,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) {
@@ -12347,6 +12978,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 };
@@ -12438,16 +13101,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,
@@ -13132,8 +13854,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:");
@@ -13198,7 +13920,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();
@@ -13234,8 +13956,9 @@ var init_parser = __esm({
        * - `GadgetName` - Auto-generate ID, no dependencies
        * - `GadgetName:my_id` - Explicit ID, no dependencies
        * - `GadgetName:my_id:dep1,dep2` - Explicit ID with dependencies
+       * - `GadgetName:my_id:dep1:dep2:dep3` - Colons treated as dep separators (LLM resilience)
        *
-       * Dependencies must be comma-separated invocation IDs.
+       * Dependencies can be comma-separated or colon-separated invocation IDs.
        */
       parseInvocationMetadata(headerLine) {
         const parts = headerLine.split(":");
@@ -13252,7 +13975,12 @@ var init_parser = __esm({
             dependencies: []
           };
         } else {
-          const deps = parts[2].split(",").map((d) => d.trim()).filter((d) => d.length > 0);
+          const depsRaw = parts.slice(2).join(",");
+          const deps = [
+            ...new Set(
+              depsRaw.split(",").map((d) => d.trim()).filter((d) => d.length > 0)
+            )
+          ];
           return {
             gadgetName: parts[0],
             invocationId: parts[1].trim(),
@@ -13404,7 +14132,7 @@ var init_typed_gadget = __esm({
 
 // src/gadgets/executor.ts
 import equal from "fast-deep-equal";
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 function getHostExportsInternal() {
   return {
     AgentBuilder,
@@ -13412,7 +14140,7 @@ function getHostExportsInternal() {
     createGadget,
     ExecutionTree,
     LLMist,
-    z: z4
+    z: z5
   };
 }
 var GadgetExecutor;
@@ -13430,7 +14158,7 @@ var init_executor = __esm({
     init_create_gadget();
     init_error_formatter();
     init_exceptions();
-    init_parser();
+    init_parser2();
     init_typed_gadget();
     GadgetExecutor = class {
       registry;
@@ -13825,6 +14553,8 @@ var init_gadget_concurrency_manager = __esm({
       concurrencyQueue = /* @__PURE__ */ new Map();
       /** All active gadget promises, keyed by invocationId */
       inFlightExecutions = /* @__PURE__ */ new Map();
+      /** Gadget name for each in-flight invocationId (for timeout event emission) */
+      inFlightGadgetNames = /* @__PURE__ */ new Map();
       /** Queue of exclusive gadgets deferred until in-flight gadgets complete */
       exclusiveQueue = [];
       constructor(options) {
@@ -13952,6 +14682,7 @@ var init_gadget_concurrency_manager = __esm({
         const currentCount = this.activeCountByGadget.get(gadgetName) ?? 0;
         this.activeCountByGadget.set(gadgetName, currentCount + 1);
         this.inFlightExecutions.set(invocationId, promise);
+        this.inFlightGadgetNames.set(invocationId, gadgetName);
       }
       /**
        * Called when a gadget execution completes.
@@ -13995,11 +14726,25 @@ var init_gadget_concurrency_manager = __esm({
         this.exclusiveQueue.push(call);
       }
       /**
-       * Clear the inFlightExecutions map after all promises have completed.
-       * Called after waitForAll resolves.
+       * Clear all in-flight tracking state.
+       * Called after all promises have completed, or on force-timeout.
+       * Also clears active gadget counts to prevent stale state when
+       * hanging promises eventually resolve into the void.
        */
       clearInFlight() {
         this.inFlightExecutions.clear();
+        this.inFlightGadgetNames.clear();
+        this.activeCountByGadget.clear();
+      }
+      /**
+       * Get metadata for all currently in-flight executions.
+       * Used by the dispatcher to emit skip events when the in-flight timeout fires.
+       */
+      getInFlightEntries() {
+        return Array.from(this.inFlightGadgetNames.entries()).map(([invocationId, gadgetName]) => ({
+          invocationId,
+          gadgetName
+        }));
       }
       // ==========================================================================
       // Waiting
@@ -14324,6 +15069,7 @@ var init_gadget_dispatcher = __esm({
       logger;
       pushToQueue;
       drainQueue;
+      inFlightTimeoutMs;
       constructor(options) {
         this.iteration = options.iteration;
         this.hookLifecycle = options.hookLifecycle;
@@ -14338,6 +15084,7 @@ var init_gadget_dispatcher = __esm({
         this.logger = options.logger ?? createLogger({ name: "llmist:gadget-dispatcher" });
         this.pushToQueue = options.pushToQueue;
         this.drainQueue = options.drainQueue;
+        this.inFlightTimeoutMs = options.inFlightTimeoutMs ?? 3e5;
       }
       // ==========================================================================
       // Primary dispatch entry point
@@ -14369,39 +15116,54 @@ var init_gadget_dispatcher = __esm({
             parentId: this.parentNodeId
           });
         }
+        let effectiveCall = call;
         if (call.dependencies.length > 0) {
-          if (call.dependencies.includes(call.invocationId)) {
-            this.logger.warn("Gadget has self-referential dependency (depends on itself)", {
+          const selfRefs = [];
+          const validDeps = [];
+          for (const dep of call.dependencies) {
+            (dep === call.invocationId ? selfRefs : validDeps).push(dep);
+          }
+          if (selfRefs.length > 0) {
+            this.logger.warn("Filtering self-referential dependencies", {
               gadgetName: call.gadgetName,
-              invocationId: call.invocationId
+              invocationId: call.invocationId,
+              removedSelfRefs: selfRefs,
+              remainingDeps: validDeps
             });
-            const errorMessage = `Gadget "${call.invocationId}" cannot depend on itself (self-referential dependency)`;
-            for await (const evt of this.emitGadgetSkipEvents(call, call.invocationId, errorMessage)) {
-              yield evt;
+            effectiveCall = { ...call, dependencies: validDeps };
+            if (validDeps.length === 0) {
+              const errorMessage = `Gadget "${call.invocationId}" cannot depend on itself (self-referential dependency)`;
+              for await (const evt of this.emitGadgetSkipEvents(
+                effectiveCall,
+                call.invocationId,
+                errorMessage
+              )) {
+                yield evt;
+              }
+              return;
             }
-            return;
           }
-          const failedDep = this.dependencyResolver.getFailedDependency(call);
+          const failedDep = this.dependencyResolver.getFailedDependency(effectiveCall);
           if (failedDep) {
-            const skipEvents = await this.handleFailedDependency(call, failedDep);
+            const skipEvents = await this.handleFailedDependency(effectiveCall, failedDep);
             for (const evt of skipEvents) {
               yield evt;
             }
             return;
           }
-          if (!this.dependencyResolver.isAllSatisfied(call)) {
-            const unsatisfied = call.dependencies.filter(
+          if (!this.dependencyResolver.isAllSatisfied(effectiveCall)) {
+            const unsatisfied = effectiveCall.dependencies.filter(
               (dep) => !this.dependencyResolver.isCompleted(dep)
             );
             this.logger.debug("Queueing gadget for later - waiting on dependencies", {
-              gadgetName: call.gadgetName,
-              invocationId: call.invocationId,
+              gadgetName: effectiveCall.gadgetName,
+              invocationId: effectiveCall.invocationId,
               waitingOn: unsatisfied
             });
-            this.dependencyResolver.addPending(call);
+            this.dependencyResolver.addPending(effectiveCall);
             return;
           }
-          for await (const evt of this._checkLimitThenExecute(call)) {
+          for await (const evt of this._checkLimitThenExecute(effectiveCall)) {
             yield evt;
           }
           for await (const evt of this.processPendingGadgets()) {
@@ -14540,7 +15302,31 @@ var init_gadget_dispatcher = __esm({
           queuedCount: this.concurrencyManager.getQueuedGadgetCount()
         });
         const POLL_INTERVAL_MS = 100;
+        const startTime = Date.now();
         while (this.concurrencyManager.inFlightCount > 0 || this.concurrencyManager.hasQueuedGadgets()) {
+          if (Date.now() - startTime >= this.inFlightTimeoutMs) {
+            const timedOutEntries = this.concurrencyManager.getInFlightEntries();
+            this.logger.error("In-flight gadget timeout exceeded, force-clearing remaining gadgets", {
+              timeoutMs: this.inFlightTimeoutMs,
+              remainingInFlight: timedOutEntries.length,
+              remainingQueued: this.concurrencyManager.getQueuedGadgetCount(),
+              timedOutInvocations: timedOutEntries.map((e) => e.invocationId)
+            });
+            const timeoutError = `Gadget execution timed out after ${this.inFlightTimeoutMs}ms`;
+            for (const { invocationId, gadgetName } of timedOutEntries) {
+              this.dependencyResolver.markFailed(invocationId);
+              yield {
+                type: "gadget_skipped",
+                gadgetName,
+                invocationId,
+                parameters: {},
+                failedDependency: invocationId,
+                failedDependencyError: timeoutError
+              };
+            }
+            this.concurrencyManager.clearInFlight();
+            break;
+          }
           const allDone = this.concurrencyManager.getAllDonePromise();
           const result = await Promise.race([
             allDone,
@@ -15031,7 +15817,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();
@@ -15126,7 +15912,8 @@ var init_stream_processor = __esm({
             const evts = [...this.completedResultsQueue];
             this.completedResultsQueue = [];
             return evts;
-          }
+          },
+          inFlightTimeoutMs: options.inFlightTimeoutMs
         });
       }
       /**
@@ -15350,6 +16137,7 @@ var init_stream_processor_factory = __esm({
       logger;
       requestHumanInput;
       defaultGadgetTimeoutMs;
+      inFlightTimeoutMs;
       gadgetExecutionMode;
       client;
       mediaStore;
@@ -15368,6 +16156,7 @@ var init_stream_processor_factory = __esm({
         this.logger = options.logger;
         this.requestHumanInput = options.requestHumanInput;
         this.defaultGadgetTimeoutMs = options.defaultGadgetTimeoutMs;
+        this.inFlightTimeoutMs = options.inFlightTimeoutMs;
         this.gadgetExecutionMode = options.gadgetExecutionMode;
         this.client = options.client;
         this.mediaStore = options.mediaStore;
@@ -15399,6 +16188,7 @@ var init_stream_processor_factory = __esm({
           logger: this.logger.getSubLogger({ name: "stream-processor" }),
           requestHumanInput: this.requestHumanInput,
           defaultGadgetTimeoutMs: this.defaultGadgetTimeoutMs,
+          inFlightTimeoutMs: this.inFlightTimeoutMs,
           gadgetExecutionMode: this.gadgetExecutionMode,
           client: this.client,
           mediaStore: this.mediaStore,
@@ -16155,7 +16945,7 @@ init_builder();
 init_event_handlers();
 init_file_logging();
 init_hook_presets();
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 
 // src/agent/compaction/index.ts
 init_config();
@@ -16464,7 +17254,7 @@ function resultWithFile(result, fileData, mimeType, options) {
 
 // src/index.ts
 init_output_viewer();
-init_parser();
+init_parser2();
 init_registry();
 init_typed_gadget();
 init_constants2();
@@ -16731,6 +17521,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;
@@ -16926,11 +17724,14 @@ export {
   OpenRouterProvider,
   RateLimitTracker,
   SimpleSessionManager,
+  Skill,
+  SkillRegistry,
   SlidingWindowStrategy,
   StreamProcessor,
   SummarizationStrategy,
   TaskCompletionSignal,
   TimeoutException,
+  USE_SKILL_GADGET_NAME,
   audioFromBase64,
   audioFromBuffer,
   collectEvents,
@@ -16948,10 +17749,12 @@ export {
   createOpenAIProviderFromEnv,
   createOpenRouterProviderFromEnv,
   createSubagent,
+  createUseSkillGadget,
   defaultLogger,
   detectAudioMimeType,
   detectImageMimeType,
   discoverProviderAdapters,
+  discoverSkills,
   extractMessageText,
   extractRetryAfterMs,
   filterByDepth,
@@ -16994,15 +17797,21 @@ export {
   iterationProgressHint,
   listPresets,
   listSubagents,
+  loadSkillsFromDirectory,
   normalizeMessageContent,
   parallelGadgetHint,
   parseDataUrl,
+  parseFrontmatter,
   parseManifest,
+  parseMetadata,
   parseRetryAfterHeader,
+  parseSkillContent,
+  parseSkillFile,
   randomDelay,
   resetFileLoggingState,
   resolveConfig,
   resolveHintTemplate,
+  resolveInstructions,
   resolveModel,
   resolvePromptTemplate,
   resolveRateLimitConfig,
@@ -17017,9 +17826,12 @@ export {
   resultWithImages,
   resultWithMedia,
   runWithHandlers,
+  scanResources,
   schemaToJSONSchema,
   stream,
   stripProviderPrefix,
+  substituteArguments,
+  substituteVariables,
   text,
   timing,
   toBase64,
@@ -17027,9 +17839,10 @@ export {
   validateAndApplyDefaults,
   validateGadgetParams,
   validateGadgetSchema,
+  validateMetadata,
   withErrorHandling,
   withRetry,
   withTimeout,
-  z5 as z
+  z6 as z
 };
 //# sourceMappingURL=index.js.map