@agentforge/skills 0.15.0

package/dist/index.cjs

@@ -0,0 +1,850 @@
+'use strict';
+
+var matter = require('gray-matter');
+var fs = require('fs');
+var path = require('path');
+var os = require('os');
+var core = require('@agentforge/core');
+var zod = require('zod');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var matter__default = /*#__PURE__*/_interopDefault(matter);
+
+// src/types.ts
+var TrustPolicyReason = /* @__PURE__ */ ((TrustPolicyReason2) => {
+  TrustPolicyReason2["NOT_SCRIPT"] = "not-script";
+  TrustPolicyReason2["WORKSPACE_TRUST"] = "workspace-trust";
+  TrustPolicyReason2["TRUSTED_ROOT"] = "trusted-root";
+  TrustPolicyReason2["UNTRUSTED_SCRIPT_DENIED"] = "untrusted-script-denied";
+  TrustPolicyReason2["UNTRUSTED_SCRIPT_ALLOWED"] = "untrusted-script-allowed-override";
+  TrustPolicyReason2["UNKNOWN_TRUST_LEVEL"] = "unknown-trust-level";
+  return TrustPolicyReason2;
+})(TrustPolicyReason || {});
+var SkillRegistryEvent = /* @__PURE__ */ ((SkillRegistryEvent2) => {
+  SkillRegistryEvent2["SKILL_DISCOVERED"] = "skill:discovered";
+  SkillRegistryEvent2["SKILL_WARNING"] = "skill:warning";
+  SkillRegistryEvent2["SKILL_ACTIVATED"] = "skill:activated";
+  SkillRegistryEvent2["SKILL_RESOURCE_LOADED"] = "skill:resource-loaded";
+  SkillRegistryEvent2["TRUST_POLICY_DENIED"] = "trust:policy-denied";
+  SkillRegistryEvent2["TRUST_POLICY_ALLOWED"] = "trust:policy-allowed";
+  return SkillRegistryEvent2;
+})(SkillRegistryEvent || {});
+var SKILL_NAME_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+var SKILL_NAME_MAX_LENGTH = 64;
+var SKILL_DESCRIPTION_MAX_LENGTH = 1024;
+function validateSkillName(name) {
+  const errors = [];
+  if (name === void 0 || name === null) {
+    errors.push({ field: "name", message: "name is required" });
+    return errors;
+  }
+  if (typeof name !== "string") {
+    errors.push({ field: "name", message: "name must be a string" });
+    return errors;
+  }
+  if (name.length === 0) {
+    errors.push({ field: "name", message: "name must not be empty" });
+    return errors;
+  }
+  if (name.length > SKILL_NAME_MAX_LENGTH) {
+    errors.push({
+      field: "name",
+      message: `name must be at most ${SKILL_NAME_MAX_LENGTH} characters (got ${name.length})`
+    });
+    return errors;
+  }
+  if (!SKILL_NAME_PATTERN.test(name)) {
+    errors.push({
+      field: "name",
+      message: "name must be lowercase alphanumeric with hyphens, no leading/trailing/consecutive hyphens"
+    });
+  }
+  if (name.includes("--")) {
+    errors.push({
+      field: "name",
+      message: "name must not contain consecutive hyphens"
+    });
+  }
+  return errors;
+}
+function validateSkillDescription(description) {
+  const errors = [];
+  if (description === void 0 || description === null) {
+    errors.push({ field: "description", message: "description is required" });
+    return errors;
+  }
+  if (typeof description !== "string") {
+    errors.push({ field: "description", message: "description must be a string" });
+    return errors;
+  }
+  if (description.trim().length === 0) {
+    errors.push({ field: "description", message: "description must not be empty" });
+    return errors;
+  }
+  if (description.length > SKILL_DESCRIPTION_MAX_LENGTH) {
+    errors.push({
+      field: "description",
+      message: `description must be at most ${SKILL_DESCRIPTION_MAX_LENGTH} characters (got ${description.length})`
+    });
+  }
+  return errors;
+}
+function validateSkillNameMatchesDir(name, dirName) {
+  if (name !== dirName) {
+    return [{
+      field: "name",
+      message: `name "${name}" must match parent directory name "${dirName}"`
+    }];
+  }
+  return [];
+}
+function parseSkillContent(content, dirName) {
+  let parsed;
+  try {
+    parsed = matter__default.default(content);
+  } catch (err) {
+    return {
+      success: false,
+      error: `Failed to parse frontmatter: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+  const data = parsed.data;
+  const errors = [
+    ...validateSkillName(data.name),
+    ...validateSkillDescription(data.description)
+  ];
+  if (typeof data.name === "string" && data.name.length > 0 && SKILL_NAME_PATTERN.test(data.name)) {
+    errors.push(...validateSkillNameMatchesDir(data.name, dirName));
+  }
+  if (errors.length > 0) {
+    return {
+      success: false,
+      error: errors.map((e) => `${e.field}: ${e.message}`).join("; ")
+    };
+  }
+  const metadata = {
+    name: data.name,
+    description: data.description
+  };
+  if (data.license !== void 0) {
+    metadata.license = String(data.license);
+  }
+  if (Array.isArray(data.compatibility)) {
+    metadata.compatibility = data.compatibility.map(String);
+  }
+  if (data.metadata !== void 0 && typeof data.metadata === "object" && data.metadata !== null) {
+    metadata.metadata = data.metadata;
+  }
+  if (Array.isArray(data["allowed-tools"])) {
+    metadata.allowedTools = data["allowed-tools"].map(String);
+  }
+  return {
+    success: true,
+    metadata,
+    body: parsed.content
+  };
+}
+var logger = core.createLogger("agentforge:skills:scanner", { level: core.LogLevel.INFO });
+function expandHome(p) {
+  if (p.startsWith("~/") || p === "~") {
+    return path.resolve(os.homedir(), p.slice(2));
+  }
+  return p;
+}
+function scanSkillRoot(rootPath) {
+  const resolvedRoot = path.resolve(expandHome(rootPath));
+  const candidates = [];
+  if (!fs.existsSync(resolvedRoot)) {
+    logger.debug("Skill root does not exist, skipping", { rootPath: resolvedRoot });
+    return candidates;
+  }
+  let entries;
+  try {
+    entries = fs.readdirSync(resolvedRoot);
+  } catch (err) {
+    logger.warn("Failed to read skill root directory", {
+      rootPath: resolvedRoot,
+      error: err instanceof Error ? err.message : String(err)
+    });
+    return candidates;
+  }
+  for (const entry of entries) {
+    const entryPath = path.resolve(resolvedRoot, entry);
+    let stat;
+    try {
+      stat = fs.statSync(entryPath);
+    } catch {
+      continue;
+    }
+    if (!stat.isDirectory()) {
+      continue;
+    }
+    const skillMdPath = path.resolve(entryPath, "SKILL.md");
+    if (!fs.existsSync(skillMdPath)) {
+      continue;
+    }
+    try {
+      const content = fs.readFileSync(skillMdPath, "utf-8");
+      candidates.push({
+        skillPath: entryPath,
+        dirName: path.basename(entryPath),
+        content,
+        rootPath: resolvedRoot
+      });
+    } catch (err) {
+      logger.warn("Failed to read SKILL.md", {
+        path: skillMdPath,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  logger.debug("Scanned skill root", {
+    rootPath: resolvedRoot,
+    candidatesFound: candidates.length
+  });
+  return candidates;
+}
+function scanAllSkillRoots(skillRoots) {
+  const allCandidates = [];
+  for (const root of skillRoots) {
+    const candidates = scanSkillRoot(root);
+    allCandidates.push(...candidates);
+  }
+  logger.info("Skill discovery complete", {
+    rootsScanned: skillRoots.length,
+    totalCandidates: allCandidates.length
+  });
+  return allCandidates;
+}
+
+// src/trust.ts
+var SCRIPT_PATH_PREFIX = "scripts/";
+var SCRIPT_PATH_EXACT = "scripts";
+function normalizeRootConfig(root) {
+  if (typeof root === "string") {
+    return { path: root, trust: "untrusted" };
+  }
+  return root;
+}
+function isScriptResource(resourcePath) {
+  let normalized = resourcePath.trim().replace(/\\/g, "/");
+  normalized = normalized.replace(/\/+/g, "/");
+  while (normalized.startsWith("./")) {
+    normalized = normalized.slice(2);
+  }
+  const lower = normalized.toLowerCase();
+  return lower === SCRIPT_PATH_EXACT || lower.startsWith(SCRIPT_PATH_PREFIX);
+}
+function evaluateTrustPolicy(resourcePath, trustLevel, allowUntrustedScripts = false) {
+  if (!isScriptResource(resourcePath)) {
+    return {
+      allowed: true,
+      reason: "not-script" /* NOT_SCRIPT */,
+      message: "Resource is not a script \u2014 no trust check required"
+    };
+  }
+  switch (trustLevel) {
+    case "workspace":
+      return {
+        allowed: true,
+        reason: "workspace-trust" /* WORKSPACE_TRUST */,
+        message: "Script allowed \u2014 skill root has workspace trust"
+      };
+    case "trusted":
+      return {
+        allowed: true,
+        reason: "trusted-root" /* TRUSTED_ROOT */,
+        message: "Script allowed \u2014 skill root is explicitly trusted"
+      };
+    case "untrusted":
+      if (allowUntrustedScripts) {
+        return {
+          allowed: true,
+          reason: "untrusted-script-allowed-override" /* UNTRUSTED_SCRIPT_ALLOWED */,
+          message: "Script from untrusted root allowed via allowUntrustedScripts override"
+        };
+      }
+      return {
+        allowed: false,
+        reason: "untrusted-script-denied" /* UNTRUSTED_SCRIPT_DENIED */,
+        message: `Script access denied \u2014 skill root is untrusted. Scripts from untrusted roots are blocked by default for security. To allow, set 'allowUntrustedScripts: true' in SkillRegistryConfig or promote the skill root to 'trusted' or 'workspace' trust level.`
+      };
+    default:
+      return {
+        allowed: false,
+        reason: "unknown-trust-level" /* UNKNOWN_TRUST_LEVEL */,
+        message: `Script access denied \u2014 trust level "${trustLevel}" is unknown and is treated as untrusted for security.`
+      };
+  }
+}
+
+// src/activation.ts
+var logger2 = core.createLogger("agentforge:skills:activation", { level: core.LogLevel.INFO });
+var activateSkillSchema = zod.z.object({
+  name: zod.z.string().describe('The name of the skill to activate (e.g., "code-review")')
+});
+var readSkillResourceSchema = zod.z.object({
+  name: zod.z.string().describe("The name of the skill that owns the resource"),
+  path: zod.z.string().describe('Relative path to the resource file within the skill directory (e.g., "references/GUIDE.md", "scripts/setup.sh")')
+});
+function resolveResourcePath(skillPath, resourcePath) {
+  if (path.isAbsolute(resourcePath)) {
+    return { success: false, error: "Absolute resource paths are not allowed" };
+  }
+  const segments = resourcePath.split(/[/\\]/);
+  if (segments.some((seg) => seg === "..")) {
+    return { success: false, error: "Path traversal is not allowed \u2014 resource paths must stay within the skill directory" };
+  }
+  const resolvedPath = path.resolve(skillPath, resourcePath);
+  const resolvedSkillPath = path.resolve(skillPath);
+  const rel = path.relative(resolvedSkillPath, resolvedPath);
+  if (rel.startsWith("..") || path.resolve(resolvedSkillPath, rel) !== resolvedPath) {
+    return { success: false, error: "Path traversal is not allowed \u2014 resource paths must stay within the skill directory" };
+  }
+  try {
+    const realSkillRoot = fs.realpathSync(resolvedSkillPath);
+    const realTarget = fs.realpathSync(resolvedPath);
+    const realRel = path.relative(realSkillRoot, realTarget);
+    if (realRel.startsWith("..") || path.isAbsolute(realRel)) {
+      return { success: false, error: "Symlink target escapes the skill directory \u2014 access denied" };
+    }
+  } catch {
+  }
+  return { success: true, resolvedPath };
+}
+function createActivateSkillTool(registry) {
+  return new core.ToolBuilder().name("activate-skill").description(
+    "Activate an Agent Skill by name, loading its full instructions. Returns the complete SKILL.md body content for the named skill. Use this when you see a relevant skill in <available_skills> and want to follow its instructions."
+  ).category(core.ToolCategory.SKILLS).tags(["skill", "activation", "agent-skills"]).schema(activateSkillSchema).implement(async ({ name }) => {
+    const skill = registry.get(name);
+    if (!skill) {
+      const availableNames = registry.getNames();
+      const suggestion = availableNames.length > 0 ? ` Available skills: ${availableNames.join(", ")}` : " No skills are currently registered.";
+      const errorMsg = `Skill "${name}" not found.${suggestion}`;
+      logger2.warn("Skill activation failed \u2014 not found", { name, availableCount: availableNames.length });
+      return errorMsg;
+    }
+    const skillMdPath = path.resolve(skill.skillPath, "SKILL.md");
+    try {
+      const content = fs.readFileSync(skillMdPath, "utf-8");
+      const body = extractBody(content);
+      logger2.info("Skill activated", {
+        name: skill.metadata.name,
+        skillPath: skill.skillPath,
+        bodyLength: body.length
+      });
+      registry.emitEvent("skill:activated" /* SKILL_ACTIVATED */, {
+        name: skill.metadata.name,
+        skillPath: skill.skillPath,
+        bodyLength: body.length
+      });
+      return body;
+    } catch (error) {
+      const errorMsg = `Failed to read skill "${name}" instructions: ${error instanceof Error ? error.message : String(error)}`;
+      logger2.error("Skill activation failed \u2014 read error", {
+        name,
+        skillPath: skill.skillPath,
+        error: error instanceof Error ? error.message : String(error)
+      });
+      return errorMsg;
+    }
+  }).build();
+}
+function createReadSkillResourceTool(registry) {
+  return new core.ToolBuilder().name("read-skill-resource").description(
+    "Read a resource file from an activated Agent Skill. Returns the content of a file within the skill directory (e.g., references/, scripts/, assets/). The path must be relative to the skill root and cannot traverse outside it."
+  ).category(core.ToolCategory.SKILLS).tags(["skill", "resource", "agent-skills"]).schema(readSkillResourceSchema).implement(async ({ name, path: resourcePath }) => {
+    const skill = registry.get(name);
+    if (!skill) {
+      const availableNames = registry.getNames();
+      const suggestion = availableNames.length > 0 ? ` Available skills: ${availableNames.join(", ")}` : " No skills are currently registered.";
+      const errorMsg = `Skill "${name}" not found.${suggestion}`;
+      logger2.warn("Skill resource load failed \u2014 skill not found", { name, resourcePath });
+      return errorMsg;
+    }
+    const pathResult = resolveResourcePath(skill.skillPath, resourcePath);
+    if (!pathResult.success) {
+      logger2.warn("Skill resource load blocked \u2014 path traversal", {
+        name,
+        resourcePath,
+        error: pathResult.error
+      });
+      return pathResult.error;
+    }
+    const policyDecision = evaluateTrustPolicy(
+      resourcePath,
+      skill.trustLevel,
+      registry.getAllowUntrustedScripts()
+    );
+    if (!policyDecision.allowed) {
+      logger2.warn("Skill resource load blocked \u2014 trust policy", {
+        name,
+        resourcePath,
+        trustLevel: skill.trustLevel,
+        reason: policyDecision.reason,
+        message: policyDecision.message
+      });
+      registry.emitEvent("trust:policy-denied" /* TRUST_POLICY_DENIED */, {
+        name: skill.metadata.name,
+        resourcePath,
+        trustLevel: skill.trustLevel,
+        reason: policyDecision.reason,
+        message: policyDecision.message
+      });
+      return policyDecision.message;
+    }
+    if (policyDecision.reason !== "not-script" /* NOT_SCRIPT */) {
+      logger2.info("Skill resource trust policy \u2014 allowed", {
+        name,
+        resourcePath,
+        trustLevel: skill.trustLevel,
+        reason: policyDecision.reason
+      });
+      registry.emitEvent("trust:policy-allowed" /* TRUST_POLICY_ALLOWED */, {
+        name: skill.metadata.name,
+        resourcePath,
+        trustLevel: skill.trustLevel,
+        reason: policyDecision.reason
+      });
+    }
+    try {
+      const content = fs.readFileSync(pathResult.resolvedPath, "utf-8");
+      logger2.info("Skill resource loaded", {
+        name: skill.metadata.name,
+        resourcePath,
+        resolvedPath: pathResult.resolvedPath,
+        contentLength: content.length
+      });
+      registry.emitEvent("skill:resource-loaded" /* SKILL_RESOURCE_LOADED */, {
+        name: skill.metadata.name,
+        resourcePath,
+        resolvedPath: pathResult.resolvedPath,
+        contentLength: content.length
+      });
+      return content;
+    } catch (error) {
+      const errorMsg = `Failed to read resource "${resourcePath}" from skill "${name}": ${error instanceof Error ? error.message : String(error)}`;
+      logger2.warn("Skill resource load failed \u2014 file not found or unreadable", {
+        name,
+        resourcePath,
+        error: error instanceof Error ? error.message : String(error)
+      });
+      return errorMsg;
+    }
+  }).build();
+}
+function createSkillActivationTools(registry) {
+  return [
+    createActivateSkillTool(registry),
+    createReadSkillResourceTool(registry)
+  ];
+}
+function extractBody(content) {
+  return matter__default.default(content).content.trim();
+}
+var logger3 = core.createLogger("agentforge:skills:registry", { level: core.LogLevel.INFO });
+var SkillRegistry = class {
+  skills = /* @__PURE__ */ new Map();
+  eventHandlers = /* @__PURE__ */ new Map();
+  config;
+  scanErrors = [];
+  /** Maps resolved root paths → trust levels for skill trust assignment */
+  rootTrustMap = /* @__PURE__ */ new Map();
+  /**
+   * Create a SkillRegistry and immediately scan configured roots for skills.
+   *
+   * @param config - Registry configuration with skill root paths
+   *
+   * @example
+   * ```ts
+   * const registry = new SkillRegistry({
+   *   skillRoots: ['.agentskills', '~/.agentskills', './project-skills'],
+   * });
+   * console.log(`Discovered ${registry.size()} skills`);
+   * ```
+   */
+  constructor(config) {
+    this.config = config;
+    this.discover();
+  }
+  /**
+   * Scan all configured roots and populate the registry.
+   *
+   * Called automatically during construction. Can be called again
+   * to re-scan (clears existing skills first).
+   */
+  discover() {
+    this.skills.clear();
+    this.scanErrors = [];
+    this.rootTrustMap.clear();
+    const normalizedRoots = this.config.skillRoots.map(normalizeRootConfig);
+    const plainPaths = normalizedRoots.map((r) => r.path);
+    for (const root of normalizedRoots) {
+      const resolvedPath = path.resolve(expandHome(root.path));
+      this.rootTrustMap.set(resolvedPath, root.trust);
+    }
+    const candidates = scanAllSkillRoots(plainPaths);
+    let successCount = 0;
+    let warningCount = 0;
+    for (const candidate of candidates) {
+      const result = parseSkillContent(candidate.content, candidate.dirName);
+      if (!result.success) {
+        warningCount++;
+        this.scanErrors.push({
+          path: candidate.skillPath,
+          error: result.error || "Unknown parse error"
+        });
+        this.emit("skill:warning" /* SKILL_WARNING */, {
+          skillPath: candidate.skillPath,
+          rootPath: candidate.rootPath,
+          error: result.error
+        });
+        logger3.warn("Skipping invalid skill", {
+          skillPath: candidate.skillPath,
+          error: result.error
+        });
+        continue;
+      }
+      const skill = {
+        metadata: result.metadata,
+        skillPath: candidate.skillPath,
+        rootPath: candidate.rootPath,
+        trustLevel: this.rootTrustMap.get(candidate.rootPath) ?? "untrusted"
+      };
+      if (this.skills.has(skill.metadata.name)) {
+        const existing = this.skills.get(skill.metadata.name);
+        warningCount++;
+        const warningMsg = `Duplicate skill name "${skill.metadata.name}" from "${candidate.rootPath}" \u2014 keeping version from "${existing.rootPath}" (first root takes precedence)`;
+        this.scanErrors.push({
+          path: candidate.skillPath,
+          error: warningMsg
+        });
+        this.emit("skill:warning" /* SKILL_WARNING */, {
+          skillPath: candidate.skillPath,
+          rootPath: candidate.rootPath,
+          duplicateOf: existing.skillPath,
+          error: warningMsg
+        });
+        logger3.warn("Duplicate skill name, keeping first", {
+          name: skill.metadata.name,
+          kept: existing.skillPath,
+          skipped: candidate.skillPath
+        });
+        continue;
+      }
+      this.skills.set(skill.metadata.name, skill);
+      successCount++;
+      this.emit("skill:discovered" /* SKILL_DISCOVERED */, skill);
+      logger3.debug("Skill discovered", {
+        name: skill.metadata.name,
+        description: skill.metadata.description.slice(0, 80),
+        skillPath: skill.skillPath
+      });
+    }
+    logger3.info("Skill registry populated", {
+      rootsScanned: this.config.skillRoots.length,
+      skillsDiscovered: successCount,
+      warnings: warningCount
+    });
+  }
+  // ─── Query API (parallel to ToolRegistry) ──────────────────────────────
+  /**
+   * Get a skill by name.
+   *
+   * @param name - The skill name
+   * @returns The skill, or undefined if not found
+   *
+   * @example
+   * ```ts
+   * const skill = registry.get('code-review');
+   * if (skill) {
+   *   console.log(skill.metadata.description);
+   * }
+   * ```
+   */
+  get(name) {
+    return this.skills.get(name);
+  }
+  /**
+   * Get all discovered skills.
+   *
+   * @returns Array of all skills
+   *
+   * @example
+   * ```ts
+   * const allSkills = registry.getAll();
+   * console.log(`Total skills: ${allSkills.length}`);
+   * ```
+   */
+  getAll() {
+    return Array.from(this.skills.values());
+  }
+  /**
+   * Check if a skill exists in the registry.
+   *
+   * @param name - The skill name
+   * @returns True if the skill exists
+   *
+   * @example
+   * ```ts
+   * if (registry.has('code-review')) {
+   *   console.log('Skill available!');
+   * }
+   * ```
+   */
+  has(name) {
+    return this.skills.has(name);
+  }
+  /**
+   * Get the number of discovered skills.
+   *
+   * @returns Number of skills in the registry
+   *
+   * @example
+   * ```ts
+   * console.log(`Registry has ${registry.size()} skills`);
+   * ```
+   */
+  size() {
+    return this.skills.size;
+  }
+  /**
+   * Get all skill names.
+   *
+   * @returns Array of skill names
+   */
+  getNames() {
+    return Array.from(this.skills.keys());
+  }
+  /**
+   * Get errors/warnings from the last scan.
+   *
+   * Useful for diagnostics and observability.
+   *
+   * @returns Array of scan errors with paths
+   */
+  getScanErrors() {
+    return this.scanErrors;
+  }
+  /**
+   * Check whether untrusted script access is allowed via config override.
+   *
+   * Used by activation tools to pass the override flag to trust policy checks.
+   *
+   * @returns True if `allowUntrustedScripts` is set in config
+   */
+  getAllowUntrustedScripts() {
+    return this.config.allowUntrustedScripts ?? false;
+  }
+  /**
+   * Get the `allowed-tools` list for a skill.
+   *
+   * Returns the `allowedTools` array from the skill's frontmatter metadata,
+   * enabling agents to filter their tool set based on what the skill expects.
+   *
+   * @param name - The skill name
+   * @returns Array of allowed tool names, or undefined if skill not found or field not set
+   *
+   * @example
+   * ```ts
+   * const allowed = registry.getAllowedTools('code-review');
+   * if (allowed) {
+   *   const filteredTools = allTools.filter(t => allowed.includes(t.name));
+   * }
+   * ```
+   */
+  getAllowedTools(name) {
+    const skill = this.skills.get(name);
+    return skill?.metadata.allowedTools;
+  }
+  // ─── Prompt Generation ─────────────────────────────────────────────────
+  /**
+   * Generate an `<available_skills>` XML block for system prompt injection.
+   *
+   * Returns an empty string when:
+   * - `config.enabled` is `false` (default) — agents operate with unmodified prompts
+   * - No skills match the filter criteria
+   *
+   * The output composes naturally with `toolRegistry.generatePrompt()` —
+   * simply concatenate both into the system prompt.
+   *
+   * @param options - Optional filtering (subset of skill names)
+   * @returns XML string or empty string
+   *
+   * @example
+   * ```ts
+   * // All skills
+   * const xml = registry.generatePrompt();
+   *
+   * // Subset for a focused agent
+   * const xml = registry.generatePrompt({ skills: ['code-review', 'testing'] });
+   *
+   * // Compose with tool prompt
+   * const systemPrompt = [
+   *   toolRegistry.generatePrompt(),
+   *   skillRegistry.generatePrompt(),
+   * ].filter(Boolean).join('\n\n');
+   * ```
+   */
+  generatePrompt(options) {
+    if (!this.config.enabled) {
+      logger3.debug("Skill prompt generation skipped (disabled)", {
+        enabled: this.config.enabled ?? false
+      });
+      return "";
+    }
+    let skills = this.getAll();
+    if (options?.skills && options.skills.length > 0) {
+      const requested = new Set(options.skills);
+      skills = skills.filter((s) => requested.has(s.metadata.name));
+    }
+    if (this.config.maxDiscoveredSkills !== void 0 && this.config.maxDiscoveredSkills >= 0) {
+      skills = skills.slice(0, this.config.maxDiscoveredSkills);
+    }
+    if (skills.length === 0) {
+      logger3.debug("Skill prompt generation produced empty result", {
+        totalDiscovered: this.size(),
+        filterApplied: !!(options?.skills && options.skills.length > 0),
+        maxCap: this.config.maxDiscoveredSkills
+      });
+      return "";
+    }
+    const skillEntries = skills.map((skill) => {
+      const lines = [
+        "  <skill>",
+        `    <name>${escapeXml(skill.metadata.name)}</name>`,
+        `    <description>${escapeXml(skill.metadata.description)}</description>`,
+        `    <location>${escapeXml(skill.skillPath)}</location>`,
+        "  </skill>"
+      ];
+      return lines.join("\n");
+    });
+    const xml = `<available_skills>
+${skillEntries.join("\n")}
+</available_skills>`;
+    const estimatedTokens = Math.ceil(xml.length / 4);
+    logger3.info("Skill prompt generated", {
+      skillCount: skills.length,
+      totalDiscovered: this.size(),
+      filterApplied: !!(options?.skills && options.skills.length > 0),
+      maxCap: this.config.maxDiscoveredSkills,
+      estimatedTokens,
+      xmlLength: xml.length
+    });
+    return xml;
+  }
+  // ─── Event System ──────────────────────────────────────────────────────
+  /**
+   * Register an event handler.
+   *
+   * @param event - The event to listen for
+   * @param handler - The handler function
+   *
+   * @example
+   * ```ts
+   * registry.on(SkillRegistryEvent.SKILL_DISCOVERED, (skill) => {
+   *   console.log('Found skill:', skill.metadata.name);
+   * });
+   * ```
+   */
+  on(event, handler) {
+    if (!this.eventHandlers.has(event)) {
+      this.eventHandlers.set(event, /* @__PURE__ */ new Set());
+    }
+    this.eventHandlers.get(event).add(handler);
+  }
+  /**
+   * Unregister an event handler.
+   *
+   * @param event - The event to stop listening for
+   * @param handler - The handler function to remove
+   */
+  off(event, handler) {
+    const handlers = this.eventHandlers.get(event);
+    if (handlers) {
+      handlers.delete(handler);
+    }
+  }
+  /**
+   * Emit an event to all registered handlers.
+   *
+   * @param event - The event to emit
+   * @param data - The event data
+   * @private
+   */
+  emit(event, data) {
+    const handlers = this.eventHandlers.get(event);
+    if (handlers) {
+      handlers.forEach((handler) => {
+        try {
+          handler(data);
+        } catch (error) {
+          logger3.error("Skill event handler error", {
+            event,
+            error: error instanceof Error ? error.message : String(error),
+            stack: error instanceof Error ? error.stack : void 0
+          });
+        }
+      });
+    }
+  }
+  /**
+   * Emit an event (public API for activation tools).
+   *
+   * Used by skill activation tools to emit `skill:activated` and
+   * `skill:resource-loaded` events through the registry's event system.
+   *
+   * @param event - The event to emit
+   * @param data - The event data
+   */
+  emitEvent(event, data) {
+    this.emit(event, data);
+  }
+  // ─── Tool Integration ────────────────────────────────────────────────
+  /**
+   * Create activation tools pre-wired to this registry instance.
+   *
+   * Returns `activate-skill` and `read-skill-resource` tools that
+   * agents can use to load skill instructions and resources on demand.
+   *
+   * @returns Array of [activate-skill, read-skill-resource] tools
+   *
+   * @example
+   * ```ts
+   * const agent = createReActAgent({
+   *   model: llm,
+   *   tools: [
+   *     ...toolRegistry.toLangChainTools(),
+   *     ...skillRegistry.toActivationTools(),
+   *   ],
+   * });
+   * ```
+   */
+  toActivationTools() {
+    return createSkillActivationTools(this);
+  }
+};
+function escapeXml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+
+exports.SkillRegistry = SkillRegistry;
+exports.SkillRegistryEvent = SkillRegistryEvent;
+exports.TrustPolicyReason = TrustPolicyReason;
+exports.createActivateSkillTool = createActivateSkillTool;
+exports.createReadSkillResourceTool = createReadSkillResourceTool;
+exports.createSkillActivationTools = createSkillActivationTools;
+exports.evaluateTrustPolicy = evaluateTrustPolicy;
+exports.expandHome = expandHome;
+exports.isScriptResource = isScriptResource;
+exports.normalizeRootConfig = normalizeRootConfig;
+exports.parseSkillContent = parseSkillContent;
+exports.resolveResourcePath = resolveResourcePath;
+exports.scanAllSkillRoots = scanAllSkillRoots;
+exports.scanSkillRoot = scanSkillRoot;
+exports.validateSkillDescription = validateSkillDescription;
+exports.validateSkillName = validateSkillName;
+exports.validateSkillNameMatchesDir = validateSkillNameMatchesDir;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map