@elizaos/plugin-agent-skills 1.0.0

package/dist/index.js

@@ -0,0 +1,3698 @@
+// src/services/skills.ts
+import { Service } from "@elizaos/core";
+
+// src/types.ts
+var SKILL_NAME_MAX_LENGTH = 64;
+var SKILL_DESCRIPTION_MAX_LENGTH = 1024;
+var SKILL_COMPATIBILITY_MAX_LENGTH = 500;
+var SKILL_BODY_RECOMMENDED_TOKENS = 5e3;
+var SKILL_NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+var SKILL_SOURCE_PRECEDENCE = {
+  workspace: 5,
+  managed: 4,
+  bundled: 3,
+  plugin: 2,
+  extra: 1
+};
+
+// src/parser.ts
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n?/);
+  if (!match) {
+    return { frontmatter: null, body: content, raw: "" };
+  }
+  const raw = match[1];
+  const body = content.slice(match[0].length).trim();
+  try {
+    const frontmatter = parseYamlSubset(raw);
+    return { frontmatter, body, raw };
+  } catch {
+    return { frontmatter: null, body, raw };
+  }
+}
+function parseYamlSubset(yaml) {
+  const result = {};
+  const lines = yaml.split("\n");
+  let currentKey = "";
+  let currentIndent = 0;
+  const stack = [
+    { obj: result, indent: -1 }
+  ];
+  let collectingJson = false;
+  let jsonBuffer = "";
+  let jsonDepth = 0;
+  let jsonKey = "";
+  let jsonParent = null;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+    if (collectingJson) {
+      if (!trimmed) continue;
+      jsonBuffer += trimmed;
+      let inString = false;
+      let escape = false;
+      for (const char of trimmed) {
+        if (escape) {
+          escape = false;
+          continue;
+        }
+        if (char === "\\") {
+          escape = true;
+          continue;
+        }
+        if (char === '"') {
+          inString = !inString;
+          continue;
+        }
+        if (!inString) {
+          if (char === "{" || char === "[") jsonDepth++;
+          else if (char === "}" || char === "]") jsonDepth--;
+        }
+      }
+      if (jsonDepth === 0) {
+        try {
+          const cleanedJson = jsonBuffer.replace(/,(\s*[}\]])/g, "$1");
+          if (jsonParent) {
+            jsonParent[jsonKey] = JSON.parse(cleanedJson);
+          }
+        } catch {
+          if (jsonParent) {
+            jsonParent[jsonKey] = jsonBuffer;
+          }
+        }
+        collectingJson = false;
+        jsonBuffer = "";
+        jsonKey = "";
+        jsonParent = null;
+      }
+      continue;
+    }
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const indent = line.search(/\S/);
+    const kvMatch = trimmed.match(/^([a-zA-Z0-9_-]+):\s*(.*)/);
+    if (kvMatch) {
+      const [, key, valueStr] = kvMatch;
+      while (stack.length > 1 && stack[stack.length - 1].indent >= indent) {
+        stack.pop();
+      }
+      const parent = stack[stack.length - 1].obj;
+      if (valueStr === "" || valueStr === "|" || valueStr === ">") {
+        let nextLineIdx = i + 1;
+        while (nextLineIdx < lines.length && !lines[nextLineIdx].trim()) {
+          nextLineIdx++;
+        }
+        const nextTrimmed = nextLineIdx < lines.length ? lines[nextLineIdx].trim() : "";
+        if (nextTrimmed.startsWith("{") || nextTrimmed.startsWith("[")) {
+          jsonKey = key;
+          jsonParent = parent;
+          jsonBuffer = "";
+          jsonDepth = 0;
+          collectingJson = true;
+        } else {
+          const childObj = {};
+          parent[key] = childObj;
+          stack.push({ obj: childObj, indent });
+          currentKey = key;
+          currentIndent = indent;
+        }
+      } else if (valueStr.startsWith("{") || valueStr.startsWith("[")) {
+        let depth = 0;
+        let inString = false;
+        let escape = false;
+        for (const char of valueStr) {
+          if (escape) {
+            escape = false;
+            continue;
+          }
+          if (char === "\\") {
+            escape = true;
+            continue;
+          }
+          if (char === '"') {
+            inString = !inString;
+            continue;
+          }
+          if (!inString) {
+            if (char === "{" || char === "[") depth++;
+            else if (char === "}" || char === "]") depth--;
+          }
+        }
+        if (depth === 0) {
+          try {
+            const cleanedJson = valueStr.replace(/,(\s*[}\]])/g, "$1");
+            parent[key] = JSON.parse(cleanedJson);
+          } catch {
+            parent[key] = valueStr;
+          }
+        } else {
+          jsonKey = key;
+          jsonParent = parent;
+          jsonBuffer = valueStr;
+          jsonDepth = depth;
+          collectingJson = true;
+        }
+      } else {
+        parent[key] = parseYamlValue(valueStr);
+      }
+    }
+  }
+  return result;
+}
+function parseYamlValue(value) {
+  const trimmed = value.trim();
+  if (trimmed.startsWith('"') && trimmed.endsWith('"') || trimmed.startsWith("'") && trimmed.endsWith("'")) {
+    return trimmed.slice(1, -1);
+  }
+  if (trimmed === "true") return true;
+  if (trimmed === "false") return false;
+  if (trimmed === "null" || trimmed === "~") return null;
+  if (/^-?\d+$/.test(trimmed)) return parseInt(trimmed, 10);
+  if (/^-?\d+\.\d+$/.test(trimmed)) return parseFloat(trimmed);
+  return trimmed;
+}
+function validateFrontmatter(frontmatter, directoryName) {
+  const errors = [];
+  const warnings = [];
+  if (!frontmatter.name) {
+    errors.push({
+      field: "name",
+      message: "name is required",
+      code: "MISSING_NAME"
+    });
+  } else {
+    if (frontmatter.name.length > SKILL_NAME_MAX_LENGTH) {
+      errors.push({
+        field: "name",
+        message: `name must be ${SKILL_NAME_MAX_LENGTH} characters or less`,
+        code: "NAME_TOO_LONG"
+      });
+    }
+    if (!SKILL_NAME_PATTERN.test(frontmatter.name)) {
+      errors.push({
+        field: "name",
+        message: "name must contain only lowercase letters, numbers, and hyphens, cannot start/end with hyphen or have consecutive hyphens",
+        code: "INVALID_NAME_FORMAT"
+      });
+    }
+    if (frontmatter.name.startsWith("-") || frontmatter.name.endsWith("-")) {
+      errors.push({
+        field: "name",
+        message: "name cannot start or end with a hyphen",
+        code: "NAME_INVALID_HYPHEN"
+      });
+    }
+    if (frontmatter.name.includes("--")) {
+      errors.push({
+        field: "name",
+        message: "name cannot contain consecutive hyphens",
+        code: "NAME_CONSECUTIVE_HYPHENS"
+      });
+    }
+    if (directoryName && directoryName !== frontmatter.name) {
+      errors.push({
+        field: "name",
+        message: `name "${frontmatter.name}" must match directory name "${directoryName}"`,
+        code: "NAME_MISMATCH"
+      });
+    }
+  }
+  if (!frontmatter.description) {
+    errors.push({
+      field: "description",
+      message: "description is required",
+      code: "MISSING_DESCRIPTION"
+    });
+  } else {
+    if (frontmatter.description.length > SKILL_DESCRIPTION_MAX_LENGTH) {
+      errors.push({
+        field: "description",
+        message: `description must be ${SKILL_DESCRIPTION_MAX_LENGTH} characters or less`,
+        code: "DESCRIPTION_TOO_LONG"
+      });
+    }
+    if (frontmatter.description.length < 20) {
+      warnings.push({
+        field: "description",
+        message: "description is very short; consider adding more detail about when to use this skill",
+        code: "DESCRIPTION_TOO_SHORT"
+      });
+    }
+  }
+  if (frontmatter.compatibility) {
+    if (frontmatter.compatibility.length > SKILL_COMPATIBILITY_MAX_LENGTH) {
+      errors.push({
+        field: "compatibility",
+        message: `compatibility must be ${SKILL_COMPATIBILITY_MAX_LENGTH} characters or less`,
+        code: "COMPATIBILITY_TOO_LONG"
+      });
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+function validateSkillDirectory(path2, content, directoryName) {
+  const errors = [];
+  const warnings = [];
+  const { frontmatter } = parseFrontmatter(content);
+  if (!frontmatter) {
+    errors.push({
+      field: "frontmatter",
+      message: "SKILL.md must have valid YAML frontmatter",
+      code: "MISSING_FRONTMATTER"
+    });
+    return { valid: false, errors, warnings };
+  }
+  const fmResult = validateFrontmatter(frontmatter, directoryName);
+  errors.push(...fmResult.errors);
+  warnings.push(...fmResult.warnings);
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+function extractBody(content) {
+  const { body } = parseFrontmatter(content);
+  return body;
+}
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+function generateSkillsXml(skills, options = {}) {
+  if (skills.length === 0) {
+    return "";
+  }
+  const skillElements = skills.map((skill) => {
+    const locationTag = options.includeLocation && skill.location ? `
+    <location>${escapeXml(skill.location)}</location>` : "";
+    return `  <skill>
+    <name>${escapeXml(skill.name)}</name>
+    <description>${escapeXml(skill.description)}</description>${locationTag}
+  </skill>`;
+  }).join("\n");
+  return `<available_skills>
+${skillElements}
+</available_skills>`;
+}
+function escapeXml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+
+// src/storage.ts
+var MemorySkillStore = class {
+  type = "memory";
+  skills = /* @__PURE__ */ new Map();
+  basePath;
+  constructor(basePath = "/virtual/skills") {
+    this.basePath = basePath;
+  }
+  async initialize() {
+  }
+  async listSkills() {
+    return Array.from(this.skills.keys());
+  }
+  async hasSkill(slug) {
+    return this.skills.has(slug);
+  }
+  async loadSkillContent(slug) {
+    const pkg = this.skills.get(slug);
+    if (!pkg) return null;
+    const skillMd = pkg.files.get("SKILL.md");
+    if (!skillMd || !skillMd.isText) return null;
+    return skillMd.content;
+  }
+  async loadFile(slug, relativePath) {
+    const pkg = this.skills.get(slug);
+    if (!pkg) return null;
+    const file = pkg.files.get(relativePath);
+    if (!file) return null;
+    return file.content;
+  }
+  async listFiles(slug, subdir) {
+    const pkg = this.skills.get(slug);
+    if (!pkg) return [];
+    const prefix = subdir ? `${subdir}/` : "";
+    const files = [];
+    for (const [path2] of pkg.files) {
+      if (subdir) {
+        if (path2.startsWith(prefix) && !path2.slice(prefix.length).includes("/")) {
+          files.push(path2.slice(prefix.length));
+        }
+      } else if (!path2.includes("/")) {
+        files.push(path2);
+      }
+    }
+    return files;
+  }
+  async saveSkill(pkg) {
+    this.skills.set(pkg.slug, pkg);
+  }
+  async deleteSkill(slug) {
+    return this.skills.delete(slug);
+  }
+  getSkillPath(slug) {
+    return `${this.basePath}/${slug}`;
+  }
+  /**
+   * Load a skill directly from content (no network/file needed).
+   */
+  async loadFromContent(slug, skillMdContent, additionalFiles) {
+    const files = /* @__PURE__ */ new Map();
+    files.set("SKILL.md", {
+      path: "SKILL.md",
+      content: skillMdContent,
+      isText: true
+    });
+    if (additionalFiles) {
+      for (const [path2, content] of additionalFiles) {
+        files.set(path2, {
+          path: path2,
+          content,
+          isText: typeof content === "string"
+        });
+      }
+    }
+    await this.saveSkill({ slug, files });
+  }
+  /**
+   * Load a skill from a zip buffer (for registry downloads).
+   */
+  async loadFromZip(slug, zipBuffer) {
+    const { unzipSync } = await import("fflate");
+    const unzipped = unzipSync(zipBuffer);
+    const files = /* @__PURE__ */ new Map();
+    for (const [fileName, data] of Object.entries(unzipped)) {
+      if (fileName.endsWith("/")) continue;
+      const parts = fileName.split("/").filter((p) => p && p !== ".." && p !== ".");
+      if (parts.length === 0) continue;
+      const relativePath = parts.join("/");
+      const isText = isTextFile(relativePath);
+      files.set(relativePath, {
+        path: relativePath,
+        content: isText ? new TextDecoder().decode(data) : data,
+        isText
+      });
+    }
+    await this.saveSkill({ slug, files });
+  }
+  /**
+   * Get the full skill package (for export/transfer).
+   */
+  getPackage(slug) {
+    return this.skills.get(slug);
+  }
+  /**
+   * Save a skill package from simple file list format.
+   * Convenience method for use with GitHub/URL installs.
+   */
+  async savePackage(pkg) {
+    const files = /* @__PURE__ */ new Map();
+    for (const file of pkg.files) {
+      const isText = typeof file.content === "string";
+      files.set(file.name, {
+        path: file.name,
+        content: file.content,
+        isText
+      });
+    }
+    await this.saveSkill({ slug: pkg.slug, files });
+  }
+  /**
+   * Get all skills in memory.
+   */
+  getAllPackages() {
+    return new Map(this.skills);
+  }
+};
+var FileSystemSkillStore = class {
+  type = "filesystem";
+  basePath;
+  fs = null;
+  path = null;
+  constructor(basePath = "./skills") {
+    this.basePath = basePath;
+  }
+  async initialize() {
+    try {
+      this.fs = await import("fs");
+      this.path = await import("path");
+      if (!this.fs.existsSync(this.basePath)) {
+        this.fs.mkdirSync(this.basePath, { recursive: true });
+      }
+    } catch {
+      throw new Error("FileSystemSkillStore requires Node.js fs module");
+    }
+  }
+  async listSkills() {
+    if (!this.fs) await this.initialize();
+    const entries = this.fs.readdirSync(this.basePath, {
+      withFileTypes: true
+    });
+    return entries.filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => e.name);
+  }
+  async hasSkill(slug) {
+    if (!this.fs) await this.initialize();
+    const skillPath = this.path.join(this.basePath, slug, "SKILL.md");
+    return this.fs.existsSync(skillPath);
+  }
+  async loadSkillContent(slug) {
+    if (!this.fs) await this.initialize();
+    const skillPath = this.path.join(this.basePath, slug, "SKILL.md");
+    if (!this.fs.existsSync(skillPath)) return null;
+    return this.fs.readFileSync(skillPath, "utf-8");
+  }
+  async loadFile(slug, relativePath) {
+    if (!this.fs) await this.initialize();
+    const safePath = this.path.basename(relativePath);
+    const subdir = this.path.dirname(relativePath);
+    const fullPath = this.path.join(this.basePath, slug, subdir, safePath);
+    if (!this.fs.existsSync(fullPath)) return null;
+    if (isTextFile(relativePath)) {
+      return this.fs.readFileSync(fullPath, "utf-8");
+    } else {
+      return new Uint8Array(this.fs.readFileSync(fullPath));
+    }
+  }
+  async listFiles(slug, subdir) {
+    if (!this.fs) await this.initialize();
+    const dirPath = subdir ? this.path.join(this.basePath, slug, subdir) : this.path.join(this.basePath, slug);
+    if (!this.fs.existsSync(dirPath)) return [];
+    return this.fs.readdirSync(dirPath).filter((f) => !f.startsWith("."));
+  }
+  async saveSkill(pkg) {
+    if (!this.fs) await this.initialize();
+    const skillDir = this.path.join(this.basePath, pkg.slug);
+    if (!this.fs.existsSync(skillDir)) {
+      this.fs.mkdirSync(skillDir, { recursive: true });
+    }
+    for (const [relativePath, file] of pkg.files) {
+      const fullPath = this.path.join(skillDir, relativePath);
+      const dir = this.path.dirname(fullPath);
+      if (!this.fs.existsSync(dir)) {
+        this.fs.mkdirSync(dir, { recursive: true });
+      }
+      if (file.isText) {
+        this.fs.writeFileSync(fullPath, file.content, "utf-8");
+      } else {
+        this.fs.writeFileSync(fullPath, file.content);
+      }
+    }
+  }
+  async deleteSkill(slug) {
+    if (!this.fs) await this.initialize();
+    const skillDir = this.path.join(this.basePath, slug);
+    if (!this.fs.existsSync(skillDir)) return false;
+    this.fs.rmSync(skillDir, { recursive: true, force: true });
+    return true;
+  }
+  getSkillPath(slug) {
+    return this.path ? this.path.resolve(this.basePath, slug) : `${this.basePath}/${slug}`;
+  }
+  /**
+   * Save a skill from a zip buffer.
+   */
+  async saveFromZip(slug, zipBuffer) {
+    const { unzipSync } = await import("fflate");
+    const unzipped = unzipSync(zipBuffer);
+    const files = /* @__PURE__ */ new Map();
+    for (const [fileName, data] of Object.entries(unzipped)) {
+      if (fileName.endsWith("/")) continue;
+      const parts = fileName.split("/").filter((p) => p && p !== ".." && p !== ".");
+      if (parts.length === 0) continue;
+      const relativePath = parts.join("/");
+      const isText = isTextFile(relativePath);
+      files.set(relativePath, {
+        path: relativePath,
+        content: isText ? new TextDecoder().decode(data) : data,
+        isText
+      });
+    }
+    await this.saveSkill({ slug, files });
+  }
+};
+function isTextFile(filePath) {
+  const textExtensions = /* @__PURE__ */ new Set([
+    ".md",
+    ".txt",
+    ".json",
+    ".yaml",
+    ".yml",
+    ".toml",
+    ".js",
+    ".ts",
+    ".py",
+    ".rs",
+    ".sh",
+    ".bash",
+    ".html",
+    ".css",
+    ".xml",
+    ".svg",
+    ".env",
+    ".gitignore",
+    ".dockerignore"
+  ]);
+  const ext = filePath.substring(filePath.lastIndexOf(".")).toLowerCase();
+  return textExtensions.has(ext) || !filePath.includes(".");
+}
+function createStorage(options) {
+  const { type = "auto", basePath } = options;
+  if (type === "memory") {
+    return new MemorySkillStore(basePath);
+  }
+  if (type === "filesystem") {
+    return new FileSystemSkillStore(basePath);
+  }
+  if (typeof window !== "undefined" || typeof process === "undefined") {
+    return new MemorySkillStore(basePath);
+  }
+  return new FileSystemSkillStore(basePath);
+}
+async function loadSkillFromStorage(storage, slug, options = {}) {
+  const content = await storage.loadSkillContent(slug);
+  if (!content) return null;
+  const { frontmatter } = parseFrontmatter(content);
+  if (!frontmatter) return null;
+  if (options.validate !== false) {
+    const result = validateFrontmatter(frontmatter, slug);
+    if (!result.valid) {
+      console.warn(`Skill ${slug} validation failed:`, result.errors);
+    }
+  }
+  const scripts = await storage.listFiles(slug, "scripts");
+  const references = await storage.listFiles(slug, "references");
+  const assets = await storage.listFiles(slug, "assets");
+  return {
+    slug,
+    name: frontmatter.name,
+    description: frontmatter.description,
+    version: frontmatter.metadata?.version?.toString() || "local",
+    content,
+    frontmatter,
+    path: storage.getSkillPath(slug),
+    scripts,
+    references,
+    assets,
+    loadedAt: Date.now()
+  };
+}
+
+// src/services/skills.ts
+var CLAWHUB_API = "https://clawhub.ai";
+var CACHE_TTL = {
+  CATALOG: 1e3 * 60 * 60,
+  // 1 hour - list of all skills
+  SKILL_DETAILS: 1e3 * 60 * 30,
+  // 30 min - individual skill details
+  SEARCH: 1e3 * 60 * 5
+  // 5 min - search results
+};
+var MAX_PACKAGE_SIZE = 10 * 1024 * 1024;
+var DEFAULT_AUTO_REFRESH_INTERVAL = 5e3;
+var ELIGIBILITY_CACHE_TTL = 5 * 60 * 1e3;
+function sanitizeSlug(slug) {
+  const sanitized = slug.replace(/[^a-zA-Z0-9_-]/g, "");
+  if (sanitized !== slug || sanitized.length === 0 || sanitized.length > 100) {
+    throw new Error(`Invalid skill slug: ${slug}`);
+  }
+  return sanitized;
+}
+var AgentSkillsService = class _AgentSkillsService extends Service {
+  constructor(runtime, config) {
+    super(runtime);
+    this.runtime = runtime;
+    const skillsDirSetting = runtime.getSetting("SKILLS_DIR") ?? runtime.getSetting("CLAWHUB_SKILLS_DIR");
+    const skillsDir = config?.skillsDir || (typeof skillsDirSetting === "string" ? skillsDirSetting : null) || "./skills";
+    const storageTypeSetting = runtime.getSetting("SKILLS_STORAGE_TYPE");
+    const storageType = config?.storageType || (typeof storageTypeSetting === "string" ? storageTypeSetting : null) || "auto";
+    const registrySetting = runtime.getSetting("SKILLS_REGISTRY") ?? runtime.getSetting("CLAWHUB_REGISTRY");
+    this.apiBase = config?.registryUrl || (typeof registrySetting === "string" ? registrySetting : null) || CLAWHUB_API;
+    this.autoLoad = config?.autoLoad ?? (runtime.getSetting("SKILLS_AUTO_LOAD") !== "false" && runtime.getSetting("CLAWHUB_AUTO_LOAD") !== "false");
+    const bundledDirsConfig = config?.bundledSkillsDirs || runtime.getSetting("BUNDLED_SKILLS_DIRS") || runtime.getSetting("OTTO_BUNDLED_SKILLS_DIR");
+    if (Array.isArray(bundledDirsConfig)) {
+      this.bundledSkillsDirs = bundledDirsConfig.filter(Boolean);
+    } else if (typeof bundledDirsConfig === "string" && bundledDirsConfig.trim()) {
+      this.bundledSkillsDirs = bundledDirsConfig.split(",").map((d) => d.trim()).filter(Boolean);
+    } else {
+      this.bundledSkillsDirs = [];
+    }
+    const workspaceDirConfig = config?.workspaceSkillsDir || runtime.getSetting("WORKSPACE_SKILLS_DIR") || runtime.getSetting("OTTO_WORKSPACE_SKILLS_DIR");
+    if (typeof workspaceDirConfig === "string" && workspaceDirConfig.trim()) {
+      this.workspaceSkillsDir = workspaceDirConfig.trim();
+    }
+    const pluginDirsConfig = config?.pluginSkillsDirs || runtime.getSetting("PLUGIN_SKILLS_DIRS") || runtime.getSetting("OTTO_PLUGIN_SKILLS_DIRS");
+    this.pluginSkillsDirs = this.parseDirectoryList(pluginDirsConfig);
+    const extraDirsConfig = config?.extraDirs || runtime.getSetting("EXTRA_SKILLS_DIRS") || runtime.getSetting("OTTO_EXTRA_SKILLS_DIRS") || runtime.getSetting("skills.load.extraDirs");
+    this.extraDirs = this.parseDirectoryList(extraDirsConfig);
+    const allowlistConfig = config?.allowlist || runtime.getSetting("SKILLS_ALLOWLIST") || runtime.getSetting("skills.allowlist");
+    if (allowlistConfig) {
+      this.allowlist = new Set(this.parseStringList(allowlistConfig));
+    }
+    const denylistConfig = config?.denylist || runtime.getSetting("SKILLS_DENYLIST") || runtime.getSetting("skills.denylist");
+    if (denylistConfig) {
+      this.denylist = new Set(this.parseStringList(denylistConfig));
+    }
+    if (config?.skillEntries) {
+      for (const [slug, entry] of Object.entries(config.skillEntries)) {
+        this.skillEntries.set(slug, entry);
+      }
+    }
+    this.autoRefreshEnabled = config?.autoRefresh ?? runtime.getSetting("SKILLS_AUTO_REFRESH") === "true";
+    this.autoRefreshInterval = config?.autoRefreshInterval ?? DEFAULT_AUTO_REFRESH_INTERVAL;
+    this.storage = config?.storage || createStorage({ type: storageType, basePath: skillsDir });
+    if (this.storage.type === "filesystem") {
+      this.catalogCachePath = `${skillsDir}/.cache/catalog.json`;
+      this.lockfilePath = `${skillsDir}/.cache/lock.json`;
+    }
+  }
+  static serviceType = "AGENT_SKILLS_SERVICE";
+  capabilityDescription = "Agent Skills - discover, load, and execute modular agent capabilities";
+  storage;
+  apiBase;
+  autoLoad;
+  // Bundled skills configuration
+  bundledSkillsDirs;
+  bundledStorages = /* @__PURE__ */ new Map();
+  // Phase 4.1: Additional skill source directories
+  workspaceSkillsDir = null;
+  workspaceStorage = null;
+  pluginSkillsDirs = [];
+  pluginStorages = /* @__PURE__ */ new Map();
+  extraDirs = [];
+  extraStorages = /* @__PURE__ */ new Map();
+  // In-memory caches - now tracks LoadedSkill with source info
+  loadedSkills = /* @__PURE__ */ new Map();
+  catalogCache = null;
+  searchCache = /* @__PURE__ */ new Map();
+  detailsCache = /* @__PURE__ */ new Map();
+  // Phase 4.2: Eligibility cache
+  eligibilityCache = /* @__PURE__ */ new Map();
+  // Phase 4.4: Skill configuration
+  allowlist = null;
+  denylist = /* @__PURE__ */ new Set();
+  skillEntries = /* @__PURE__ */ new Map();
+  skillEnvOverrides = /* @__PURE__ */ new Map();
+  skillApiKeys = /* @__PURE__ */ new Map();
+  // Auto-refresh watcher
+  autoRefreshEnabled = false;
+  autoRefreshInterval = DEFAULT_AUTO_REFRESH_INTERVAL;
+  watcherCleanup = null;
+  // Catalog cache for disk persistence (filesystem mode only)
+  catalogCachePath = null;
+  lockfilePath = null;
+  /**
+   * Parse a directory list from config (string or array).
+   */
+  parseDirectoryList(config) {
+    if (Array.isArray(config)) {
+      return config.filter((d) => typeof d === "string" && d.trim().length > 0);
+    }
+    if (typeof config === "string" && config.trim()) {
+      return config.split(",").map((d) => d.trim()).filter(Boolean);
+    }
+    return [];
+  }
+  /**
+   * Parse a string list from config (string or array).
+   */
+  parseStringList(config) {
+    if (Array.isArray(config)) {
+      return config.filter((s) => typeof s === "string");
+    }
+    if (typeof config === "string") {
+      return config.split(",").map((s) => s.trim()).filter(Boolean);
+    }
+    return [];
+  }
+  static async start(runtime, config) {
+    const service = new _AgentSkillsService(runtime, config);
+    await service.initialize();
+    return service;
+  }
+  static async stop(_runtime) {
+  }
+  async stop() {
+    this.runtime.logger.info("AgentSkills: Service stopping...");
+    if (this.watcherCleanup) {
+      this.watcherCleanup();
+      this.watcherCleanup = null;
+    }
+    this.loadedSkills.clear();
+    this.eligibilityCache.clear();
+    this.catalogCache = null;
+    this.searchCache.clear();
+    this.detailsCache.clear();
+  }
+  async initialize() {
+    this.runtime.logger.info(
+      `AgentSkills: Service initializing (storage: ${this.storage.type})...`
+    );
+    await this.storage.initialize();
+    await this.initializeSkillSources();
+    if (this.autoLoad) {
+      await this.loadSkillsFromSource(this.extraStorages, "extra");
+      await this.loadSkillsFromSource(this.pluginStorages, "plugin");
+      await this.loadBundledSkills();
+      await this.loadInstalledSkills();
+      await this.loadWorkspaceSkills();
+    }
+    if (this.storage.type === "filesystem") {
+      await this.loadCatalogFromDisk();
+    }
+    if (this.autoRefreshEnabled && this.storage.type === "filesystem") {
+      this.startAutoRefresh();
+    }
+    const counts = this.getSkillCountsBySource();
+    this.runtime.logger.info(
+      `AgentSkills: Initialized with ${this.loadedSkills.size} skills (workspace: ${counts.workspace}, managed: ${counts.managed}, bundled: ${counts.bundled}, plugin: ${counts.plugin}, extra: ${counts.extra})`
+    );
+  }
+  /**
+   * Initialize all skill source storages.
+   */
+  async initializeSkillSources() {
+    if (this.workspaceSkillsDir) {
+      try {
+        this.workspaceStorage = new FileSystemSkillStore(this.workspaceSkillsDir);
+        await this.workspaceStorage.initialize();
+        this.runtime.logger.info(
+          `AgentSkills: Registered workspace skills directory: ${this.workspaceSkillsDir}`
+        );
+      } catch (error) {
+        this.runtime.logger.debug(
+          `AgentSkills: Workspace skills directory not accessible: ${this.workspaceSkillsDir}`
+        );
+        this.workspaceStorage = null;
+      }
+    }
+    for (const bundledDir of this.bundledSkillsDirs) {
+      try {
+        const bundledStorage = new FileSystemSkillStore(bundledDir);
+        await bundledStorage.initialize();
+        this.bundledStorages.set(bundledDir, bundledStorage);
+        this.runtime.logger.info(
+          `AgentSkills: Registered bundled skills directory: ${bundledDir}`
+        );
+      } catch (error) {
+        this.runtime.logger.warn(
+          `AgentSkills: Failed to initialize bundled skills directory: ${bundledDir}`
+        );
+      }
+    }
+    for (const pluginDir of this.pluginSkillsDirs) {
+      try {
+        const pluginStorage = new FileSystemSkillStore(pluginDir);
+        await pluginStorage.initialize();
+        this.pluginStorages.set(pluginDir, pluginStorage);
+        this.runtime.logger.info(
+          `AgentSkills: Registered plugin skills directory: ${pluginDir}`
+        );
+      } catch (error) {
+        this.runtime.logger.debug(
+          `AgentSkills: Plugin skills directory not accessible: ${pluginDir}`
+        );
+      }
+    }
+    for (const extraDir of this.extraDirs) {
+      try {
+        const extraStorage = new FileSystemSkillStore(extraDir);
+        await extraStorage.initialize();
+        this.extraStorages.set(extraDir, extraStorage);
+        this.runtime.logger.info(
+          `AgentSkills: Registered extra skills directory: ${extraDir}`
+        );
+      } catch (error) {
+        this.runtime.logger.debug(
+          `AgentSkills: Extra skills directory not accessible: ${extraDir}`
+        );
+      }
+    }
+  }
+  /**
+   * Get skill counts by source type.
+   */
+  getSkillCountsBySource() {
+    const counts = {
+      workspace: 0,
+      managed: 0,
+      bundled: 0,
+      plugin: 0,
+      extra: 0
+    };
+    for (const skill of this.loadedSkills.values()) {
+      counts[skill.source]++;
+    }
+    return counts;
+  }
+  /**
+   * Load skills from a set of storages with a specific source type.
+   */
+  async loadSkillsFromSource(storages, source) {
+    for (const [dir, storage] of storages) {
+      const slugs = await storage.listSkills();
+      this.runtime.logger.debug(
+        `AgentSkills: Found ${slugs.length} ${source} skills in ${dir}`
+      );
+      for (const slug of slugs) {
+        if (!this.isSkillAllowed(slug)) {
+          this.runtime.logger.debug(
+            `AgentSkills: Skipping ${source} skill ${slug} (filtered by allow/denylist)`
+          );
+          continue;
+        }
+        const existing = this.loadedSkills.get(slug);
+        if (existing && SKILL_SOURCE_PRECEDENCE[existing.source] >= SKILL_SOURCE_PRECEDENCE[source]) {
+          this.runtime.logger.debug(
+            `AgentSkills: Skipping ${source} skill ${slug} (${existing.source} version takes precedence)`
+          );
+          continue;
+        }
+        const skill = await this.loadSkillFromStorageWithSource(
+          storage,
+          slug,
+          source,
+          dir
+        );
+        if (skill) {
+          if (existing) {
+            this.runtime.logger.info(
+              `AgentSkills: ${source} skill ${slug} overrides ${existing.source} version from ${existing.sourceDir}`
+            );
+            skill.overrides = `${existing.source}:${existing.sourceDir}`;
+          }
+          this.loadedSkills.set(slug, skill);
+        }
+      }
+    }
+  }
+  /**
+   * Load workspace skills (highest precedence).
+   */
+  async loadWorkspaceSkills() {
+    if (!this.workspaceStorage) return;
+    const slugs = await this.workspaceStorage.listSkills();
+    this.runtime.logger.debug(
+      `AgentSkills: Found ${slugs.length} workspace skills`
+    );
+    for (const slug of slugs) {
+      if (!this.isSkillAllowed(slug)) {
+        this.runtime.logger.debug(
+          `AgentSkills: Skipping workspace skill ${slug} (filtered by allow/denylist)`
+        );
+        continue;
+      }
+      const existing = this.loadedSkills.get(slug);
+      const skill = await this.loadSkillFromStorageWithSource(
+        this.workspaceStorage,
+        slug,
+        "workspace",
+        this.workspaceSkillsDir
+      );
+      if (skill) {
+        if (existing) {
+          this.runtime.logger.info(
+            `AgentSkills: Workspace skill ${slug} overrides ${existing.source} version`
+          );
+          skill.overrides = `${existing.source}:${existing.sourceDir}`;
+        }
+        this.loadedSkills.set(slug, skill);
+      }
+    }
+  }
+  /**
+   * Check if a skill is allowed based on allowlist/denylist.
+   */
+  isSkillAllowed(slug) {
+    if (this.denylist.has(slug)) {
+      return false;
+    }
+    if (this.allowlist !== null) {
+      return this.allowlist.has(slug);
+    }
+    return true;
+  }
+  /**
+   * Start the auto-refresh watcher.
+   */
+  startAutoRefresh() {
+    if (this.watcherCleanup) return;
+    const watchDirs = [];
+    if (this.workspaceSkillsDir) {
+      watchDirs.push(this.workspaceSkillsDir);
+    }
+    if (watchDirs.length === 0) {
+      this.runtime.logger.debug(
+        "AgentSkills: No directories to watch for auto-refresh"
+      );
+      return;
+    }
+    let lastCheck = Date.now();
+    const interval = setInterval(async () => {
+      try {
+        await this.refreshSkillsIfChanged(lastCheck);
+        lastCheck = Date.now();
+      } catch (error) {
+        this.runtime.logger.error(
+          `AgentSkills: Auto-refresh error: ${error}`
+        );
+      }
+    }, this.autoRefreshInterval);
+    this.watcherCleanup = () => {
+      clearInterval(interval);
+    };
+    this.runtime.logger.info(
+      `AgentSkills: Auto-refresh enabled (${this.autoRefreshInterval}ms interval)`
+    );
+  }
+  /**
+   * Refresh skills if any files have changed.
+   */
+  async refreshSkillsIfChanged(since) {
+    if (this.workspaceStorage) {
+      const slugs = await this.workspaceStorage.listSkills();
+      for (const slug of slugs) {
+        const existing = this.loadedSkills.get(slug);
+        if (!existing || existing.source !== "workspace") {
+          await this.loadSkill(slug, { validate: true });
+        }
+      }
+    }
+  }
+  /**
+   * Load all skills from bundled directories.
+   * These are read-only and cannot be modified or uninstalled.
+   */
+  async loadBundledSkills() {
+    for (const [bundledDir, storage] of this.bundledStorages) {
+      const slugs = await storage.listSkills();
+      this.runtime.logger.debug(
+        `AgentSkills: Found ${slugs.length} bundled skills in ${bundledDir}`
+      );
+      for (const slug of slugs) {
+        if (!this.isSkillAllowed(slug)) {
+          this.runtime.logger.debug(
+            `AgentSkills: Skipping bundled skill ${slug} (filtered by allow/denylist)`
+          );
+          continue;
+        }
+        const existing = this.loadedSkills.get(slug);
+        if (existing && SKILL_SOURCE_PRECEDENCE[existing.source] >= SKILL_SOURCE_PRECEDENCE.bundled) {
+          this.runtime.logger.debug(
+            `AgentSkills: Skipping bundled skill ${slug} (${existing.source} version takes precedence)`
+          );
+          continue;
+        }
+        const skill = await this.loadSkillFromStorageWithSource(
+          storage,
+          slug,
+          "bundled",
+          bundledDir
+        );
+        if (skill) {
+          if (existing) {
+            skill.overrides = `${existing.source}:${existing.sourceDir}`;
+          }
+          this.loadedSkills.set(slug, skill);
+        }
+      }
+    }
+  }
+  /**
+   * Internal helper to load a skill from any storage with source tracking.
+   */
+  async loadSkillFromStorageWithSource(storage, slug, source, sourceDir) {
+    const content = await storage.loadSkillContent(slug);
+    if (!content) {
+      this.runtime.logger.warn(`AgentSkills: No SKILL.md found for ${slug}`);
+      return null;
+    }
+    const { frontmatter, body } = parseFrontmatter(content);
+    if (!frontmatter) {
+      this.runtime.logger.warn(`AgentSkills: ${slug} has invalid frontmatter`);
+      return null;
+    }
+    const validation = validateFrontmatter(frontmatter, slug);
+    if (!validation.valid) {
+      this.runtime.logger.warn(
+        `AgentSkills: ${slug} validation failed: ${validation.errors.map((e) => e.message).join(", ")}`
+      );
+    }
+    for (const warning of validation.warnings) {
+      this.runtime.logger.debug(
+        `AgentSkills: ${slug} warning: ${warning.message}`
+      );
+    }
+    const scripts = await storage.listFiles(slug, "scripts");
+    const references = await storage.listFiles(slug, "references");
+    const assets = await storage.listFiles(slug, "assets");
+    const version = frontmatter.metadata?.version?.toString() || "local";
+    return {
+      slug,
+      name: frontmatter.name,
+      description: frontmatter.description,
+      version,
+      content,
+      frontmatter,
+      path: storage.getSkillPath(slug),
+      scripts,
+      references,
+      assets,
+      loadedAt: Date.now(),
+      source,
+      sourceDir,
+      precedence: SKILL_SOURCE_PRECEDENCE[source],
+      bundledDir: source === "bundled" ? sourceDir : void 0
+    };
+  }
+  // ============================================================
+  // PHASE 4.2: SKILL ELIGIBILITY CHECKING
+  // ============================================================
+  /**
+   * Check if a skill is eligible for use based on its requirements.
+   * Checks required binaries, environment variables, and config.
+   *
+   * @param slug - Skill slug or loaded skill
+   * @returns Eligibility status with reasons if ineligible
+   */
+  async checkSkillEligibility(slugOrSkill) {
+    const skill = typeof slugOrSkill === "string" ? this.loadedSkills.get(slugOrSkill) : slugOrSkill;
+    if (!skill) {
+      return {
+        slug: typeof slugOrSkill === "string" ? slugOrSkill : "unknown",
+        eligible: false,
+        reasons: [{
+          type: "config",
+          missing: "skill",
+          message: "Skill not found"
+        }],
+        checkedAt: Date.now()
+      };
+    }
+    const cached = this.eligibilityCache.get(skill.slug);
+    if (cached && Date.now() - cached.checkedAt < ELIGIBILITY_CACHE_TTL) {
+      return cached;
+    }
+    const reasons = [];
+    const metadata = skill.frontmatter.metadata?.otto;
+    const requires = metadata?.requires;
+    if (requires) {
+      if (requires.bins && requires.bins.length > 0) {
+        const missingBins = await this.checkMissingBinaries(requires.bins);
+        for (const bin of missingBins) {
+          reasons.push({
+            type: "bin",
+            missing: bin,
+            message: `Required binary '${bin}' not found in PATH`,
+            suggestion: this.getSuggestionForBinary(bin, metadata?.install)
+          });
+        }
+      }
+      if (requires.env && requires.env.length > 0) {
+        for (const envVar of requires.env) {
+          const value = process.env[envVar] || this.runtime.getSetting(envVar);
+          if (!value) {
+            reasons.push({
+              type: "env",
+              missing: envVar,
+              message: `Required environment variable '${envVar}' is not set`,
+              suggestion: `Set ${envVar} in your environment or agent settings`
+            });
+          }
+        }
+      }
+      if (requires.config && requires.config.length > 0) {
+        for (const configKey of requires.config) {
+          const value = this.runtime.getSetting(configKey);
+          if (!value) {
+            reasons.push({
+              type: "config",
+              missing: configKey,
+              message: `Required configuration '${configKey}' is not set`,
+              suggestion: `Set ${configKey} in your agent configuration`
+            });
+          }
+        }
+      }
+    }
+    const eligibility = {
+      slug: skill.slug,
+      eligible: reasons.length === 0,
+      reasons,
+      checkedAt: Date.now(),
+      installOptions: metadata?.install
+    };
+    this.eligibilityCache.set(skill.slug, eligibility);
+    return eligibility;
+  }
+  /**
+   * Check for missing binaries from a list.
+   */
+  async checkMissingBinaries(bins) {
+    const missing = [];
+    for (const bin of bins) {
+      const exists = await this.binaryExists(bin);
+      if (!exists) {
+        missing.push(bin);
+      }
+    }
+    return missing;
+  }
+  /**
+   * Check if a binary exists in PATH.
+   */
+  async binaryExists(name) {
+    try {
+      const { execSync } = await import("node:child_process");
+      const platform = process.platform;
+      const command = platform === "win32" ? `where ${name}` : `which ${name}`;
+      execSync(command, { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Get installation suggestion for a missing binary.
+   */
+  getSuggestionForBinary(bin, installOptions) {
+    if (!installOptions) return void 0;
+    const options = installOptions.filter((opt) => opt.bins?.includes(bin));
+    if (options.length === 0) return void 0;
+    const platform = process.platform;
+    const preferred = platform === "darwin" ? options.find((o) => o.kind === "brew") : options.find((o) => o.kind === "apt");
+    const option = preferred || options[0];
+    switch (option.kind) {
+      case "brew":
+        return `Install with Homebrew: brew install ${option.formula || option.package}`;
+      case "apt":
+        return `Install with apt: sudo apt-get install ${option.package}`;
+      case "node":
+        return `Install with npm/pnpm: npm install -g ${option.package}`;
+      case "pip":
+        return `Install with pip: pip install ${option.package}`;
+      case "cargo":
+        return `Install with cargo: cargo install ${option.package}`;
+      default:
+        return option.label;
+    }
+  }
+  /**
+   * Get eligibility status for all loaded skills.
+   */
+  async getAllSkillEligibility() {
+    const results = /* @__PURE__ */ new Map();
+    for (const [slug, skill] of this.loadedSkills) {
+      const eligibility = await this.checkSkillEligibility(skill);
+      results.set(slug, eligibility);
+    }
+    return results;
+  }
+  /**
+   * Get only eligible skills.
+   */
+  async getEligibleSkills() {
+    const eligible = [];
+    for (const skill of this.loadedSkills.values()) {
+      const eligibility = await this.checkSkillEligibility(skill);
+      if (eligibility.eligible) {
+        eligible.push(skill);
+      }
+    }
+    return eligible;
+  }
+  /**
+   * Get ineligible skills with their reasons.
+   */
+  async getIneligibleSkills() {
+    const ineligible = [];
+    for (const skill of this.loadedSkills.values()) {
+      const eligibility = await this.checkSkillEligibility(skill);
+      if (!eligibility.eligible) {
+        ineligible.push({ skill, eligibility });
+      }
+    }
+    return ineligible;
+  }
+  /**
+   * Clear the eligibility cache.
+   */
+  clearEligibilityCache() {
+    this.eligibilityCache.clear();
+  }
+  // ============================================================
+  // PHASE 4.4: SKILL CONFIGURATION
+  // ============================================================
+  /**
+   * Set environment variables for a specific skill.
+   * These will be injected when the skill is used.
+   *
+   * @param skillName - Skill slug
+   * @param env - Environment variables to set
+   */
+  setSkillEnv(skillName, env) {
+    this.skillEnvOverrides.set(skillName, {
+      ...this.skillEnvOverrides.get(skillName),
+      ...env
+    });
+    this.runtime.logger.debug(
+      `AgentSkills: Set env overrides for skill ${skillName}`
+    );
+  }
+  /**
+   * Get environment variables configured for a skill.
+   *
+   * @param skillName - Skill slug
+   * @returns Merged environment variables
+   */
+  getSkillEnv(skillName) {
+    const skillEntry = this.skillEntries.get(skillName);
+    const overrides = this.skillEnvOverrides.get(skillName);
+    return {
+      ...skillEntry?.env,
+      ...overrides
+    };
+  }
+  /**
+   * Set an API key for a specific skill.
+   *
+   * @param skillName - Skill slug
+   * @param apiKey - API key value
+   */
+  setSkillApiKey(skillName, apiKey) {
+    this.skillApiKeys.set(skillName, apiKey);
+    this.runtime.logger.debug(
+      `AgentSkills: Set API key for skill ${skillName}`
+    );
+  }
+  /**
+   * Get the API key for a skill.
+   *
+   * @param skillName - Skill slug
+   * @returns API key if set
+   */
+  getSkillApiKey(skillName) {
+    const override = this.skillApiKeys.get(skillName);
+    if (override) return override;
+    const entry = this.skillEntries.get(skillName);
+    return entry?.apiKey;
+  }
+  /**
+   * Update the allowlist of skills.
+   *
+   * @param slugs - Skill slugs to allow (null to disable allowlist)
+   */
+  setAllowlist(slugs) {
+    this.allowlist = slugs ? new Set(slugs) : null;
+    this.runtime.logger.info(
+      `AgentSkills: Updated allowlist (${slugs?.length ?? "disabled"} skills)`
+    );
+  }
+  /**
+   * Update the denylist of skills.
+   *
+   * @param slugs - Skill slugs to deny
+   */
+  setDenylist(slugs) {
+    this.denylist = new Set(slugs);
+    this.runtime.logger.info(
+      `AgentSkills: Updated denylist (${slugs.length} skills)`
+    );
+  }
+  /**
+   * Get the current allowlist.
+   */
+  getAllowlist() {
+    return this.allowlist ? Array.from(this.allowlist) : null;
+  }
+  /**
+   * Get the current denylist.
+   */
+  getDenylist() {
+    return Array.from(this.denylist);
+  }
+  /**
+   * Set configuration for a skill.
+   *
+   * @param skillName - Skill slug
+   * @param config - Configuration entry
+   */
+  setSkillConfig(skillName, config) {
+    this.skillEntries.set(skillName, {
+      ...this.skillEntries.get(skillName),
+      ...config
+    });
+    this.runtime.logger.debug(
+      `AgentSkills: Updated config for skill ${skillName}`
+    );
+  }
+  /**
+   * Get configuration for a skill.
+   *
+   * @param skillName - Skill slug
+   * @returns Skill configuration or undefined
+   */
+  getSkillConfig(skillName) {
+    return this.skillEntries.get(skillName);
+  }
+  /**
+   * Check if a skill is enabled.
+   *
+   * @param skillName - Skill slug
+   * @returns True if enabled (default: true)
+   */
+  isSkillEnabled(skillName) {
+    const entry = this.skillEntries.get(skillName);
+    return entry?.enabled !== false;
+  }
+  /**
+   * Enable or disable a skill.
+   *
+   * @param skillName - Skill slug
+   * @param enabled - Whether to enable the skill
+   */
+  setSkillEnabled(skillName, enabled) {
+    this.setSkillConfig(skillName, { enabled });
+  }
+  /**
+   * Add a plugin skills directory at runtime.
+   *
+   * @param dir - Directory path
+   */
+  async addPluginSkillsDir(dir) {
+    if (this.pluginStorages.has(dir)) return;
+    try {
+      const storage = new FileSystemSkillStore(dir);
+      await storage.initialize();
+      this.pluginStorages.set(dir, storage);
+      this.pluginSkillsDirs.push(dir);
+      await this.loadSkillsFromSource(
+        /* @__PURE__ */ new Map([[dir, storage]]),
+        "plugin"
+      );
+      this.runtime.logger.info(
+        `AgentSkills: Added plugin skills directory: ${dir}`
+      );
+    } catch (error) {
+      this.runtime.logger.warn(
+        `AgentSkills: Failed to add plugin skills directory: ${dir}`
+      );
+    }
+  }
+  // ============================================================
+  // STORAGE ACCESS
+  // ============================================================
+  /**
+   * Get the storage backend.
+   */
+  getStorage() {
+    return this.storage;
+  }
+  /**
+   * Get storage type.
+   */
+  getStorageType() {
+    return this.storage.type;
+  }
+  /**
+   * Check if running in memory mode.
+   */
+  isMemoryMode() {
+    return this.storage.type === "memory";
+  }
+  // ============================================================
+  // SKILL DISCOVERY (Progressive Disclosure Level 1)
+  // ============================================================
+  /**
+   * Get skill metadata for all loaded skills.
+   * Returns minimal information suitable for system prompts.
+   */
+  getSkillsMetadata() {
+    return Array.from(this.loadedSkills.values()).map((skill) => ({
+      name: skill.name,
+      description: skill.description,
+      location: `${skill.path}/SKILL.md`
+    }));
+  }
+  /**
+   * Generate XML for available skills (for system prompts).
+   */
+  generateSkillsPromptXml(options = {}) {
+    const metadata = this.getSkillsMetadata();
+    const limited = options.maxSkills ? metadata.slice(0, options.maxSkills) : metadata;
+    return generateSkillsXml(limited, {
+      includeLocation: options.includeLocation ?? true
+    });
+  }
+  // ============================================================
+  // SKILL LOADING (Progressive Disclosure Level 2)
+  // ============================================================
+  /**
+   * Load all managed/installed skills from the main storage.
+   * Respects skill source precedence ordering.
+   */
+  async loadInstalledSkills() {
+    const slugs = await this.storage.listSkills();
+    for (const slug of slugs) {
+      if (!this.isSkillAllowed(slug)) {
+        this.runtime.logger.debug(
+          `AgentSkills: Skipping managed skill ${slug} (filtered by allow/denylist)`
+        );
+        continue;
+      }
+      const existing = this.loadedSkills.get(slug);
+      if (existing && SKILL_SOURCE_PRECEDENCE[existing.source] >= SKILL_SOURCE_PRECEDENCE.managed) {
+        this.runtime.logger.debug(
+          `AgentSkills: Skipping managed skill ${slug} (${existing.source} version takes precedence)`
+        );
+        continue;
+      }
+      const skillsDir = this.storage.type === "filesystem" ? this.storage.basePath : "./skills";
+      const skill = await this.loadSkillFromStorageWithSource(
+        this.storage,
+        slug,
+        "managed",
+        skillsDir
+      );
+      if (skill) {
+        if (existing) {
+          this.runtime.logger.info(
+            `AgentSkills: Managed skill ${slug} overrides ${existing.source} version`
+          );
+          skill.overrides = `${existing.source}:${existing.sourceDir}`;
+        }
+        this.loadedSkills.set(slug, skill);
+      }
+    }
+  }
+  /**
+   * Load a single skill by slug or path.
+   * Checks all storage sources in precedence order.
+   */
+  async loadSkill(slugOrPath, options = {}) {
+    let slug;
+    if (slugOrPath.includes("/")) {
+      const parts = slugOrPath.split("/").filter(Boolean);
+      slug = parts[parts.length - 1];
+    } else {
+      slug = sanitizeSlug(slugOrPath);
+    }
+    if (!this.isSkillAllowed(slug)) {
+      this.runtime.logger.debug(
+        `AgentSkills: Skill ${slug} not allowed by allow/denylist`
+      );
+      return null;
+    }
+    const existing = this.loadedSkills.get(slug);
+    if (existing) {
+      return existing;
+    }
+    if (this.workspaceStorage && await this.workspaceStorage.hasSkill(slug)) {
+      const skill = await this.loadSkillFromStorageWithSource(
+        this.workspaceStorage,
+        slug,
+        "workspace",
+        this.workspaceSkillsDir
+      );
+      if (skill) {
+        this.loadedSkills.set(slug, skill);
+        return skill;
+      }
+    }
+    if (await this.storage.hasSkill(slug)) {
+      const skillsDir = this.storage.type === "filesystem" ? this.storage.basePath : "./skills";
+      const skill = await this.loadSkillFromStorageWithSource(
+        this.storage,
+        slug,
+        "managed",
+        skillsDir
+      );
+      if (skill) {
+        this.loadedSkills.set(slug, skill);
+        return skill;
+      }
+    }
+    for (const [bundledDir, storage] of this.bundledStorages) {
+      if (await storage.hasSkill(slug)) {
+        const skill = await this.loadSkillFromStorageWithSource(
+          storage,
+          slug,
+          "bundled",
+          bundledDir
+        );
+        if (skill) {
+          this.loadedSkills.set(slug, skill);
+          return skill;
+        }
+      }
+    }
+    for (const [pluginDir, storage] of this.pluginStorages) {
+      if (await storage.hasSkill(slug)) {
+        const skill = await this.loadSkillFromStorageWithSource(
+          storage,
+          slug,
+          "plugin",
+          pluginDir
+        );
+        if (skill) {
+          this.loadedSkills.set(slug, skill);
+          return skill;
+        }
+      }
+    }
+    for (const [extraDir, storage] of this.extraStorages) {
+      if (await storage.hasSkill(slug)) {
+        const skill = await this.loadSkillFromStorageWithSource(
+          storage,
+          slug,
+          "extra",
+          extraDir
+        );
+        if (skill) {
+          this.loadedSkills.set(slug, skill);
+          return skill;
+        }
+      }
+    }
+    return null;
+  }
+  /**
+   * Load a skill directly from content (memory mode convenience).
+   */
+  async loadSkillFromContent(slug, skillMdContent, additionalFiles) {
+    if (!(this.storage instanceof MemorySkillStore)) {
+      throw new Error("loadSkillFromContent requires memory storage mode");
+    }
+    await this.storage.loadFromContent(
+      slug,
+      skillMdContent,
+      additionalFiles
+    );
+    return this.loadSkill(slug);
+  }
+  /**
+   * Get skill instructions (body without frontmatter).
+   */
+  getSkillInstructions(slug) {
+    try {
+      const skill = this.loadedSkills.get(sanitizeSlug(slug));
+      if (!skill) return null;
+      const body = extractBody(skill.content);
+      return {
+        slug: skill.slug,
+        body,
+        estimatedTokens: estimateTokens(body)
+      };
+    } catch {
+      return null;
+    }
+  }
+  // ============================================================
+  // RESOURCE ACCESS (Progressive Disclosure Level 3)
+  // ============================================================
+  /**
+   * Get the appropriate storage for a skill based on its source.
+   */
+  getStorageForSkill(skill) {
+    switch (skill.source) {
+      case "workspace":
+        if (this.workspaceStorage) return this.workspaceStorage;
+        break;
+      case "bundled":
+        if (skill.bundledDir) {
+          const bundledStorage = this.bundledStorages.get(skill.bundledDir);
+          if (bundledStorage) return bundledStorage;
+        }
+        break;
+      case "plugin":
+        if (skill.sourceDir) {
+          const pluginStorage = this.pluginStorages.get(skill.sourceDir);
+          if (pluginStorage) return pluginStorage;
+        }
+        break;
+      case "extra":
+        if (skill.sourceDir) {
+          const extraStorage = this.extraStorages.get(skill.sourceDir);
+          if (extraStorage) return extraStorage;
+        }
+        break;
+      case "managed":
+      default:
+        return this.storage;
+    }
+    return this.storage;
+  }
+  /**
+   * Read a reference file from a skill.
+   * Injects per-skill environment variables if configured.
+   */
+  async readReference(slug, filename) {
+    const safeSlug = sanitizeSlug(slug);
+    const skill = this.loadedSkills.get(safeSlug);
+    if (!skill) return null;
+    const safeName = filename.split("/").pop() || filename;
+    const storage = this.getStorageForSkill(skill);
+    const content = await storage.loadFile(safeSlug, `references/${safeName}`);
+    return typeof content === "string" ? content : null;
+  }
+  /**
+   * Get the path to a script file.
+   * Returns the actual filesystem path for all skill sources.
+   */
+  getScriptPath(slug, filename) {
+    const skill = this.loadedSkills.get(sanitizeSlug(slug));
+    if (!skill) return null;
+    const safeName = filename.split("/").pop() || filename;
+    if (!skill.scripts.includes(safeName)) return null;
+    return `${skill.path}/scripts/${safeName}`;
+  }
+  /**
+   * Read a script file content.
+   */
+  async readScript(slug, filename) {
+    const safeSlug = sanitizeSlug(slug);
+    const skill = this.loadedSkills.get(safeSlug);
+    if (!skill) return null;
+    const safeName = filename.split("/").pop() || filename;
+    const storage = this.getStorageForSkill(skill);
+    const content = await storage.loadFile(safeSlug, `scripts/${safeName}`);
+    return typeof content === "string" ? content : null;
+  }
+  /**
+   * Get the path to an asset file.
+   */
+  getAssetPath(slug, filename) {
+    const skill = this.loadedSkills.get(sanitizeSlug(slug));
+    if (!skill) return null;
+    const safeName = filename.split("/").pop() || filename;
+    if (!skill.assets.includes(safeName)) return null;
+    return `${skill.path}/assets/${safeName}`;
+  }
+  /**
+   * Read an asset file content.
+   */
+  async readAsset(slug, filename) {
+    const safeSlug = sanitizeSlug(slug);
+    const skill = this.loadedSkills.get(safeSlug);
+    if (!skill) return null;
+    const safeName = filename.split("/").pop() || filename;
+    const storage = this.getStorageForSkill(skill);
+    const content = await storage.loadFile(safeSlug, `assets/${safeName}`);
+    if (content instanceof Uint8Array) return content;
+    if (typeof content === "string") return new TextEncoder().encode(content);
+    return null;
+  }
+  /**
+   * Get the environment to use when executing a skill script.
+   * Merges system env with skill-specific overrides.
+   */
+  getSkillExecutionEnv(slug) {
+    const skillEnv = this.getSkillEnv(slug);
+    const apiKey = this.getSkillApiKey(slug);
+    const env = {
+      ...process.env,
+      ...skillEnv
+    };
+    if (apiKey) {
+      env.SKILL_API_KEY = apiKey;
+      env[`${slug.toUpperCase().replace(/-/g, "_")}_API_KEY`] = apiKey;
+    }
+    return env;
+  }
+  // ============================================================
+  // SKILL RETRIEVAL
+  // ============================================================
+  /**
+   * Get all loaded skills.
+   */
+  getLoadedSkills() {
+    return Array.from(this.loadedSkills.values());
+  }
+  /**
+   * Get only bundled skills.
+   */
+  getBundledSkills() {
+    return Array.from(this.loadedSkills.values()).filter(
+      (s) => s.source === "bundled"
+    );
+  }
+  /**
+   * Get only managed/installed skills.
+   */
+  getManagedSkills() {
+    return Array.from(this.loadedSkills.values()).filter(
+      (s) => s.source === "managed"
+    );
+  }
+  /**
+   * Get only workspace skills.
+   */
+  getWorkspaceSkills() {
+    return Array.from(this.loadedSkills.values()).filter(
+      (s) => s.source === "workspace"
+    );
+  }
+  /**
+   * Get only plugin-contributed skills.
+   */
+  getPluginSkills() {
+    return Array.from(this.loadedSkills.values()).filter(
+      (s) => s.source === "plugin"
+    );
+  }
+  /**
+   * Get skills by source type.
+   */
+  getSkillsBySource(source) {
+    return Array.from(this.loadedSkills.values()).filter(
+      (s) => s.source === source
+    );
+  }
+  /**
+   * Get a specific loaded skill.
+   */
+  getLoadedSkill(slug) {
+    try {
+      return this.loadedSkills.get(sanitizeSlug(slug));
+    } catch {
+      return void 0;
+    }
+  }
+  /**
+   * Check if a skill is loaded.
+   */
+  isLoaded(slug) {
+    try {
+      return this.loadedSkills.has(sanitizeSlug(slug));
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Check if a skill is bundled (read-only).
+   */
+  isBundled(slug) {
+    const skill = this.loadedSkills.get(slug);
+    return skill?.source === "bundled";
+  }
+  /**
+   * Check if a skill is installed (in managed storage, not bundled).
+   */
+  async isInstalled(slug) {
+    try {
+      return await this.storage.hasSkill(sanitizeSlug(slug));
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Check if a skill exists (either bundled or installed).
+   */
+  async exists(slug) {
+    const safeSlug = sanitizeSlug(slug);
+    for (const storage of this.bundledStorages.values()) {
+      if (await storage.hasSkill(safeSlug)) return true;
+    }
+    return this.storage.hasSkill(safeSlug);
+  }
+  /**
+   * Unload a skill from memory (keeps in storage).
+   */
+  unloadSkill(slug) {
+    try {
+      return this.loadedSkills.delete(sanitizeSlug(slug));
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Get the list of bundled skills directories.
+   */
+  getBundledSkillsDirs() {
+    return [...this.bundledSkillsDirs];
+  }
+  // ============================================================
+  // REGISTRY OPERATIONS (ClawHub Integration)
+  // ============================================================
+  /**
+   * Get the full skill catalog from ClawHub.
+   */
+  async getCatalog(options = {}) {
+    const ttl = options.notOlderThan ?? CACHE_TTL.CATALOG;
+    if (!options.forceRefresh && this.catalogCache) {
+      const age = Date.now() - this.catalogCache.cachedAt;
+      if (age < ttl) {
+        return this.catalogCache.data;
+      }
+    }
+    try {
+      const entries = [];
+      let cursor;
+      do {
+        const url = `${this.apiBase}/api/v1/skills?limit=100${cursor ? `&cursor=${cursor}` : ""}`;
+        const response = await fetch(url, {
+          headers: { Accept: "application/json" }
+        });
+        if (!response.ok) {
+          throw new Error(`Catalog fetch failed: ${response.status}`);
+        }
+        const data = await response.json();
+        entries.push(...data.items);
+        cursor = data.nextCursor;
+      } while (cursor);
+      this.catalogCache = { data: entries, cachedAt: Date.now() };
+      if (this.storage.type === "filesystem") {
+        await this.saveCatalogToDisk();
+      }
+      return entries;
+    } catch (error) {
+      this.runtime.logger.error(`AgentSkills: Catalog fetch error: ${error}`);
+      return this.catalogCache?.data || [];
+    }
+  }
+  /**
+   * Search ClawHub for skills.
+   */
+  async search(query, limit = 10, options = {}) {
+    const cacheKey = `${query}:${limit}`;
+    const ttl = options.notOlderThan ?? CACHE_TTL.SEARCH;
+    if (!options.forceRefresh) {
+      const cached = this.searchCache.get(cacheKey);
+      if (cached && Date.now() - cached.cachedAt < ttl) {
+        return cached.data;
+      }
+    }
+    try {
+      const url = `${this.apiBase}/api/v1/search?q=${encodeURIComponent(query)}&limit=${limit}`;
+      const response = await fetch(url, {
+        headers: { Accept: "application/json" }
+      });
+      if (!response.ok) {
+        throw new Error(`Search failed: ${response.status}`);
+      }
+      const data = await response.json();
+      const results = data.results || [];
+      this.searchCache.set(cacheKey, { data: results, cachedAt: Date.now() });
+      return results;
+    } catch (error) {
+      this.runtime.logger.error(`AgentSkills: Search error: ${error}`);
+      return this.searchCache.get(cacheKey)?.data || [];
+    }
+  }
+  /**
+   * Get skill details from ClawHub.
+   */
+  async getSkillDetails(slug, options = {}) {
+    const safeSlug = sanitizeSlug(slug);
+    const ttl = options.notOlderThan ?? CACHE_TTL.SKILL_DETAILS;
+    if (!options.forceRefresh) {
+      const cached = this.detailsCache.get(safeSlug);
+      if (cached && Date.now() - cached.cachedAt < ttl) {
+        return cached.data;
+      }
+    }
+    try {
+      const url = `${this.apiBase}/api/v1/skills/${safeSlug}`;
+      const response = await fetch(url, {
+        headers: { Accept: "application/json" }
+      });
+      if (!response.ok) {
+        if (response.status === 404) return null;
+        throw new Error(`Details fetch failed: ${response.status}`);
+      }
+      const details = await response.json();
+      this.detailsCache.set(safeSlug, { data: details, cachedAt: Date.now() });
+      return details;
+    } catch (error) {
+      this.runtime.logger.error(`AgentSkills: Details fetch error: ${error}`);
+      return this.detailsCache.get(safeSlug)?.data || null;
+    }
+  }
+  // ============================================================
+  // INSTALLATION
+  // ============================================================
+  /**
+   * Install a skill from ClawHub.
+   *
+   * In memory mode: Downloads and loads skill into memory.
+   * In filesystem mode: Downloads, extracts to disk, and loads.
+   */
+  async install(slug, options = {}) {
+    try {
+      const safeSlug = sanitizeSlug(slug);
+      const version = options.version || "latest";
+      if (!options.force && await this.isInstalled(safeSlug)) {
+        this.runtime.logger.info(`AgentSkills: ${safeSlug} already installed`);
+        return true;
+      }
+      this.runtime.logger.info(
+        `AgentSkills: Installing ${safeSlug}@${version}...`
+      );
+      const details = await this.getSkillDetails(safeSlug);
+      if (!details) {
+        throw new Error(`Skill "${safeSlug}" not found`);
+      }
+      const resolvedVersion = version === "latest" ? details.latestVersion.version : version;
+      const downloadUrl = `${this.apiBase}/api/v1/download?slug=${safeSlug}&version=${resolvedVersion}`;
+      const response = await fetch(downloadUrl);
+      if (!response.ok) {
+        throw new Error(`Download failed: ${response.status}`);
+      }
+      const zipBuffer = await response.arrayBuffer();
+      if (zipBuffer.byteLength > MAX_PACKAGE_SIZE) {
+        throw new Error(
+          `Package too large (max ${MAX_PACKAGE_SIZE / 1024 / 1024}MB)`
+        );
+      }
+      if (this.storage instanceof MemorySkillStore) {
+        await this.storage.loadFromZip(
+          safeSlug,
+          new Uint8Array(zipBuffer)
+        );
+      } else if (this.storage instanceof FileSystemSkillStore) {
+        await this.storage.saveFromZip(
+          safeSlug,
+          new Uint8Array(zipBuffer)
+        );
+        await this.updateLockfile(safeSlug, resolvedVersion);
+      }
+      await this.loadSkill(safeSlug);
+      this.runtime.logger.info(
+        `AgentSkills: Installed ${safeSlug}@${resolvedVersion}`
+      );
+      return true;
+    } catch (error) {
+      this.runtime.logger.error(`AgentSkills: Install error: ${error}`);
+      return false;
+    }
+  }
+  /**
+   * Install a skill from a GitHub repository.
+   *
+   * Supports both full repo paths and shorthand:
+   * - "owner/repo" - Uses repo root
+   * - "owner/repo/path/to/skill" - Uses specific subdirectory
+   * - "https://github.com/owner/repo" - Full URL
+   *
+   * Downloads SKILL.md and any additional files in the skill directory.
+   */
+  async installFromGitHub(repo, options = {}) {
+    try {
+      let owner;
+      let repoName;
+      let skillPath = options.path || "";
+      const branch = options.branch || "main";
+      if (repo.startsWith("http")) {
+        const url = new URL(repo);
+        const parts = url.pathname.split("/").filter(Boolean);
+        if (parts.length < 2) {
+          throw new Error("Invalid GitHub URL");
+        }
+        owner = parts[0];
+        repoName = parts[1];
+        if (parts.length > 2) {
+          const treeIdx = parts.indexOf("tree");
+          if (treeIdx >= 0 && parts.length > treeIdx + 2) {
+            skillPath = parts.slice(treeIdx + 2).join("/");
+          } else if (parts.length > 2) {
+            skillPath = parts.slice(2).join("/");
+          }
+        }
+      } else {
+        const parts = repo.split("/");
+        if (parts.length < 2) {
+          throw new Error(
+            "Invalid repo format. Use owner/repo or owner/repo/path"
+          );
+        }
+        owner = parts[0];
+        repoName = parts[1];
+        if (parts.length > 2) {
+          skillPath = parts.slice(2).join("/");
+        }
+      }
+      const slug = skillPath ? skillPath.split("/").pop() || repoName : repoName;
+      const safeSlug = sanitizeSlug(slug);
+      if (!options.force && await this.isInstalled(safeSlug)) {
+        this.runtime.logger.info(
+          `AgentSkills: ${safeSlug} already installed from GitHub`
+        );
+        return true;
+      }
+      this.runtime.logger.info(
+        `AgentSkills: Installing from GitHub ${owner}/${repoName}/${skillPath}...`
+      );
+      const basePath = skillPath ? `${skillPath}/` : "";
+      const rawBase = `https://raw.githubusercontent.com/${owner}/${repoName}/${branch}/${basePath}`;
+      const skillMdUrl = `${rawBase}SKILL.md`;
+      const response = await fetch(skillMdUrl);
+      if (!response.ok) {
+        throw new Error(
+          `Failed to fetch SKILL.md: ${response.status} from ${skillMdUrl}`
+        );
+      }
+      const skillMdContent = await response.text();
+      const files = [
+        { name: "SKILL.md", content: skillMdContent }
+      ];
+      try {
+        const readmeUrl = `${rawBase}README.md`;
+        const readmeResponse = await fetch(readmeUrl);
+        if (readmeResponse.ok) {
+          const readmeContent = await readmeResponse.text();
+          files.push({ name: "README.md", content: readmeContent });
+        }
+      } catch {
+      }
+      if (this.storage instanceof MemorySkillStore) {
+        await this.storage.savePackage({
+          slug: safeSlug,
+          files,
+          loadedAt: Date.now()
+        });
+      } else if (this.storage instanceof FileSystemSkillStore) {
+        const fs = await import("fs/promises");
+        const path2 = await import("path");
+        const skillDir = path2.join(
+          this.storage.basePath,
+          safeSlug
+        );
+        await fs.mkdir(skillDir, { recursive: true });
+        for (const file of files) {
+          await fs.writeFile(path2.join(skillDir, file.name), file.content);
+        }
+      }
+      await this.loadSkill(safeSlug);
+      this.runtime.logger.info(
+        `AgentSkills: Installed ${safeSlug} from GitHub`
+      );
+      return true;
+    } catch (error) {
+      this.runtime.logger.error(`AgentSkills: GitHub install error: ${error}`);
+      return false;
+    }
+  }
+  /**
+   * Install a skill from a direct URL to a SKILL.md file or zip package.
+   */
+  async installFromUrl(url, options = {}) {
+    try {
+      const response = await fetch(url);
+      if (!response.ok) {
+        throw new Error(`Failed to fetch: ${response.status}`);
+      }
+      const contentType = response.headers.get("content-type") || "";
+      const urlPath = new URL(url).pathname;
+      const derivedSlug = options.slug || urlPath.split("/").filter(Boolean).pop()?.replace(/\.(md|zip)$/i, "") || "skill";
+      const safeSlug = sanitizeSlug(derivedSlug);
+      if (contentType.includes("application/zip") || url.endsWith(".zip")) {
+        const zipBuffer = await response.arrayBuffer();
+        if (zipBuffer.byteLength > MAX_PACKAGE_SIZE) {
+          throw new Error(
+            `Package too large (max ${MAX_PACKAGE_SIZE / 1024 / 1024}MB)`
+          );
+        }
+        if (this.storage instanceof MemorySkillStore) {
+          await this.storage.loadFromZip(
+            safeSlug,
+            new Uint8Array(zipBuffer)
+          );
+        } else if (this.storage instanceof FileSystemSkillStore) {
+          await this.storage.saveFromZip(
+            safeSlug,
+            new Uint8Array(zipBuffer)
+          );
+        }
+      } else {
+        const content = await response.text();
+        const files = [
+          { name: "SKILL.md", content }
+        ];
+        if (this.storage instanceof MemorySkillStore) {
+          await this.storage.savePackage({
+            slug: safeSlug,
+            files,
+            loadedAt: Date.now()
+          });
+        } else if (this.storage instanceof FileSystemSkillStore) {
+          const fs = await import("fs/promises");
+          const path2 = await import("path");
+          const skillDir = path2.join(
+            this.storage.basePath,
+            safeSlug
+          );
+          await fs.mkdir(skillDir, { recursive: true });
+          for (const file of files) {
+            await fs.writeFile(path2.join(skillDir, file.name), file.content);
+          }
+        }
+      }
+      await this.loadSkill(safeSlug);
+      this.runtime.logger.info(`AgentSkills: Installed ${safeSlug} from URL`);
+      return true;
+    } catch (error) {
+      this.runtime.logger.error(`AgentSkills: URL install error: ${error}`);
+      return false;
+    }
+  }
+  /**
+   * Uninstall a skill (remove from storage and memory).
+   * Cannot uninstall bundled skills - they are read-only.
+   */
+  async uninstall(slug) {
+    const safeSlug = sanitizeSlug(slug);
+    const existing = this.loadedSkills.get(safeSlug);
+    if (existing?.source === "bundled") {
+      this.runtime.logger.warn(
+        `AgentSkills: Cannot uninstall bundled skill ${safeSlug}`
+      );
+      return false;
+    }
+    this.loadedSkills.delete(safeSlug);
+    const deleted = await this.storage.deleteSkill(safeSlug);
+    if (deleted) {
+      this.runtime.logger.info(`AgentSkills: Uninstalled ${safeSlug}`);
+    }
+    return deleted;
+  }
+  // ============================================================
+  // SYNC OPERATIONS
+  // ============================================================
+  /**
+   * Sync the skill catalog from ClawHub.
+   */
+  async syncCatalog() {
+    const oldCount = this.catalogCache?.data.length || 0;
+    await this.getCatalog({ forceRefresh: true });
+    const newCount = this.catalogCache?.data.length || 0;
+    return {
+      added: Math.max(0, newCount - oldCount),
+      updated: newCount
+    };
+  }
+  /**
+   * Get catalog stats for logging.
+   */
+  getCatalogStats() {
+    const categories = /* @__PURE__ */ new Set();
+    if (this.catalogCache?.data) {
+      for (const skill of this.catalogCache.data) {
+        if (skill.tags) {
+          for (const tag of Object.keys(skill.tags)) {
+            if (tag !== "latest") categories.add(tag);
+          }
+        }
+      }
+    }
+    return {
+      total: this.catalogCache?.data.length || 0,
+      installed: this.loadedSkills.size,
+      // For backward compat
+      loaded: this.loadedSkills.size,
+      cachedAt: this.catalogCache?.cachedAt || null,
+      storageType: this.storage.type,
+      categories: Array.from(categories).slice(0, 20)
+    };
+  }
+  // ============================================================
+  // PRIVATE HELPERS
+  // ============================================================
+  async getLockfileVersion(slug) {
+    if (!this.lockfilePath || this.storage.type !== "filesystem") return null;
+    try {
+      const fs = await import("fs");
+      if (!fs.existsSync(this.lockfilePath)) return null;
+      const lockfile = JSON.parse(fs.readFileSync(this.lockfilePath, "utf-8"));
+      return lockfile[slug]?.version || null;
+    } catch {
+      return null;
+    }
+  }
+  async updateLockfile(slug, version) {
+    if (!this.lockfilePath || this.storage.type !== "filesystem") return;
+    try {
+      const fs = await import("fs");
+      const path2 = await import("path");
+      const cacheDir = path2.dirname(this.lockfilePath);
+      if (!fs.existsSync(cacheDir)) {
+        fs.mkdirSync(cacheDir, { recursive: true });
+      }
+      let lockfile = {};
+      if (fs.existsSync(this.lockfilePath)) {
+        try {
+          lockfile = JSON.parse(fs.readFileSync(this.lockfilePath, "utf-8"));
+        } catch {
+        }
+      }
+      lockfile[slug] = { version, installedAt: (/* @__PURE__ */ new Date()).toISOString() };
+      fs.writeFileSync(this.lockfilePath, JSON.stringify(lockfile, null, 2));
+    } catch {
+    }
+  }
+  async loadCatalogFromDisk() {
+    if (!this.catalogCachePath || this.storage.type !== "filesystem") return;
+    try {
+      const fs = await import("fs");
+      if (!fs.existsSync(this.catalogCachePath)) return;
+      const cached = JSON.parse(
+        fs.readFileSync(this.catalogCachePath, "utf-8")
+      );
+      if (cached.data && cached.cachedAt) {
+        this.catalogCache = cached;
+        this.runtime.logger.debug(
+          `AgentSkills: Loaded catalog cache (${cached.data.length} skills)`
+        );
+      }
+    } catch {
+    }
+  }
+  async saveCatalogToDisk() {
+    if (!this.catalogCache || !this.catalogCachePath || this.storage.type !== "filesystem")
+      return;
+    try {
+      const fs = await import("fs");
+      const path2 = await import("path");
+      const cacheDir = path2.dirname(this.catalogCachePath);
+      if (!fs.existsSync(cacheDir)) {
+        fs.mkdirSync(cacheDir, { recursive: true });
+      }
+      fs.writeFileSync(
+        this.catalogCachePath,
+        JSON.stringify(this.catalogCache, null, 2)
+      );
+    } catch {
+    }
+  }
+};
+
+// src/actions/search-skills.ts
+var searchSkillsAction = {
+  name: "SEARCH_SKILLS",
+  similes: ["BROWSE_SKILLS", "LIST_SKILLS", "FIND_SKILLS"],
+  description: "Search the skill registry for available skills by keyword or category.",
+  validate: async (runtime, _message) => {
+    const service = runtime.getService(
+      "AGENT_SKILLS_SERVICE"
+    );
+    return !!service;
+  },
+  handler: async (runtime, message, _state, _options, callback) => {
+    try {
+      const service = runtime.getService(
+        "AGENT_SKILLS_SERVICE"
+      );
+      if (!service) {
+        throw new Error("AgentSkillsService not available");
+      }
+      const query = message.content?.text || "";
+      const results = await service.search(query, 10);
+      if (results.length === 0) {
+        const text2 = `No skills found matching "${query}".`;
+        if (callback) await callback({ text: text2 });
+        return { success: true, text: text2, data: { results: [] } };
+      }
+      const skillList = results.map(
+        (r, i) => `${i + 1}. **${r.displayName}** (\`${r.slug}\`)
+   ${r.summary}`
+      ).join("\n\n");
+      const text = `## Skills matching "${query}"
+
+${skillList}
+
+Use GET_SKILL_GUIDANCE with a skill name to get detailed instructions.`;
+      if (callback) await callback({ text });
+      return {
+        success: true,
+        text,
+        data: { results }
+      };
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      if (callback) {
+        await callback({ text: `Error searching skills: ${errorMsg}` });
+      }
+      return {
+        success: false,
+        error: error instanceof Error ? error : new Error(errorMsg)
+      };
+    }
+  },
+  examples: [
+    [
+      {
+        name: "{{userName}}",
+        content: { text: "Search for skills about data analysis" }
+      },
+      {
+        name: "{{agentName}}",
+        content: {
+          text: '## Skills matching "data analysis"\n\n1. **Data Analysis** (`data-analysis`)\n   Analyze datasets and generate insights...',
+          actions: ["SEARCH_SKILLS"]
+        }
+      }
+    ]
+  ]
+};
+
+// src/actions/get-skill-details.ts
+var getSkillDetailsAction = {
+  name: "GET_SKILL_DETAILS",
+  similes: ["SKILL_INFO", "SKILL_DETAILS"],
+  description: "Get detailed information about a specific skill including version, owner, and stats.",
+  validate: async (runtime, _message) => {
+    const service = runtime.getService(
+      "AGENT_SKILLS_SERVICE"
+    );
+    return !!service;
+  },
+  handler: async (runtime, message, _state, options, callback) => {
+    try {
+      const service = runtime.getService(
+        "AGENT_SKILLS_SERVICE"
+      );
+      if (!service) {
+        throw new Error("AgentSkillsService not available");
+      }
+      const opts = options;
+      const slug = opts?.slug || extractSlugFromText(message.content?.text || "");
+      if (!slug) {
+        return {
+          success: false,
+          error: new Error("Skill slug is required")
+        };
+      }
+      const details = await service.getSkillDetails(slug);
+      if (!details) {
+        const text2 = `Skill "${slug}" not found in the registry.`;
+        if (callback) await callback({ text: text2 });
+        return { success: false, error: new Error(text2) };
+      }
+      const isInstalled = await service.isInstalled(slug);
+      const text = `## ${details.skill.displayName}
+
+**Slug:** \`${details.skill.slug}\`
+**Version:** ${details.latestVersion.version}
+**Status:** ${isInstalled ? "\u2705 Installed" : "\u{1F4E6} Available"}
+
+${details.skill.summary}
+
+**Stats:**
+- Downloads: ${details.skill.stats.downloads}
+- Stars: ${details.skill.stats.stars}
+- Versions: ${details.skill.stats.versions}
+
+${details.owner ? `**Author:** ${details.owner.displayName} (@${details.owner.handle})` : ""}
+
+${details.latestVersion.changelog ? `**Changelog:** ${details.latestVersion.changelog}` : ""}`;
+      if (callback) await callback({ text });
+      return {
+        success: true,
+        text,
+        data: { details, isInstalled }
+      };
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      if (callback) {
+        await callback({ text: `Error getting skill details: ${errorMsg}` });
+      }
+      return {
+        success: false,
+        error: error instanceof Error ? error : new Error(errorMsg)
+      };
+    }
+  },
+  examples: [
+    [
+      {
+        name: "{{userName}}",
+        content: { text: "Tell me about the pdf-processing skill" }
+      },
+      {
+        name: "{{agentName}}",
+        content: {
+          text: "## PDF Processing\n\n**Slug:** `pdf-processing`\n**Version:** 1.2.0\n**Status:** \u2705 Installed...",
+          actions: ["GET_SKILL_DETAILS"]
+        }
+      }
+    ]
+  ]
+};
+function extractSlugFromText(text) {
+  const match = text.match(/\b([a-z][a-z0-9-]*[a-z0-9])\b/);
+  return match ? match[1] : null;
+}
+
+// src/actions/get-skill-guidance.ts
+var getSkillGuidanceAction = {
+  name: "GET_SKILL_GUIDANCE",
+  similes: [
+    "FIND_SKILL",
+    "SEARCH_SKILLS",
+    "SKILL_HELP",
+    "HOW_TO",
+    "GET_INSTRUCTIONS",
+    "LEARN_SKILL",
+    "LOOKUP_SKILL"
+  ],
+  description: "Search for and get skill instructions. Use when user asks to find a skill or when you need instructions for a capability.",
+  validate: async (runtime, _message) => {
+    const service = runtime.getService(
+      "AGENT_SKILLS_SERVICE"
+    );
+    return !!service;
+  },
+  handler: async (runtime, message, _state, _options, callback) => {
+    try {
+      const service = runtime.getService(
+        "AGENT_SKILLS_SERVICE"
+      );
+      if (!service) {
+        throw new Error("AgentSkillsService not available");
+      }
+      const query = message.content?.text || "";
+      if (!query || query.length < 3) {
+        return { success: false, error: new Error("Query too short") };
+      }
+      const searchTerms = extractSearchTerms(query);
+      runtime.logger.info(`AgentSkills: Searching for "${searchTerms}"`);
+      const searchResults = await service.search(searchTerms, 5);
+      const installedSkills = service.getLoadedSkills();
+      const localMatch = findBestLocalMatch(installedSkills, searchTerms);
+      runtime.logger.info(
+        `AgentSkills: Found ${searchResults.length} remote results, local match: ${localMatch?.skill.slug || "none"} (score: ${localMatch?.score || 0})`
+      );
+      const bestRemote = searchResults.length > 0 ? searchResults[0] : null;
+      const remoteScore = bestRemote ? bestRemote.score * 100 : 0;
+      const localIsStrong = localMatch && localMatch.score >= 8;
+      if (!bestRemote || bestRemote.score < 0.25 && !localIsStrong) {
+        const text = `I couldn't find a specific skill for "${searchTerms}". I'll do my best with my general knowledge.`;
+        if (callback) await callback({ text });
+        return {
+          success: true,
+          text,
+          data: { found: false, query: searchTerms }
+        };
+      }
+      const useLocal = localIsStrong && (!bestRemote || localMatch.score >= remoteScore);
+      if (useLocal && localMatch) {
+        runtime.logger.info(
+          `AgentSkills: Using local skill "${localMatch.skill.slug}"`
+        );
+        const instructions2 = service.getSkillInstructions(
+          localMatch.skill.slug
+        );
+        return buildSuccessResult(
+          localMatch.skill,
+          instructions2?.body || null,
+          "local",
+          callback
+        );
+      }
+      if (!bestRemote) {
+        const text = `I couldn't find a specific skill for "${searchTerms}".`;
+        if (callback) await callback({ text });
+        return { success: true, text, data: { found: false } };
+      }
+      const alreadyInstalled = service.getLoadedSkill(bestRemote.slug);
+      if (!alreadyInstalled) {
+        const installed = await service.install(bestRemote.slug);
+        if (!installed) {
+          if (localMatch) {
+            const instructions2 = service.getSkillInstructions(
+              localMatch.skill.slug
+            );
+            return buildSuccessResult(
+              localMatch.skill,
+              instructions2?.body || null,
+              "local",
+              callback
+            );
+          }
+          const text = `Found "${bestRemote.displayName}" skill but couldn't install it.`;
+          if (callback) await callback({ text });
+          return {
+            success: true,
+            text,
+            data: { found: true, installed: false }
+          };
+        }
+      }
+      const skill = service.getLoadedSkill(bestRemote.slug);
+      const instructions = skill ? service.getSkillInstructions(skill.slug) : null;
+      return buildSuccessResult(
+        skill || {
+          slug: bestRemote.slug,
+          name: bestRemote.displayName,
+          description: bestRemote.summary,
+          version: bestRemote.version,
+          frontmatter: {
+            name: bestRemote.slug,
+            description: bestRemote.summary
+          },
+          content: "",
+          path: "",
+          scripts: [],
+          references: [],
+          assets: [],
+          loadedAt: Date.now()
+        },
+        instructions?.body || null,
+        alreadyInstalled ? "local" : "installed",
+        callback
+      );
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      if (callback) {
+        await callback({ text: `Error finding skill guidance: ${errorMsg}` });
+      }
+      return {
+        success: false,
+        error: error instanceof Error ? error : new Error(errorMsg)
+      };
+    }
+  },
+  examples: [
+    [
+      { name: "{{userName}}", content: { text: "How do I work with PDFs?" } },
+      {
+        name: "{{agentName}}",
+        content: {
+          text: "I found the **PDF Processing** skill. Here's how to use it:\n\n# PDF Processing\n\nExtract text and tables from PDF files...",
+          actions: ["GET_SKILL_GUIDANCE"]
+        }
+      }
+    ],
+    [
+      {
+        name: "{{userName}}",
+        content: { text: "I need help with browser automation" }
+      },
+      {
+        name: "{{agentName}}",
+        content: {
+          text: "I found the **Browser Automation** skill. Here's the guidance:\n\n# Browser Automation\n\nAutomate browser interactions...",
+          actions: ["GET_SKILL_GUIDANCE"]
+        }
+      }
+    ]
+  ]
+};
+function extractSearchTerms(query) {
+  let cleaned = query.toLowerCase().replace(/\b(on|in|from|at)\s+(clawhub|registry)\b/g, "").replace(/\b(clawhub|registry)\s+(catalog|platform|site)\b/g, "");
+  const stopWords = /* @__PURE__ */ new Set([
+    "search",
+    "find",
+    "look",
+    "for",
+    "a",
+    "an",
+    "the",
+    "skill",
+    "skills",
+    "please",
+    "can",
+    "you",
+    "help",
+    "me",
+    "with",
+    "how",
+    "to",
+    "do",
+    "i",
+    "need",
+    "want",
+    "get",
+    "use",
+    "using",
+    "about",
+    "is",
+    "are",
+    "there",
+    "any",
+    "some",
+    "show",
+    "list",
+    "give",
+    "tell",
+    "what",
+    "which"
+  ]);
+  const words = cleaned.replace(/[^\w\s-]/g, " ").split(/\s+/).filter((w) => w.length > 1 && !stopWords.has(w));
+  return words.join(" ") || query.toLowerCase();
+}
+function findBestLocalMatch(skills, query) {
+  const queryLower = query.toLowerCase();
+  const queryWords = queryLower.split(/\s+/).filter((w) => w.length > 2);
+  let bestMatch = null;
+  for (const skill of skills) {
+    let score = 0;
+    const slugLower = skill.slug.toLowerCase();
+    const nameLower = skill.name.toLowerCase();
+    if (queryLower.includes(slugLower) || queryWords.some((w) => slugLower.includes(w) && w.length > 3)) {
+      score += 10;
+    }
+    if (queryLower.includes(nameLower) || queryWords.some((w) => nameLower.includes(w) && w.length > 3)) {
+      score += 8;
+    }
+    const genericWords = /* @__PURE__ */ new Set([
+      "skill",
+      "agent",
+      "search",
+      "install",
+      "use",
+      "when",
+      "with",
+      "from",
+      "your"
+    ]);
+    const descWords = skill.description.toLowerCase().split(/\s+/);
+    for (const word of descWords) {
+      if (word.length > 5 && !genericWords.has(word) && queryWords.includes(word)) {
+        score += 1;
+      }
+    }
+    if (score > 0 && (!bestMatch || score > bestMatch.score)) {
+      bestMatch = { skill, score };
+    }
+  }
+  return bestMatch;
+}
+async function buildSuccessResult(skill, instructions, source, callback) {
+  let text = `## ${skill.name}
+
+`;
+  if (source === "installed") {
+    text += `*Skill installed from registry*
+
+`;
+  }
+  text += `${skill.description}
+
+`;
+  if (instructions) {
+    const maxLen = 3500;
+    const truncated = instructions.length > maxLen ? instructions.substring(0, maxLen) + "\n\n...[truncated]" : instructions;
+    text += `### Instructions
+
+${truncated}`;
+  }
+  if (callback) {
+    await callback({ text, actions: ["GET_SKILL_GUIDANCE"] });
+  }
+  return {
+    success: true,
+    text,
+    values: {
+      activeSkill: skill.slug,
+      skillName: skill.name,
+      skillSource: source
+    },
+    data: {
+      skill: {
+        slug: skill.slug,
+        name: skill.name,
+        description: skill.description
+      },
+      instructions,
+      source
+    }
+  };
+}
+
+// src/actions/sync-catalog.ts
+var syncCatalogAction = {
+  name: "SYNC_SKILL_CATALOG",
+  similes: ["REFRESH_SKILLS", "UPDATE_CATALOG"],
+  description: "Sync the skill catalog from the registry to discover new skills.",
+  validate: async (runtime, _message) => {
+    const service = runtime.getService(
+      "AGENT_SKILLS_SERVICE"
+    );
+    return !!service;
+  },
+  handler: async (runtime, _message, _state, _options, callback) => {
+    try {
+      const service = runtime.getService(
+        "AGENT_SKILLS_SERVICE"
+      );
+      if (!service) {
+        throw new Error("AgentSkillsService not available");
+      }
+      runtime.logger.info("AgentSkills: Manual catalog sync triggered");
+      const result = await service.syncCatalog();
+      const text = `Skill catalog synced successfully.
+- Total skills: ${result.updated}
+- New skills: ${result.added}`;
+      if (callback) await callback({ text });
+      return {
+        success: true,
+        text,
+        data: result
+      };
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      if (callback) {
+        await callback({ text: `Error syncing catalog: ${errorMsg}` });
+      }
+      return {
+        success: false,
+        error: error instanceof Error ? error : new Error(errorMsg)
+      };
+    }
+  },
+  examples: [
+    [
+      { name: "{{userName}}", content: { text: "Refresh the skill catalog" } },
+      {
+        name: "{{agentName}}",
+        content: {
+          text: "Skill catalog synced successfully.\n- Total skills: 150\n- New skills: 5",
+          actions: ["SYNC_SKILL_CATALOG"]
+        }
+      }
+    ]
+  ]
+};
+
+// src/actions/run-skill-script.ts
+import { spawn } from "child_process";
+import * as path from "path";
+var runSkillScriptAction = {
+  name: "RUN_SKILL_SCRIPT",
+  similes: ["EXECUTE_SKILL_SCRIPT", "SKILL_SCRIPT"],
+  description: "Execute a script bundled with an installed skill. Provide skill slug and script name.",
+  validate: async (runtime, _message) => {
+    const service = runtime.getService(
+      "AGENT_SKILLS_SERVICE"
+    );
+    return !!service;
+  },
+  handler: async (runtime, message, _state, options, callback) => {
+    try {
+      const service = runtime.getService(
+        "AGENT_SKILLS_SERVICE"
+      );
+      if (!service) {
+        throw new Error("AgentSkillsService not available");
+      }
+      const opts = options;
+      const skillSlug = opts?.skillSlug;
+      const scriptName = opts?.script;
+      const args = opts?.args || [];
+      if (!skillSlug || !scriptName) {
+        return {
+          success: false,
+          error: new Error("Both skillSlug and script are required")
+        };
+      }
+      const scriptPath = service.getScriptPath(skillSlug, scriptName);
+      if (!scriptPath) {
+        return {
+          success: false,
+          error: new Error(
+            `Script "${scriptName}" not found in skill "${skillSlug}"`
+          )
+        };
+      }
+      runtime.logger.info(`AgentSkills: Executing ${skillSlug}/${scriptName}`);
+      const result = await executeScript(scriptPath, args);
+      const text = result.success ? `Script executed successfully:
+\`\`\`
+${result.stdout}
+\`\`\`` : `Script failed:
+\`\`\`
+${result.stderr}
+\`\`\``;
+      if (callback) {
+        await callback({ text });
+      }
+      return {
+        success: result.success,
+        text,
+        data: {
+          scriptPath,
+          exitCode: result.exitCode,
+          stdout: result.stdout,
+          stderr: result.stderr
+        }
+      };
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      if (callback) {
+        await callback({ text: `Error executing script: ${errorMsg}` });
+      }
+      return {
+        success: false,
+        error: error instanceof Error ? error : new Error(errorMsg)
+      };
+    }
+  },
+  examples: [
+    [
+      {
+        name: "{{userName}}",
+        content: { text: "Run the rotate script from pdf-skill" }
+      },
+      {
+        name: "{{agentName}}",
+        content: {
+          text: "I'll run the rotate_pdf.py script from the pdf-skill.",
+          actions: ["RUN_SKILL_SCRIPT"]
+        }
+      }
+    ]
+  ]
+};
+async function executeScript(scriptPath, args) {
+  return new Promise((resolve) => {
+    const ext = path.extname(scriptPath).toLowerCase();
+    let cmd;
+    let cmdArgs;
+    switch (ext) {
+      case ".py":
+        cmd = "python3";
+        cmdArgs = [scriptPath, ...args];
+        break;
+      case ".sh":
+        cmd = "bash";
+        cmdArgs = [scriptPath, ...args];
+        break;
+      case ".js":
+        cmd = "node";
+        cmdArgs = [scriptPath, ...args];
+        break;
+      default:
+        cmd = scriptPath;
+        cmdArgs = args;
+    }
+    const child = spawn(cmd, cmdArgs, {
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 6e4
+      // 1 minute timeout
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (data) => {
+      stdout += data.toString();
+    });
+    child.stderr?.on("data", (data) => {
+      stderr += data.toString();
+    });
+    child.on("close", (code) => {
+      resolve({
+        success: code === 0,
+        exitCode: code || 0,
+        stdout: stdout.trim(),
+        stderr: stderr.trim()
+      });
+    });
+    child.on("error", (error) => {
+      resolve({
+        success: false,
+        exitCode: -1,
+        stdout: "",
+        stderr: error.message
+      });
+    });
+  });
+}
+
+// src/providers/skills.ts
+var skillsOverviewProvider = {
+  name: "agent_skills_overview",
+  description: "Low-res overview of available Agent Skills (names only)",
+  position: -20,
+  dynamic: true,
+  get: async (runtime, _message, _state) => {
+    const service = runtime.getService(
+      "AGENT_SKILLS_SERVICE"
+    );
+    if (!service) return { text: "" };
+    const stats = service.getCatalogStats();
+    const installed = service.getLoadedSkills();
+    const catalog = await service.getCatalog({ notOlderThan: Infinity });
+    const availableCount = catalog.length;
+    const examples = catalog.slice(0, 5).map((s) => s.displayName).join(", ");
+    const text = `**Skills:** ${stats.installed} installed, ${availableCount} available
+Examples: ${examples}...
+Use GET_SKILL_GUIDANCE to find skills for specific tasks.`;
+    return {
+      text,
+      values: {
+        installedCount: stats.installed,
+        availableCount
+      },
+      data: {
+        installed: installed.map((s) => s.slug),
+        catalogSize: availableCount
+      }
+    };
+  }
+};
+var skillsSummaryProvider = {
+  name: "agent_skills",
+  description: "Medium-res list of installed Agent Skills with descriptions",
+  position: -10,
+  get: async (runtime, _message, _state) => {
+    const service = runtime.getService(
+      "AGENT_SKILLS_SERVICE"
+    );
+    if (!service) return { text: "" };
+    const skills = service.getLoadedSkills();
+    if (skills.length === 0) {
+      return {
+        text: "**Skills:** None installed. Use GET_SKILL_GUIDANCE to find and install skills.",
+        values: { skillCount: 0 },
+        data: { skills: [] }
+      };
+    }
+    const xml = service.generateSkillsPromptXml({ includeLocation: true });
+    const text = `## Installed Skills (${skills.length})
+
+${xml}
+
+*More skills available via GET_SKILL_GUIDANCE*`;
+    return {
+      text,
+      values: {
+        skillCount: skills.length,
+        installedSkills: skills.map((s) => s.slug).join(", ")
+      },
+      data: {
+        skills: skills.map((s) => ({
+          slug: s.slug,
+          name: s.name,
+          description: s.description,
+          version: s.version
+        }))
+      }
+    };
+  }
+};
+var skillInstructionsProvider = {
+  name: "agent_skill_instructions",
+  description: "High-res instructions from the most relevant skill",
+  position: 5,
+  get: async (runtime, message, state) => {
+    const service = runtime.getService(
+      "AGENT_SKILLS_SERVICE"
+    );
+    if (!service) return { text: "" };
+    const skills = service.getLoadedSkills();
+    if (skills.length === 0) return { text: "" };
+    const messageText = (message.content?.text || "").toLowerCase();
+    const recentContext = getRecentContext(state);
+    const fullContext = `${messageText} ${recentContext}`.toLowerCase();
+    const scoredSkills = skills.map((skill) => ({
+      skill,
+      score: calculateSkillRelevance(skill, fullContext)
+    })).filter((s) => s.score > 0).sort((a, b) => b.score - a.score);
+    if (scoredSkills.length === 0 || scoredSkills[0].score < 3) {
+      return { text: "" };
+    }
+    const topSkill = scoredSkills[0];
+    const instructions = service.getSkillInstructions(topSkill.skill.slug);
+    if (!instructions) return { text: "" };
+    const maxChars = 4e3;
+    const truncatedBody = instructions.body.length > maxChars ? instructions.body.substring(0, maxChars) + "\n\n...[truncated]" : instructions.body;
+    const text = `## Active Skill: ${topSkill.skill.name}
+
+${truncatedBody}`;
+    return {
+      text,
+      values: {
+        activeSkill: topSkill.skill.slug,
+        skillName: topSkill.skill.name,
+        relevanceScore: topSkill.score,
+        estimatedTokens: instructions.estimatedTokens
+      },
+      data: {
+        activeSkill: {
+          slug: topSkill.skill.slug,
+          name: topSkill.skill.name,
+          score: topSkill.score
+        },
+        otherMatches: scoredSkills.slice(1, 3).map((s) => ({
+          slug: s.skill.slug,
+          score: s.score
+        }))
+      }
+    };
+  }
+};
+var catalogAwarenessProvider = {
+  name: "agent_skills_catalog",
+  description: "Awareness of skills available on the registry",
+  position: 10,
+  dynamic: true,
+  private: true,
+  get: async (runtime, message, _state) => {
+    const service = runtime.getService(
+      "AGENT_SKILLS_SERVICE"
+    );
+    if (!service) return { text: "" };
+    const text = (message.content?.text || "").toLowerCase();
+    const capabilityKeywords = [
+      "what can you",
+      "what skills",
+      "capabilities",
+      "what do you know",
+      "help with"
+    ];
+    if (!capabilityKeywords.some((kw) => text.includes(kw))) {
+      return { text: "" };
+    }
+    const catalog = await service.getCatalog({ notOlderThan: Infinity });
+    if (catalog.length === 0) return { text: "" };
+    const categories = groupByCategory(catalog);
+    let categoryText = "";
+    for (const [category, skills] of Object.entries(categories).slice(0, 8)) {
+      const skillNames = skills.slice(0, 3).map((s) => s.name).join(", ");
+      const more = skills.length > 3 ? ` +${skills.length - 3} more` : "";
+      categoryText += `- **${category}**: ${skillNames}${more}
+`;
+    }
+    return {
+      text: `## Available Skill Categories
+
+${categoryText}
+Use GET_SKILL_GUIDANCE to find and use any skill.`,
+      data: { categories }
+    };
+  }
+};
+function getRecentContext(state) {
+  const recentMessages = state.recentMessages || state.recentMessagesData || [];
+  if (Array.isArray(recentMessages)) {
+    return recentMessages.slice(-5).map(
+      (m) => m.content?.text || ""
+    ).join(" ");
+  }
+  return "";
+}
+function calculateSkillRelevance(skill, context) {
+  let score = 0;
+  const contextLower = context.toLowerCase();
+  if (contextLower.includes(skill.slug.toLowerCase())) score += 10;
+  if (contextLower.includes(skill.name.toLowerCase())) score += 8;
+  const nameWords = skill.name.split(/[\s-_]+/).filter((w) => w.length > 3);
+  for (const word of nameWords) {
+    if (contextLower.includes(word.toLowerCase())) score += 2;
+  }
+  const stopwords = /* @__PURE__ */ new Set([
+    "the",
+    "and",
+    "for",
+    "with",
+    "this",
+    "that",
+    "from",
+    "will",
+    "can",
+    "are",
+    "use",
+    "when",
+    "how",
+    "what",
+    "your",
+    "you",
+    "our",
+    "has",
+    "have",
+    "been",
+    "skill",
+    "agent",
+    "search",
+    "install"
+  ]);
+  const descWords = skill.description.toLowerCase().replace(/[^a-z0-9\s]/g, " ").split(/\s+/).filter((w) => w.length > 4 && !stopwords.has(w));
+  for (const word of descWords) {
+    if (contextLower.includes(word)) score += 1;
+  }
+  const triggerMatch = skill.description.match(
+    /Use (?:when|for|to)\s+([^.]+)/i
+  );
+  if (triggerMatch) {
+    const triggerWords = triggerMatch[1].split(/[,;]/).map((t) => t.trim().toLowerCase());
+    for (const trigger of triggerWords) {
+      if (trigger && contextLower.includes(trigger)) score += 3;
+    }
+  }
+  return score;
+}
+function groupByCategory(skills) {
+  const categories = {};
+  const categoryKeywords = {
+    "AI & Models": [
+      "ai",
+      "llm",
+      "model",
+      "gpt",
+      "claude",
+      "openai",
+      "anthropic"
+    ],
+    "Browser & Web": ["browser", "web", "scrape", "chrome", "selenium"],
+    "Code & Dev": ["code", "python", "javascript", "typescript", "git", "dev"],
+    "Data & Analytics": ["data", "analytics", "csv", "json", "database"],
+    "Finance & Trading": [
+      "trading",
+      "finance",
+      "crypto",
+      "market",
+      "prediction"
+    ],
+    Communication: ["email", "slack", "discord", "telegram", "chat"],
+    Productivity: ["calendar", "task", "todo", "note", "document"],
+    Other: []
+  };
+  for (const skill of skills) {
+    const text = `${skill.displayName} ${skill.summary || ""}`.toLowerCase();
+    let assigned = false;
+    for (const [category, keywords] of Object.entries(categoryKeywords)) {
+      if (category === "Other") continue;
+      if (keywords.some((kw) => text.includes(kw))) {
+        if (!categories[category]) categories[category] = [];
+        categories[category].push({
+          slug: skill.slug,
+          name: skill.displayName
+        });
+        assigned = true;
+        break;
+      }
+    }
+    if (!assigned) {
+      if (!categories["Other"]) categories["Other"] = [];
+      categories["Other"].push({ slug: skill.slug, name: skill.displayName });
+    }
+  }
+  return categories;
+}
+var skillsProvider = skillsSummaryProvider;
+
+// src/tasks/sync-catalog.ts
+var SYNC_INTERVAL_MS = 1e3 * 60 * 60;
+var syncCatalogTask = {
+  name: "agent-skills-sync",
+  description: "Sync skill catalog from registry",
+  execute: async (runtime) => {
+    const service = runtime.getService(
+      "AGENT_SKILLS_SERVICE"
+    );
+    if (!service) {
+      runtime.logger.warn("AgentSkills: Sync task - service not available");
+      return;
+    }
+    try {
+      const result = await service.syncCatalog();
+      runtime.logger.info(
+        `AgentSkills: Catalog synced - ${result.updated} skills, ${result.added} new`
+      );
+    } catch (error) {
+      runtime.logger.error(`AgentSkills: Sync failed: ${error}`);
+    }
+  }
+};
+function startSyncTask(runtime) {
+  const initialTimeout = setTimeout(() => {
+    syncCatalogTask.execute(runtime).catch((err) => {
+      runtime.logger.error(`AgentSkills: Initial sync failed: ${err}`);
+    });
+  }, 5e3);
+  const interval = setInterval(() => {
+    syncCatalogTask.execute(runtime).catch((err) => {
+      runtime.logger.error(`AgentSkills: Periodic sync failed: ${err}`);
+    });
+  }, SYNC_INTERVAL_MS);
+  return () => {
+    clearTimeout(initialTimeout);
+    clearInterval(interval);
+  };
+}
+
+// src/plugin.ts
+var ALL_SERVICES = [
+  AgentSkillsService
+];
+var ALL_ACTIONS = [
+  searchSkillsAction,
+  // Browse/search available skills
+  getSkillDetailsAction,
+  // Get info about a specific skill
+  getSkillGuidanceAction,
+  // Auto-finds, installs, returns skill instructions
+  syncCatalogAction,
+  // Manual catalog sync
+  runSkillScriptAction
+  // Execute scripts from installed skills
+];
+var ALL_PROVIDERS = [
+  skillsSummaryProvider,
+  // Medium-res (default) - installed skills
+  skillInstructionsProvider,
+  // High-res - active skill instructions
+  catalogAwarenessProvider
+  // Dynamic - catalog awareness
+];
+var cleanupSyncTask = null;
+var agentSkillsPlugin = {
+  name: "@elizaos/plugin-agent-skills",
+  description: "Agent Skills - modular capabilities with progressive disclosure",
+  services: ALL_SERVICES,
+  actions: ALL_ACTIONS,
+  providers: ALL_PROVIDERS,
+  evaluators: [],
+  routes: [],
+  // Initialize background task when plugin loads
+  init: async (_config, runtime) => {
+    cleanupSyncTask = startSyncTask(runtime);
+    runtime.logger.info("AgentSkills: Background sync task started");
+  }
+};
+var clawHubPlugin = agentSkillsPlugin;
+var plugin_default = agentSkillsPlugin;
+
+// src/services/install.ts
+var DEFAULT_TIMEOUT = 3e5;
+var NODE_MANAGERS = ["bun", "pnpm", "npm", "yarn"];
+function detectPlatform() {
+  if (typeof process === "undefined") return "unknown";
+  const platform = process.platform;
+  if (platform === "darwin") return "darwin";
+  if (platform === "linux") return "linux";
+  if (platform === "win32") return "windows";
+  return "unknown";
+}
+async function binaryExists(name) {
+  try {
+    const { execSync } = await import("node:child_process");
+    const platform = detectPlatform();
+    const command = platform === "windows" ? `where ${name}` : `which ${name}`;
+    execSync(command, { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function getPreferredNodeManager() {
+  const preferred = process.env.OTTO_NODE_MANAGER;
+  if (preferred && await binaryExists(preferred)) {
+    return preferred;
+  }
+  for (const manager of NODE_MANAGERS) {
+    if (await binaryExists(manager)) {
+      return manager;
+    }
+  }
+  return null;
+}
+async function isHomebrewAvailable() {
+  return detectPlatform() === "darwin" && await binaryExists("brew");
+}
+async function isAptAvailable() {
+  return detectPlatform() === "linux" && await binaryExists("apt-get");
+}
+async function isPipAvailable() {
+  return await binaryExists("pip3") || await binaryExists("pip");
+}
+async function isCargoAvailable() {
+  return binaryExists("cargo");
+}
+function buildInstallCommand(option) {
+  switch (option.kind) {
+    case "brew":
+      return `brew install ${option.formula || option.package}`;
+    case "apt":
+      return `sudo apt-get install -y ${option.package}`;
+    case "node": {
+      const pkg = option.package;
+      return `__NODE_MANAGER__ install -g ${pkg}`;
+    }
+    case "pip":
+      return `pip3 install ${option.package}`;
+    case "cargo":
+      return `cargo install ${option.package}`;
+    case "manual":
+      return null;
+    default:
+      return null;
+  }
+}
+async function resolveNodeManager(command) {
+  if (!command.includes("__NODE_MANAGER__")) {
+    return command;
+  }
+  const manager = await getPreferredNodeManager();
+  if (!manager) {
+    throw new Error("No Node.js package manager found (tried bun, pnpm, npm, yarn)");
+  }
+  return command.replace("__NODE_MANAGER__", manager);
+}
+async function executeInstall(command, options = {}) {
+  const { timeout = DEFAULT_TIMEOUT, onProgress, dryRun } = options;
+  const startTime = Date.now();
+  if (dryRun) {
+    onProgress?.({
+      phase: "complete",
+      progress: 100,
+      message: `[DRY RUN] Would execute: ${command}`
+    });
+    return { success: true, duration: 0 };
+  }
+  try {
+    const { spawn: spawn2 } = await import("node:child_process");
+    onProgress?.({
+      phase: "installing",
+      progress: 10,
+      message: `Executing: ${command}`
+    });
+    return await new Promise((resolve) => {
+      const child = spawn2("sh", ["-c", command], {
+        stdio: ["pipe", "pipe", "pipe"],
+        timeout
+      });
+      let stdout = "";
+      let stderr = "";
+      child.stdout?.on("data", (data) => {
+        stdout += data.toString();
+        onProgress?.({
+          phase: "installing",
+          progress: 50,
+          message: data.toString().trim().slice(0, 200)
+        });
+      });
+      child.stderr?.on("data", (data) => {
+        stderr += data.toString();
+      });
+      child.on("close", (code) => {
+        const duration = Date.now() - startTime;
+        if (code === 0) {
+          onProgress?.({
+            phase: "complete",
+            progress: 100,
+            message: "Installation completed successfully"
+          });
+          resolve({ success: true, duration });
+        } else {
+          const error = stderr || stdout || `Process exited with code ${code}`;
+          onProgress?.({
+            phase: "error",
+            message: "Installation failed",
+            error
+          });
+          resolve({ success: false, error, duration });
+        }
+      });
+      child.on("error", (err) => {
+        const duration = Date.now() - startTime;
+        const error = err.message;
+        onProgress?.({
+          phase: "error",
+          message: "Installation failed",
+          error
+        });
+        resolve({ success: false, error, duration });
+      });
+    });
+  } catch (error) {
+    const duration = Date.now() - startTime;
+    const errorMessage = error instanceof Error ? error.message : "Unknown error";
+    onProgress?.({
+      phase: "error",
+      message: "Installation failed",
+      error: errorMessage
+    });
+    return { success: false, error: errorMessage, duration };
+  }
+}
+async function installSkillDependency(options) {
+  const { option, onProgress, dryRun, timeout } = options;
+  onProgress?.({
+    phase: "installing",
+    progress: 0,
+    message: `Preparing to install via ${option.kind}...`
+  });
+  const platform = detectPlatform();
+  switch (option.kind) {
+    case "brew":
+      if (!await isHomebrewAvailable()) {
+        return {
+          success: false,
+          option,
+          error: "Homebrew is not available (macOS only)"
+        };
+      }
+      break;
+    case "apt":
+      if (!await isAptAvailable()) {
+        return {
+          success: false,
+          option,
+          error: "apt-get is not available (Debian/Ubuntu only)"
+        };
+      }
+      break;
+    case "node":
+      if (!await getPreferredNodeManager()) {
+        return {
+          success: false,
+          option,
+          error: "No Node.js package manager found"
+        };
+      }
+      break;
+    case "pip":
+      if (!await isPipAvailable()) {
+        return {
+          success: false,
+          option,
+          error: "pip/pip3 is not available"
+        };
+      }
+      break;
+    case "cargo":
+      if (!await isCargoAvailable()) {
+        return {
+          success: false,
+          option,
+          error: "cargo is not available (Rust)"
+        };
+      }
+      break;
+    case "manual":
+      return {
+        success: false,
+        option,
+        error: `Manual installation required: ${option.label || "See skill documentation"}`
+      };
+  }
+  let command = buildInstallCommand(option);
+  if (!command) {
+    return {
+      success: false,
+      option,
+      error: `Cannot build command for install kind: ${option.kind}`
+    };
+  }
+  try {
+    command = await resolveNodeManager(command);
+  } catch (error) {
+    return {
+      success: false,
+      option,
+      error: error instanceof Error ? error.message : "Failed to resolve node manager"
+    };
+  }
+  const result = await executeInstall(command, {
+    timeout,
+    onProgress,
+    dryRun
+  });
+  return {
+    ...result,
+    option,
+    command
+  };
+}
+async function findBestInstallOption(options) {
+  const platform = detectPlatform();
+  const preferenceOrder = [];
+  if (platform === "darwin") {
+    preferenceOrder.push("brew", "node", "pip", "cargo");
+  } else if (platform === "linux") {
+    preferenceOrder.push("apt", "node", "pip", "cargo");
+  } else {
+    preferenceOrder.push("node", "pip", "cargo");
+  }
+  for (const kind of preferenceOrder) {
+    const option = options.find((o) => o.kind === kind);
+    if (option) {
+      switch (kind) {
+        case "brew":
+          if (await isHomebrewAvailable()) return option;
+          break;
+        case "apt":
+          if (await isAptAvailable()) return option;
+          break;
+        case "node":
+          if (await getPreferredNodeManager()) return option;
+          break;
+        case "pip":
+          if (await isPipAvailable()) return option;
+          break;
+        case "cargo":
+          if (await isCargoAvailable()) return option;
+          break;
+      }
+    }
+  }
+  const manual = options.find((o) => o.kind === "manual");
+  return manual || null;
+}
+async function getAvailableInstallOptions(options) {
+  const available = [];
+  for (const option of options) {
+    switch (option.kind) {
+      case "brew":
+        if (await isHomebrewAvailable()) available.push(option);
+        break;
+      case "apt":
+        if (await isAptAvailable()) available.push(option);
+        break;
+      case "node":
+        if (await getPreferredNodeManager()) available.push(option);
+        break;
+      case "pip":
+        if (await isPipAvailable()) available.push(option);
+        break;
+      case "cargo":
+        if (await isCargoAvailable()) available.push(option);
+        break;
+      case "manual":
+        available.push(option);
+        break;
+    }
+  }
+  return available;
+}
+async function installSkillDependencies(skill, options = {}) {
+  const metadata = skill.frontmatter.metadata?.otto;
+  const installOptions = metadata?.install || [];
+  if (installOptions.length === 0) {
+    return [];
+  }
+  const results = [];
+  const { onProgress, dryRun } = options;
+  const binsByOption = /* @__PURE__ */ new Map();
+  for (const option of installOptions) {
+    const bins = option.bins || [];
+    for (const bin of bins) {
+      if (!binsByOption.has(bin)) {
+        binsByOption.set(bin, []);
+      }
+      binsByOption.get(bin).push(option);
+    }
+  }
+  for (const [bin, opts] of binsByOption) {
+    if (await binaryExists(bin)) {
+      onProgress?.({
+        phase: "complete",
+        message: `${bin} is already installed`
+      });
+      continue;
+    }
+    const bestOption = await findBestInstallOption(opts);
+    if (!bestOption) {
+      results.push({
+        success: false,
+        option: opts[0],
+        error: `No available installation method for ${bin}`
+      });
+      continue;
+    }
+    const result = await installSkillDependency({
+      option: bestOption,
+      onProgress,
+      dryRun
+    });
+    results.push(result);
+    if (!result.success) {
+      break;
+    }
+  }
+  return results;
+}
+async function getInstallPlan(skill) {
+  const metadata = skill.frontmatter.metadata?.otto;
+  const requiredBins = metadata?.requires?.bins || [];
+  const installOptions = metadata?.install || [];
+  const missingBins = [];
+  for (const bin of requiredBins) {
+    if (!await binaryExists(bin)) {
+      missingBins.push(bin);
+    }
+  }
+  const availableOptions = await getAvailableInstallOptions(installOptions);
+  const recommendedOptions = [];
+  for (const bin of missingBins) {
+    const opts = installOptions.filter((o) => o.bins?.includes(bin));
+    const best = await findBestInstallOption(opts);
+    if (best && !recommendedOptions.includes(best)) {
+      recommendedOptions.push(best);
+    }
+  }
+  return {
+    requiredBins,
+    missingBins,
+    availableOptions,
+    recommendedOptions
+  };
+}
+export {
+  AgentSkillsService,
+  AgentSkillsService as ClawHubService,
+  FileSystemSkillStore,
+  MemorySkillStore,
+  SKILL_BODY_RECOMMENDED_TOKENS,
+  SKILL_COMPATIBILITY_MAX_LENGTH,
+  SKILL_DESCRIPTION_MAX_LENGTH,
+  SKILL_NAME_MAX_LENGTH,
+  SKILL_NAME_PATTERN,
+  SKILL_SOURCE_PRECEDENCE,
+  agentSkillsPlugin,
+  catalogAwarenessProvider,
+  clawHubPlugin,
+  createStorage,
+  plugin_default as default,
+  estimateTokens,
+  extractBody,
+  findBestInstallOption,
+  generateSkillsXml,
+  getAvailableInstallOptions,
+  getInstallPlan,
+  getPreferredNodeManager,
+  getSkillDetailsAction,
+  getSkillGuidanceAction,
+  installSkillDependencies,
+  installSkillDependency,
+  isAptAvailable,
+  isCargoAvailable,
+  isHomebrewAvailable,
+  isPipAvailable,
+  loadSkillFromStorage,
+  parseFrontmatter,
+  runSkillScriptAction,
+  searchSkillsAction,
+  skillInstructionsProvider,
+  skillsOverviewProvider,
+  skillsProvider,
+  skillsSummaryProvider,
+  startSyncTask,
+  syncCatalogAction,
+  syncCatalogTask,
+  validateFrontmatter,
+  validateSkillDirectory
+};
+//# sourceMappingURL=index.js.map