@agentforge/skills 0.16.56 → 0.16.58

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { z } from 'zod';
 import { Tool } from '@agentforge/core';
+import { z } from 'zod';
 
 /**
  * Skill System Types
@@ -299,26 +299,6 @@ declare function scanSkillRoot(rootPath: string): SkillCandidate[];
  */
 declare function scanAllSkillRoots(skillRoots: string[]): SkillCandidate[];
 
-/**
- * Skill Activation Tools
- *
- * Provides `activate-skill` and `read-skill-resource` tools built with
- * the AgentForge tool builder API. These tools enable agents to load
- * skill instructions on demand and access skill resources at runtime.
- *
- * @see https://agentskills.io/specification
- *
- * @example
- * ```ts
- * const [activateSkill, readSkillResource] = createSkillActivationTools(registry);
- * // activateSkill       — load full SKILL.md body
- * // readSkillResource   — load a resource file from a skill
- *
- * // Or use the convenience method:
- * const [activateSkill, readSkillResource] = registry.toActivationTools();
- * ```
- */
-
 declare const activateSkillSchema: z.ZodObject<{
     name: z.ZodString;
 }, "strip", z.ZodTypeAny, {
@@ -336,6 +316,18 @@ declare const readSkillResourceSchema: z.ZodObject<{
     name: string;
     path: string;
 }>;
+
+/**
+ * Create the `activate-skill` tool bound to a registry instance.
+ *
+ * Resolves the skill by name, reads the full SKILL.md file, and returns
+ * the body content (below frontmatter).
+ *
+ * @param registry - The SkillRegistry to resolve skills from
+ * @returns An AgentForge Tool
+ */
+declare function createActivateSkillTool(registry: SkillRegistry): Tool<z.infer<typeof activateSkillSchema>, string>;
+
 /**
  * Resolve a resource path within a skill root, blocking path traversal.
  *
@@ -350,16 +342,7 @@ declare function resolveResourcePath(skillPath: string, resourcePath: string): {
     success: false;
     error: string;
 };
-/**
- * Create the `activate-skill` tool bound to a registry instance.
- *
- * Resolves the skill by name, reads the full SKILL.md file, and returns
- * the body content (below frontmatter).
- *
- * @param registry - The SkillRegistry to resolve skills from
- * @returns An AgentForge Tool
- */
-declare function createActivateSkillTool(registry: SkillRegistry): Tool<z.infer<typeof activateSkillSchema>, string>;
+
 /**
  * Create the `read-skill-resource` tool bound to a registry instance.
  *
@@ -370,6 +353,27 @@ declare function createActivateSkillTool(registry: SkillRegistry): Tool<z.infer<
  * @returns An AgentForge Tool
  */
 declare function createReadSkillResourceTool(registry: SkillRegistry): Tool<z.infer<typeof readSkillResourceSchema>, string>;
+
+/**
+ * Skill Activation Tools
+ *
+ * Provides `activate-skill` and `read-skill-resource` tools built with
+ * the AgentForge tool builder API. These tools enable agents to load
+ * skill instructions on demand and access skill resources at runtime.
+ *
+ * @see https://agentskills.io/specification
+ *
+ * @example
+ * ```ts
+ * const [activateSkill, readSkillResource] = createSkillActivationTools(registry);
+ * // activateSkill       — load full SKILL.md body
+ * // readSkillResource   — load a resource file from a skill
+ *
+ * // Or use the convenience method:
+ * const [activateSkill, readSkillResource] = registry.toActivationTools();
+ * ```
+ */
+
 /**
  * Create both skill activation tools bound to a registry instance.
  *

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { z } from 'zod';
 import { Tool } from '@agentforge/core';
+import { z } from 'zod';
 
 /**
  * Skill System Types
@@ -299,26 +299,6 @@ declare function scanSkillRoot(rootPath: string): SkillCandidate[];
  */
 declare function scanAllSkillRoots(skillRoots: string[]): SkillCandidate[];
 
-/**
- * Skill Activation Tools
- *
- * Provides `activate-skill` and `read-skill-resource` tools built with
- * the AgentForge tool builder API. These tools enable agents to load
- * skill instructions on demand and access skill resources at runtime.
- *
- * @see https://agentskills.io/specification
- *
- * @example
- * ```ts
- * const [activateSkill, readSkillResource] = createSkillActivationTools(registry);
- * // activateSkill       — load full SKILL.md body
- * // readSkillResource   — load a resource file from a skill
- *
- * // Or use the convenience method:
- * const [activateSkill, readSkillResource] = registry.toActivationTools();
- * ```
- */
-
 declare const activateSkillSchema: z.ZodObject<{
     name: z.ZodString;
 }, "strip", z.ZodTypeAny, {
@@ -336,6 +316,18 @@ declare const readSkillResourceSchema: z.ZodObject<{
     name: string;
     path: string;
 }>;
+
+/**
+ * Create the `activate-skill` tool bound to a registry instance.
+ *
+ * Resolves the skill by name, reads the full SKILL.md file, and returns
+ * the body content (below frontmatter).
+ *
+ * @param registry - The SkillRegistry to resolve skills from
+ * @returns An AgentForge Tool
+ */
+declare function createActivateSkillTool(registry: SkillRegistry): Tool<z.infer<typeof activateSkillSchema>, string>;
+
 /**
  * Resolve a resource path within a skill root, blocking path traversal.
  *
@@ -350,16 +342,7 @@ declare function resolveResourcePath(skillPath: string, resourcePath: string): {
     success: false;
     error: string;
 };
-/**
- * Create the `activate-skill` tool bound to a registry instance.
- *
- * Resolves the skill by name, reads the full SKILL.md file, and returns
- * the body content (below frontmatter).
- *
- * @param registry - The SkillRegistry to resolve skills from
- * @returns An AgentForge Tool
- */
-declare function createActivateSkillTool(registry: SkillRegistry): Tool<z.infer<typeof activateSkillSchema>, string>;
+
 /**
  * Create the `read-skill-resource` tool bound to a registry instance.
  *
@@ -370,6 +353,27 @@ declare function createActivateSkillTool(registry: SkillRegistry): Tool<z.infer<
  * @returns An AgentForge Tool
  */
 declare function createReadSkillResourceTool(registry: SkillRegistry): Tool<z.infer<typeof readSkillResourceSchema>, string>;
+
+/**
+ * Skill Activation Tools
+ *
+ * Provides `activate-skill` and `read-skill-resource` tools built with
+ * the AgentForge tool builder API. These tools enable agents to load
+ * skill instructions on demand and access skill resources at runtime.
+ *
+ * @see https://agentskills.io/specification
+ *
+ * @example
+ * ```ts
+ * const [activateSkill, readSkillResource] = createSkillActivationTools(registry);
+ * // activateSkill       — load full SKILL.md body
+ * // readSkillResource   — load a resource file from a skill
+ *
+ * // Or use the convenience method:
+ * const [activateSkill, readSkillResource] = registry.toActivationTools();
+ * ```
+ */
+
 /**
  * Create both skill activation tools bound to a registry instance.
  *

package/dist/index.js

@@ -211,6 +211,65 @@ function scanAllSkillRoots(skillRoots) {
   });
   return allCandidates;
 }
+function extractBody(content) {
+  return matter(content).content.trim();
+}
+var activateSkillSchema = z.object({
+  name: z.string().describe('The name of the skill to activate (e.g., "code-review")')
+});
+var readSkillResourceSchema = z.object({
+  name: z.string().describe("The name of the skill that owns the resource"),
+  path: z.string().describe('Relative path to the resource file within the skill directory (e.g., "references/GUIDE.md", "scripts/setup.sh")')
+});
+var activationLogger = createLogger("agentforge:skills:activation", {
+  level: LogLevel.INFO
+});
+function buildMissingSkillMessage(registry, name) {
+  const availableNames = registry.getNames();
+  const suggestion = availableNames.length > 0 ? ` Available skills: ${availableNames.join(", ")}` : " No skills are currently registered.";
+  return {
+    availableCount: availableNames.length,
+    errorMessage: `Skill "${name}" not found.${suggestion}`
+  };
+}
+
+// src/activation-activate-tool.ts
+function createActivateSkillTool(registry) {
+  return new 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(ToolCategory.SKILLS).tags(["skill", "activation", "agent-skills"]).schema(activateSkillSchema).implement(async ({ name }) => {
+    const skill = registry.get(name);
+    if (!skill) {
+      const { availableCount, errorMessage } = buildMissingSkillMessage(registry, name);
+      activationLogger.warn("Skill activation failed \u2014 not found", { name, availableCount });
+      return errorMessage;
+    }
+    const skillMdPath = resolve(skill.skillPath, "SKILL.md");
+    try {
+      const content = readFileSync(skillMdPath, "utf-8");
+      const body = extractBody(content);
+      activationLogger.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 message = error instanceof Error ? error.message : String(error);
+      activationLogger.error("Skill activation failed \u2014 read error", {
+        name,
+        skillPath: skill.skillPath,
+        error: message
+      });
+      return `Failed to read skill "${name}" instructions: ${message}`;
+    }
+  }).build();
+}
 
 // src/trust.ts
 var SCRIPT_PATH_PREFIX = "scripts/";
@@ -272,16 +331,6 @@ function evaluateTrustPolicy(resourcePath, trustLevel, allowUntrustedScripts = f
       };
   }
 }
-
-// src/activation.ts
-var logger2 = createLogger("agentforge:skills:activation", { level: LogLevel.INFO });
-var activateSkillSchema = z.object({
-  name: z.string().describe('The name of the skill to activate (e.g., "code-review")')
-});
-var readSkillResourceSchema = z.object({
-  name: z.string().describe("The name of the skill that owns the resource"),
-  path: 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 (isAbsolute(resourcePath)) {
     return { success: false, error: "Absolute resource paths are not allowed" };
@@ -307,59 +356,21 @@ function resolveResourcePath(skillPath, resourcePath) {
   }
   return { success: true, resolvedPath };
 }
-function createActivateSkillTool(registry) {
-  return new 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(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 = resolve(skill.skillPath, "SKILL.md");
-    try {
-      const content = 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();
-}
+
+// src/activation-resource-tool.ts
 function createReadSkillResourceTool(registry) {
   return new 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(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 { errorMessage } = buildMissingSkillMessage(registry, name);
+      activationLogger.warn("Skill resource load failed \u2014 skill not found", { name, resourcePath });
+      return errorMessage;
     }
     const pathResult = resolveResourcePath(skill.skillPath, resourcePath);
     if (!pathResult.success) {
-      logger2.warn("Skill resource load blocked \u2014 path traversal", {
+      activationLogger.warn("Skill resource load blocked \u2014 path traversal", {
         name,
         resourcePath,
         error: pathResult.error
@@ -372,7 +383,7 @@ function createReadSkillResourceTool(registry) {
       registry.getAllowUntrustedScripts()
     );
     if (!policyDecision.allowed) {
-      logger2.warn("Skill resource load blocked \u2014 trust policy", {
+      activationLogger.warn("Skill resource load blocked \u2014 trust policy", {
         name,
         resourcePath,
         trustLevel: skill.trustLevel,
@@ -389,7 +400,7 @@ function createReadSkillResourceTool(registry) {
       return policyDecision.message;
     }
     if (policyDecision.reason !== "not-script" /* NOT_SCRIPT */) {
-      logger2.info("Skill resource trust policy \u2014 allowed", {
+      activationLogger.info("Skill resource trust policy \u2014 allowed", {
         name,
         resourcePath,
         trustLevel: skill.trustLevel,
@@ -404,7 +415,7 @@ function createReadSkillResourceTool(registry) {
     }
     try {
       const content = readFileSync(pathResult.resolvedPath, "utf-8");
-      logger2.info("Skill resource loaded", {
+      activationLogger.info("Skill resource loaded", {
         name: skill.metadata.name,
         resourcePath,
         resolvedPath: pathResult.resolvedPath,
@@ -418,26 +429,25 @@ function createReadSkillResourceTool(registry) {
       });
       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", {
+      const message = error instanceof Error ? error.message : String(error);
+      activationLogger.warn("Skill resource load failed \u2014 file not found or unreadable", {
         name,
         resourcePath,
-        error: error instanceof Error ? error.message : String(error)
+        error: message
       });
-      return errorMsg;
+      return `Failed to read resource "${resourcePath}" from skill "${name}": ${message}`;
     }
   }).build();
 }
+
+// src/activation.ts
 function createSkillActivationTools(registry) {
   return [
     createActivateSkillTool(registry),
     createReadSkillResourceTool(registry)
   ];
 }
-function extractBody(content) {
-  return matter(content).content.trim();
-}
-var logger3 = createLogger("agentforge:skills:registry", { level: LogLevel.INFO });
+var logger2 = createLogger("agentforge:skills:registry", { level: LogLevel.INFO });
 function discoverSkills(config, skills, rootTrustMap, emit) {
   skills.clear();
   rootTrustMap.clear();
@@ -461,7 +471,7 @@ function discoverSkills(config, skills, rootTrustMap, emit) {
         rootPath: candidate.rootPath,
         error: result.error
       });
-      logger3.warn("Skipping invalid skill", {
+      logger2.warn("Skipping invalid skill", {
         skillPath: candidate.skillPath,
         ...result.error ? { error: result.error } : {}
       });
@@ -484,7 +494,7 @@ function discoverSkills(config, skills, rootTrustMap, emit) {
         duplicateOf: existing.skillPath,
         error: warningMessage
       });
-      logger3.warn("Duplicate skill name, keeping first", {
+      logger2.warn("Duplicate skill name, keeping first", {
         name: skill.metadata.name,
         kept: existing.skillPath,
         skipped: candidate.skillPath
@@ -494,13 +504,13 @@ function discoverSkills(config, skills, rootTrustMap, emit) {
     skills.set(skill.metadata.name, skill);
     successCount++;
     emit("skill:discovered" /* SKILL_DISCOVERED */, skill);
-    logger3.debug("Skill discovered", {
+    logger2.debug("Skill discovered", {
       name: skill.metadata.name,
       description: skill.metadata.description.slice(0, 80),
       skillPath: skill.skillPath
     });
   }
-  logger3.info("Skill registry populated", {
+  logger2.info("Skill registry populated", {
     rootsScanned: config.skillRoots.length,
     skillsDiscovered: successCount,
     warnings: warningCount
@@ -510,7 +520,7 @@ function discoverSkills(config, skills, rootTrustMap, emit) {
 function recordScanError(scanErrors, path, error) {
   scanErrors.push({ path, error });
 }
-var logger4 = createLogger("agentforge:skills:registry", { level: LogLevel.INFO });
+var logger3 = createLogger("agentforge:skills:registry", { level: LogLevel.INFO });
 function addRegistryEventHandler(eventHandlers, event, handler) {
   if (!eventHandlers.has(event)) {
     eventHandlers.set(event, /* @__PURE__ */ new Set());
@@ -532,7 +542,7 @@ function emitRegistryEvent(eventHandlers, event, data) {
     try {
       handler(data);
     } catch (error) {
-      logger4.error("Skill event handler error", {
+      logger3.error("Skill event handler error", {
         event,
         error: error instanceof Error ? error.message : String(error),
         ...error instanceof Error && error.stack ? { stack: error.stack } : {}
@@ -540,10 +550,10 @@ function emitRegistryEvent(eventHandlers, event, data) {
     }
   });
 }
-var logger5 = createLogger("agentforge:skills:registry", { level: LogLevel.INFO });
+var logger4 = createLogger("agentforge:skills:registry", { level: LogLevel.INFO });
 function generateSkillPrompt(config, allSkills, totalDiscovered, options) {
   if (!config.enabled) {
-    logger5.debug("Skill prompt generation skipped (disabled)", {
+    logger4.debug("Skill prompt generation skipped (disabled)", {
       enabled: config.enabled ?? false
     });
     return "";
@@ -557,7 +567,7 @@ function generateSkillPrompt(config, allSkills, totalDiscovered, options) {
     skills = skills.slice(0, config.maxDiscoveredSkills);
   }
   if (skills.length === 0) {
-    logger5.debug("Skill prompt generation produced empty result", {
+    logger4.debug("Skill prompt generation produced empty result", {
       totalDiscovered,
       filterApplied: !!(options?.skills && options.skills.length > 0),
       ...config.maxDiscoveredSkills !== void 0 ? { maxCap: config.maxDiscoveredSkills } : {}
@@ -568,7 +578,7 @@ function generateSkillPrompt(config, allSkills, totalDiscovered, options) {
 ${skills.map(renderSkillEntry).join("\n")}
 </available_skills>`;
   const estimatedTokens = Math.ceil(xml.length / 4);
-  logger5.info("Skill prompt generated", {
+  logger4.info("Skill prompt generated", {
     skillCount: skills.length,
     totalDiscovered,
     filterApplied: !!(options?.skills && options.skills.length > 0),