@juspay/neurolink 9.84.2 → 9.85.0

package/dist/cli/factories/commandFactory.d.ts

@@ -117,6 +117,12 @@ export declare class CLICommandFactory {
      * Create memory commands
      */
     static createMemoryCommands(): CommandModule;
+    /**
+     * Create skills commands — manage the local skills store
+     * (list / show / search / create / delete). The store directory comes
+     * from --skills-dir, NEUROLINK_SKILLS_DIR, or defaults to ./skills.
+     */
+    static createSkillsCommands(): CommandModule;
     /**
      * Create config commands
      */
@@ -235,6 +241,17 @@ export declare class CLICommandFactory {
     /**
      * Execute memory stats command
      */
+    /**
+     * Resolve a standalone SkillsManager for the `skills` command group.
+     * Directory precedence: --skills-dir > NEUROLINK_SKILLS_DIR > ./skills.
+     * Cache is disabled so every command sees the directory's current state.
+     */
+    private static resolveSkillsManagerForCli;
+    private static executeSkillsList;
+    private static executeSkillsShow;
+    private static executeSkillsSearch;
+    private static executeSkillsCreate;
+    private static executeSkillsDelete;
     private static executeMemoryStats;
     /**
      * Execute memory history command

package/dist/cli/factories/commandFactory.js

@@ -12,6 +12,8 @@ import { logger } from "../../lib/utils/logger.js";
 import { createThinkingConfigFromRecord } from "../../lib/utils/thinkingConfig.js";
 import { buildToolRoutingConfigFromCli } from "../utils/toolRoutingFlags.js";
 import { buildClassifierRouterConfigFromCli } from "../utils/classifierRouterFlags.js";
+import { buildSkillsConfigFromCli } from "../utils/skillsFlags.js";
+import { SkillsManager } from "../../lib/skills/skillsManager.js";
 import { configManager } from "../commands/config.js";
 import { MCPCommandFactory } from "../commands/mcp.js";
 import { ModelsCommandFactory } from "../commands/models.js";
@@ -711,6 +713,14 @@ export class CLICommandFactory {
             description: "Minimum response length (characters)",
             alias: "output-min-length",
         },
+        // Skills options
+        skillsDir: {
+            type: "string",
+            description: "Directory of skills (SOPs/playbooks) to make available to the AI. " +
+                "Supports <id>.json, <name>.md, and <name>/SKILL.md layouts. " +
+                "Also settable via NEUROLINK_SKILLS_DIR.",
+            alias: "skills-dir",
+        },
     };
     // Helper method to build options for commands
     static buildOptions(yargs, additionalOptions = {}) {
@@ -963,6 +973,8 @@ export class CLICommandFactory {
             classifierModelRegion: argv.classifierModelRegion,
             classifierPool: argv.classifierPool,
             classifierTimeout: argv.classifierTimeout,
+            // Skills flag — constructor-level config (see note above).
+            skillsDir: argv.skillsDir,
         };
     }
     /**
@@ -1651,6 +1663,77 @@ export class CLICommandFactory {
             handler: () => { }, // No-op handler as subcommands handle everything
         };
     }
+    /**
+     * Create skills commands — manage the local skills store
+     * (list / show / search / create / delete). The store directory comes
+     * from --skills-dir, NEUROLINK_SKILLS_DIR, or defaults to ./skills.
+     */
+    static createSkillsCommands() {
+        return {
+            command: "skills <subcommand>",
+            describe: "Manage skills (SOPs/playbooks the AI can follow)",
+            builder: (yargs) => {
+                return yargs
+                    .command("list", "List all active skills (index only, no instructions)", (y) => CLICommandFactory.buildOptions(y)
+                    .example("$0 skills list --skills-dir ./skills", "List skills")
+                    .example("$0 skills list --format json", "Export as JSON"), async (argv) => await CLICommandFactory.executeSkillsList(argv))
+                    .command("show <skill>", "Show one skill including its full instructions", (y) => CLICommandFactory.buildOptions(y)
+                    .positional("skill", {
+                    type: "string",
+                    description: "Skill id or exact name",
+                    demandOption: true,
+                })
+                    .example("$0 skills show refund_dispute_escalation", "Show a skill by name"), async (argv) => await CLICommandFactory.executeSkillsShow(argv))
+                    .command("search <query>", "Search skills by keyword (matches name and description)", (y) => CLICommandFactory.buildOptions(y)
+                    .positional("query", {
+                    type: "string",
+                    description: "Keyword to match",
+                    demandOption: true,
+                })
+                    .option("tag", {
+                    type: "string",
+                    description: "Tag filter applied on top of the keyword",
+                })
+                    .example('$0 skills search "refund"', "Find refund skills"), async (argv) => await CLICommandFactory.executeSkillsSearch(argv))
+                    .command("create", "Create a new skill in the store", (y) => CLICommandFactory.buildOptions(y)
+                    .option("name", {
+                    type: "string",
+                    description: "Machine-friendly unique name (snake_case)",
+                    demandOption: true,
+                })
+                    .option("description", {
+                    type: "string",
+                    description: "When this skill applies (used for matching)",
+                    demandOption: true,
+                })
+                    .option("instructions", {
+                    type: "string",
+                    description: "Full instructions text",
+                })
+                    .option("instructions-file", {
+                    type: "string",
+                    description: "Read instructions from a file",
+                })
+                    .option("display-name", {
+                    type: "string",
+                    description: "Human-readable display name",
+                })
+                    .option("tags", {
+                    type: "array",
+                    string: true,
+                    description: "Domain tags",
+                })
+                    .example('$0 skills create --name deploy_sop --description "How to deploy" --instructions-file ./sop.md', "Create from a file"), async (argv) => await CLICommandFactory.executeSkillsCreate(argv))
+                    .command("delete <skill>", "Soft-delete (deprecate) a skill", (y) => CLICommandFactory.buildOptions(y).positional("skill", {
+                    type: "string",
+                    description: "Skill id or exact name",
+                    demandOption: true,
+                }), async (argv) => await CLICommandFactory.executeSkillsDelete(argv))
+                    .demandCommand(1, "Please specify a skills subcommand");
+            },
+            handler: () => { }, // No-op handler as subcommands handle everything
+        };
+    }
     /**
      * Create config commands
      */
@@ -1900,6 +1983,12 @@ export class CLICommandFactory {
                         },
                     };
                 }
+                // Inject skills config (--skills-dir / NEUROLINK_SKILLS_DIR) before
+                // the loop session constructs its NeuroLink instance.
+                const loopSkillsConfig = buildSkillsConfigFromCli(argv);
+                if (loopSkillsConfig) {
+                    globalSession.setSkillsConfig(loopSkillsConfig);
+                }
                 // Handle --list-conversations option
                 if (listConversations) {
                     const { ConversationSelector } = await import("../loop/conversationSelector.js");
@@ -2399,6 +2488,11 @@ export class CLICommandFactory {
             if (classifierRouterConfig) {
                 globalSession.setClassifierRouterConfig(classifierRouterConfig);
             }
+            // Inject skills config (--skills-dir / NEUROLINK_SKILLS_DIR) before SDK construction.
+            const skillsConfig = buildSkillsConfigFromCli(options);
+            if (skillsConfig) {
+                globalSession.setSkillsConfig(skillsConfig);
+            }
             // Initialize SDK and session
             const sdk = globalSession.getOrCreateNeuroLink();
             const sessionVariables = CLICommandFactory.normalizeLoopSessionVariables(globalSession.getSessionVariables());
@@ -2667,6 +2761,11 @@ export class CLICommandFactory {
         if (classifierRouterConfig) {
             globalSession.setClassifierRouterConfig(classifierRouterConfig);
         }
+        // Inject skills config (--skills-dir / NEUROLINK_SKILLS_DIR) before SDK construction.
+        const skillsConfig = buildSkillsConfigFromCli(options);
+        if (skillsConfig) {
+            globalSession.setSkillsConfig(skillsConfig);
+        }
         const sdk = globalSession.getOrCreateNeuroLink();
         const sessionVariables = CLICommandFactory.normalizeLoopSessionVariables(globalSession.getSessionVariables());
         const enhancedOptions = { ...options, ...sessionVariables };
@@ -3182,6 +3281,11 @@ export class CLICommandFactory {
             if (classifierRouterConfig) {
                 globalSession.setClassifierRouterConfig(classifierRouterConfig);
             }
+            // Inject skills config (--skills-dir / NEUROLINK_SKILLS_DIR) before SDK construction.
+            const skillsConfig = buildSkillsConfigFromCli(options);
+            if (skillsConfig) {
+                globalSession.setSkillsConfig(skillsConfig);
+            }
             const sdk = globalSession.getOrCreateNeuroLink();
             const sessionVariables = CLICommandFactory.normalizeLoopSessionVariables(globalSession.getSessionVariables());
             const enhancedOptions = { ...options, ...sessionVariables };
@@ -3339,6 +3443,156 @@ export class CLICommandFactory {
     /**
      * Execute memory stats command
      */
+    /**
+     * Resolve a standalone SkillsManager for the `skills` command group.
+     * Directory precedence: --skills-dir > NEUROLINK_SKILLS_DIR > ./skills.
+     * Cache is disabled so every command sees the directory's current state.
+     */
+    static resolveSkillsManagerForCli(argv) {
+        const raw = argv.skillsDir;
+        const dir = (typeof raw === "string" && raw.trim()) ||
+            process.env.NEUROLINK_SKILLS_DIR?.trim() ||
+            "./skills";
+        return new SkillsManager({
+            enabled: true,
+            storage: { type: "filesystem", path: dir },
+            indexCacheTtlMs: 0,
+        });
+    }
+    static async executeSkillsList(argv) {
+        const options = CLICommandFactory.processOptions(argv);
+        try {
+            const manager = CLICommandFactory.resolveSkillsManagerForCli(argv);
+            const skills = await manager.list();
+            if (options.format === "json") {
+                CLICommandFactory.handleOutput({ skills, count: skills.length }, options);
+                return;
+            }
+            if (skills.length === 0) {
+                logger.always(chalk.yellow("No active skills found."));
+                return;
+            }
+            logger.always(chalk.blue(`🧩 Skills (${skills.length}):`));
+            for (const skill of skills) {
+                const tags = skill.tags?.length ? ` [${skill.tags.join(", ")}]` : "";
+                logger.always(`   ${chalk.bold(skill.name)} — ${skill.description}${tags}`);
+            }
+        }
+        catch (error) {
+            handleError(error, "Skills list");
+        }
+    }
+    static async executeSkillsShow(argv) {
+        const options = CLICommandFactory.processOptions(argv);
+        try {
+            const manager = CLICommandFactory.resolveSkillsManagerForCli(argv);
+            const skill = await manager.get(argv.skill);
+            if (!skill) {
+                logger.always(chalk.yellow(`Skill "${argv.skill}" not found.`));
+                process.exitCode = 1;
+                return;
+            }
+            if (options.format === "json") {
+                CLICommandFactory.handleOutput(skill, options);
+                return;
+            }
+            logger.always(chalk.blue(`🧩 ${skill.displayName || skill.name}`));
+            logger.always(`   id: ${skill.id}  version: ${skill.version ?? 1}`);
+            logger.always(`   ${skill.description}`);
+            if (skill.tags?.length) {
+                logger.always(`   tags: ${skill.tags.join(", ")}`);
+            }
+            logger.always("");
+            logger.always(skill.instructions);
+        }
+        catch (error) {
+            handleError(error, "Skills show");
+        }
+    }
+    static async executeSkillsSearch(argv) {
+        const options = CLICommandFactory.processOptions(argv);
+        try {
+            const manager = CLICommandFactory.resolveSkillsManagerForCli(argv);
+            const matches = await manager.search({
+                query: argv.query,
+                ...(argv.tag ? { tag: argv.tag } : {}),
+            });
+            if (options.format === "json") {
+                CLICommandFactory.handleOutput({ skills: matches, count: matches.length }, options);
+                return;
+            }
+            if (matches.length === 0) {
+                logger.always(chalk.yellow(`No skills match "${argv.query}".`));
+                return;
+            }
+            logger.always(chalk.blue(`🔎 ${matches.length} match(es):`));
+            for (const skill of matches) {
+                logger.always(`   ${chalk.bold(skill.name)} — ${skill.description}`);
+            }
+            logger.always("");
+            logger.always("Use `neurolink skills show <name>` for full instructions.");
+        }
+        catch (error) {
+            handleError(error, "Skills search");
+        }
+    }
+    static async executeSkillsCreate(argv) {
+        const options = CLICommandFactory.processOptions(argv);
+        try {
+            let instructions = argv.instructions;
+            if (!instructions && argv.instructionsFile) {
+                instructions = fs.readFileSync(argv.instructionsFile, "utf-8");
+            }
+            if (!instructions?.trim()) {
+                logger.always(chalk.red("Provide skill instructions via --instructions or --instructions-file."));
+                process.exitCode = 1;
+                return;
+            }
+            const manager = CLICommandFactory.resolveSkillsManagerForCli(argv);
+            const result = await manager.requestMutation({
+                type: "create",
+                skill: {
+                    name: argv.name,
+                    description: argv.description,
+                    instructions,
+                    ...(argv.displayName ? { displayName: argv.displayName } : {}),
+                    ...(argv.tags?.length ? { tags: argv.tags.map(String) } : {}),
+                },
+            });
+            if (options.format === "json") {
+                CLICommandFactory.handleOutput(result, options);
+                return;
+            }
+            logger.always(chalk.green(`✅ Skill "${argv.name}" created (id: ${result.skill?.id}).`));
+        }
+        catch (error) {
+            handleError(error, "Skills create");
+        }
+    }
+    static async executeSkillsDelete(argv) {
+        const options = CLICommandFactory.processOptions(argv);
+        try {
+            const manager = CLICommandFactory.resolveSkillsManagerForCli(argv);
+            const existing = await manager.get(argv.skill);
+            if (!existing) {
+                logger.always(chalk.yellow(`Skill "${argv.skill}" not found.`));
+                process.exitCode = 1;
+                return;
+            }
+            const result = await manager.requestMutation({
+                type: "delete",
+                skillId: existing.id,
+            });
+            if (options.format === "json") {
+                CLICommandFactory.handleOutput(result, options);
+                return;
+            }
+            logger.always(chalk.green(`✅ Skill "${existing.name}" deprecated (soft-deleted).`));
+        }
+        catch (error) {
+            handleError(error, "Skills delete");
+        }
+    }
     static async executeMemoryStats(argv) {
         const options = CLICommandFactory.processOptions(argv);
         const spinner = options.quiet

package/dist/cli/parser.js

@@ -161,6 +161,8 @@ export function initializeCliParser() {
         .command(CLICommandFactory.createConfigCommands())
         // Memory Command Group - Using CLICommandFactory
         .command(CLICommandFactory.createMemoryCommands())
+        // Skills Command Group - Using CLICommandFactory
+        .command(CLICommandFactory.createSkillsCommands())
         // Get Best Provider Command - Using CLICommandFactory
         .command(CLICommandFactory.createBestProviderCommand())
         // Validate Command (alias for config validate)

package/dist/cli/utils/skillsFlags.d.ts

@@ -0,0 +1,10 @@
+/**
+ * CLI → SkillsConfig mapping, following the toolRoutingFlags /
+ * classifierRouterFlags pattern.
+ *
+ * `--skills-dir <path>` (or NEUROLINK_SKILLS_DIR) enables skills with a
+ * filesystem store for generate / stream / batch / loop runs. Returns null
+ * when neither is provided so the SDK stays skills-free by default.
+ */
+import type { SkillsConfig } from "../../lib/types/index.js";
+export declare function buildSkillsConfigFromCli(options: Record<string, unknown>): SkillsConfig | null;

package/dist/cli/utils/skillsFlags.js

@@ -0,0 +1,22 @@
+/**
+ * CLI → SkillsConfig mapping, following the toolRoutingFlags /
+ * classifierRouterFlags pattern.
+ *
+ * `--skills-dir <path>` (or NEUROLINK_SKILLS_DIR) enables skills with a
+ * filesystem store for generate / stream / batch / loop runs. Returns null
+ * when neither is provided so the SDK stays skills-free by default.
+ */
+export function buildSkillsConfigFromCli(options) {
+    const dir = (typeof options.skillsDir === "string" && options.skillsDir.trim()) ||
+        (typeof process.env.NEUROLINK_SKILLS_DIR === "string" &&
+            process.env.NEUROLINK_SKILLS_DIR.trim()) ||
+        "";
+    if (!dir) {
+        return null;
+    }
+    return {
+        enabled: true,
+        storage: { type: "filesystem", path: dir },
+    };
+}
+//# sourceMappingURL=skillsFlags.js.map

package/dist/index.d.ts

@@ -44,6 +44,11 @@ export { ErrorCode as ClientErrorCode, NeuroLinkError as ClientNeuroLinkError, H
 export { AIProviderName, BedrockModels, OpenAIModels, VertexModels, } from "./constants/enums.js";
 export { dynamicModelProvider } from "./core/dynamicModels.js";
 export { validateTool } from "./sdk/toolRegistration.js";
+export { SkillsManager } from "./skills/skillsManager.js";
+export { createSkillStore, FileSystemSkillStore, InMemorySkillStore, } from "./skills/skillStores.js";
+export { S3SkillStore } from "./skills/skillStoreS3.js";
+export { RedisSkillStore } from "./skills/skillStoreRedis.js";
+export { createSkillTools } from "./skills/skillTools.js";
 export * from "./types/index.js";
 export { isAbortError } from "./utils/errorHandling.js";
 export { calculateCost, hasPricing } from "./utils/pricing.js";

package/dist/index.js

@@ -68,6 +68,12 @@ export { AIProviderName, BedrockModels, OpenAIModels, VertexModels, } from "./co
 export { dynamicModelProvider } from "./core/dynamicModels.js";
 // Tool Registration utility
 export { validateTool } from "./sdk/toolRegistration.js";
+// Skills subsystem — manager, stores, and the built-in tool factory
+export { SkillsManager } from "./skills/skillsManager.js";
+export { createSkillStore, FileSystemSkillStore, InMemorySkillStore, } from "./skills/skillStores.js";
+export { S3SkillStore } from "./skills/skillStoreS3.js";
+export { RedisSkillStore } from "./skills/skillStoreRedis.js";
+export { createSkillTools } from "./skills/skillTools.js";
 // Export ALL types from the centralized type barrel
 export * from "./types/index.js";
 // Error utilities

package/dist/lib/index.d.ts

@@ -44,6 +44,11 @@ export { ErrorCode as ClientErrorCode, NeuroLinkError as ClientNeuroLinkError, H
 export { AIProviderName, BedrockModels, OpenAIModels, VertexModels, } from "./constants/enums.js";
 export { dynamicModelProvider } from "./core/dynamicModels.js";
 export { validateTool } from "./sdk/toolRegistration.js";
+export { SkillsManager } from "./skills/skillsManager.js";
+export { createSkillStore, FileSystemSkillStore, InMemorySkillStore, } from "./skills/skillStores.js";
+export { S3SkillStore } from "./skills/skillStoreS3.js";
+export { RedisSkillStore } from "./skills/skillStoreRedis.js";
+export { createSkillTools } from "./skills/skillTools.js";
 export * from "./types/index.js";
 export { isAbortError } from "./utils/errorHandling.js";
 export { calculateCost, hasPricing } from "./utils/pricing.js";

package/dist/lib/index.js

@@ -68,6 +68,12 @@ export { AIProviderName, BedrockModels, OpenAIModels, VertexModels, } from "./co
 export { dynamicModelProvider } from "./core/dynamicModels.js";
 // Tool Registration utility
 export { validateTool } from "./sdk/toolRegistration.js";
+// Skills subsystem — manager, stores, and the built-in tool factory
+export { SkillsManager } from "./skills/skillsManager.js";
+export { createSkillStore, FileSystemSkillStore, InMemorySkillStore, } from "./skills/skillStores.js";
+export { S3SkillStore } from "./skills/skillStoreS3.js";
+export { RedisSkillStore } from "./skills/skillStoreRedis.js";
+export { createSkillTools } from "./skills/skillTools.js";
 // Export ALL types from the centralized type barrel
 export * from "./types/index.js";
 // Error utilities

package/dist/lib/neurolink.d.ts

@@ -12,6 +12,7 @@ import type { RedisConversationMemoryManager } from "./core/redisConversationMem
 import { ExternalServerManager } from "./mcp/externalServerManager.js";
 import { MCPToolRegistry } from "./mcp/toolRegistry.js";
 import type { DynamicOptions } from "./types/index.js";
+import { SkillsManager } from "./skills/skillsManager.js";
 import { TaskManager } from "./tasks/taskManager.js";
 /**
  * Curator P2-4 dedup (concurrency-safe): native providers emit
@@ -140,6 +141,8 @@ export declare class NeuroLink {
     private cachedFileTools;
     private memoryInstance?;
     private memorySDKConfig?;
+    private skillsManagerInstance?;
+    private skillsConfig?;
     /**
      * Extract and set Langfuse context from options with proper async scoping
      */
@@ -264,6 +267,31 @@ export declare class NeuroLink {
      * Only registered when Redis conversation memory is active.
      */
     private registerMemoryRetrievalTools;
+    /**
+     * Lazy initialization for the skills subsystem — mirrors ensureMemoryReady().
+     * Returns null (and stays null) when skills are not configured or the
+     * store failed to initialize; read paths fail open on that null.
+     */
+    private ensureSkillsReady;
+    /**
+     * Register the built-in skill tools (search_skills / list_skills, plus
+     * mutation tools when allowMutations is set). Follows the
+     * registerMemoryRetrievalTools() pattern: registered via registerTool()
+     * so they land in the "user-defined" category that reaches the LLM tool
+     * schema, with the manager resolved lazily at execution time.
+     */
+    private registerSkillTools;
+    /**
+     * Append the compact skills index (names + descriptions, never
+     * instructions) to the system prompt for one generate()/stream() call.
+     * Fails open: any error leaves the prompt untouched.
+     */
+    private applySkillsPromptIndex;
+    /**
+     * Programmatic access to the skills subsystem (search/list/get/mutations).
+     * Returns null when skills are not configured or failed to initialize.
+     */
+    getSkillsManager(): SkillsManager | null;
     /** Format memory context for prompt inclusion */
     private formatMemoryContext;
     /**

package/dist/lib/neurolink.js

@@ -54,6 +54,8 @@ import { MCPToolRegistry } from "./mcp/toolRegistry.js";
 import { resolveDynamicArgument } from "./dynamic/dynamicResolver.js";
 import { initializeHippocampus } from "./memory/hippocampusInitializer.js";
 import { createMemoryRetrievalTools } from "./memory/memoryRetrievalTools.js";
+import { SkillsManager } from "./skills/skillsManager.js";
+import { createSkillTools } from "./skills/skillTools.js";
 import { getMetricsAggregator, MetricsAggregator, } from "./observability/metricsAggregator.js";
 import { SpanStatus, SpanType, CircuitBreakerOpenError, ConversationMemoryError, ModelAccessDeniedError, } from "./types/index.js";
 import { SpanSerializer } from "./observability/utils/spanSerializer.js";
@@ -458,6 +460,10 @@ export class NeuroLink {
     // Memory instance and config
     memoryInstance;
     memorySDKConfig;
+    // Skills subsystem — lazily initialized manager + instance config.
+    // `undefined` = not yet attempted, `null` = init failed (stay disabled).
+    skillsManagerInstance;
+    skillsConfig;
     /**
      * Extract and set Langfuse context from options with proper async scoping
      */
@@ -830,6 +836,10 @@ export class NeuroLink {
         this.initializeMCPEnhancements(config);
         this.registerFileTools();
         this.registerMemoryRetrievalTools();
+        if (config?.skills?.enabled) {
+            this.skillsConfig = config.skills;
+            this.registerSkillTools();
+        }
         this.initializeLangfuse(constructorId, constructorStartTime, constructorHrTimeStart);
         this.initializeMetricsListeners();
         this.logConstructorComplete(constructorId, constructorStartTime, constructorHrTimeStart);
@@ -1243,6 +1253,107 @@ export class NeuroLink {
         });
         logger.info("[NeuroLink] Memory retrieval tools registered");
     }
+    /**
+     * Lazy initialization for the skills subsystem — mirrors ensureMemoryReady().
+     * Returns null (and stays null) when skills are not configured or the
+     * store failed to initialize; read paths fail open on that null.
+     */
+    ensureSkillsReady() {
+        if (this.skillsManagerInstance !== undefined) {
+            return this.skillsManagerInstance;
+        }
+        if (!this.skillsConfig?.enabled) {
+            this.skillsManagerInstance = null;
+            return null;
+        }
+        try {
+            this.skillsManagerInstance = new SkillsManager(this.skillsConfig);
+        }
+        catch (error) {
+            logger.warn("[NeuroLink] Skills initialization failed — skills disabled for this instance", { error: error instanceof Error ? error.message : String(error) });
+            this.skillsManagerInstance = null;
+        }
+        return this.skillsManagerInstance;
+    }
+    /**
+     * Register the built-in skill tools (search_skills / list_skills, plus
+     * mutation tools when allowMutations is set). Follows the
+     * registerMemoryRetrievalTools() pattern: registered via registerTool()
+     * so they land in the "user-defined" category that reaches the LLM tool
+     * schema, with the manager resolved lazily at execution time.
+     */
+    registerSkillTools() {
+        const canonicalTools = createSkillTools(() => this.ensureSkillsReady(), {
+            allowMutations: this.skillsConfig?.allowMutations === true,
+        });
+        for (const [toolName, toolDef] of Object.entries(canonicalTools)) {
+            this.registerTool(toolName, {
+                name: toolName,
+                description: toolDef.description ?? toolName,
+                // Zod schema — registerTool() detects isZodSchema and preserves it
+                // so ToolsManager gives the LLM full parameter types.
+                inputSchema: toolDef
+                    .inputSchema,
+                execute: async (params) => withTimeout(toolDef.execute(params, { toolCallId: "skill-tool", messages: [] }), TOOL_TIMEOUTS.EXECUTION_DEFAULT_MS, ErrorFactory.toolTimeout(toolName, TOOL_TIMEOUTS.EXECUTION_DEFAULT_MS)),
+            });
+        }
+        logger.info(`[NeuroLink] Registered ${Object.keys(canonicalTools).length} skill tools`, { allowMutations: this.skillsConfig?.allowMutations === true });
+    }
+    /**
+     * Append the compact skills index (names + descriptions, never
+     * instructions) to the system prompt for one generate()/stream() call.
+     * Fails open: any error leaves the prompt untouched.
+     */
+    async applySkillsPromptIndex(options) {
+        if (!this.skillsConfig?.enabled || options.skills?.enabled === false) {
+            return;
+        }
+        // Per-call promptIndex wins over instance config; default is on.
+        const promptIndexEnabled = options.skills?.promptIndex ?? this.skillsConfig.promptIndex ?? true;
+        if (!promptIndexEnabled) {
+            return;
+        }
+        // Media-only modes have no meaningful text prompt to augment.
+        const mode = options.output?.mode;
+        if (mode === "avatar" ||
+            mode === "music" ||
+            mode === "video" ||
+            mode === "ppt") {
+            return;
+        }
+        try {
+            const manager = this.ensureSkillsReady();
+            if (!manager) {
+                return;
+            }
+            const block = await manager.buildPromptIndex({
+                ...(options.skills?.scopeId !== undefined
+                    ? { scopeId: options.skills.scopeId }
+                    : {}),
+                ...(options.skills?.tags !== undefined
+                    ? { tags: options.skills.tags }
+                    : {}),
+            });
+            if (block) {
+                options.systemPrompt = options.systemPrompt
+                    ? `${options.systemPrompt}\n\n${block}`
+                    : block;
+                logger.debug("[NeuroLink] Skills prompt index injected", {
+                    blockLength: block.length,
+                });
+            }
+        }
+        catch (error) {
+            logger.warn("[NeuroLink] Skills prompt index injection failed — continuing without it", { error: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    /**
+     * Programmatic access to the skills subsystem (search/list/get/mutations).
+     * Returns null when skills are not configured or failed to initialize.
+     */
+    getSkillsManager() {
+        return this.ensureSkillsReady();
+    }
     /** Format memory context for prompt inclusion */
     formatMemoryContext(memoryContext, currentInput) {
         return `Context from previous conversations:
@@ -3499,6 +3610,9 @@ Current user's request: ${currentInput}`;
                 });
             }
         }
+        // Skills: append the compact skills index to the system prompt so the
+        // model knows which skills exist (bodies load via search_skills).
+        await this.applySkillsPromptIndex(options);
         // Media-only modes (avatar, music, video, ppt) do not have a meaningful
         // text prompt to augment with memory — skip injection to avoid corrupting
         // the empty/synthesized input.text that was set for these modes.
@@ -7037,6 +7151,9 @@ Current user's request: ${currentInput}`;
                 logger.warn("Memory retrieval failed:", error);
             }
         }
+        // Skills: append the compact skills index to the system prompt so the
+        // model knows which skills exist (bodies load via search_skills).
+        await this.applySkillsPromptIndex(options);
         // Apply orchestration if enabled and no specific provider/model requested
         if (this.enableOrchestration && !options.provider && !options.model) {
             try {