@jupyterlite/ai 0.11.0 → 0.12.0

package/schema/settings-model.json

@@ -163,7 +163,7 @@
       "title": "System Prompt",
       "description": "Instructions that define how the AI should behave and respond",
       "type": "string",
-      "default": "You are Jupyternaut, an AI coding assistant built specifically for the JupyterLab environment.\n\n## Your Core Mission\nYou're designed to be a capable partner for data science, research, and development work in Jupyter notebooks. You can help with everything from quick code snippets to complex multi-notebook projects.\n\n## Your Capabilities\n**📁 File & Project Management:**\n- Create, read, edit, and organize files and notebooks in any language\n- Manage project structure and navigate file systems\n- Help with version control and project organization\n\n**📊 Notebook Operations:**\n- Create new notebooks and manage existing ones\n- Add, edit, delete, and run cells (both code and markdown)\n- Help with notebook structure and organization\n- Retrieve and analyze cell outputs and execution results\n\n**⚡ Kernel Management:**\n- Start new kernels with specified language or kernel name\n- Execute code directly in running kernels without creating cells\n- List running kernels and monitor their status\n- Manage kernel lifecycle (start, monitor, shutdown)\n\n**🧠 Coding & Development:**\n- Write, debug, and optimize code in any language supported by Jupyter kernels (Python, R, Julia, JavaScript, C++, and more)\n- Explain complex algorithms and data structures\n- Help with data analysis, visualization, and machine learning\n- Support for libraries and packages across different languages\n- Code reviews and best practices recommendations\n\n**💡 Adaptive Assistance:**\n- Understand context from the user's current work environment\n- Provide suggestions tailored to the user's specific use case\n- Help with both quick fixes and long-term project planning\n\n## How You Work\nYou interact with the user's JupyterLab environment primarily through the command system:\n- Use 'discover_commands' to find available JupyterLab commands\n- Use 'execute_command' to perform operations\n- For file and notebook operations, use commands from the jupyterlab-ai-commands extension (prefixed with 'jupyterlab-ai-commands:')\n- These commands provide comprehensive file and notebook manipulation: create, read, edit files/notebooks, manage cells, run code, etc.\n- You can make systematic changes across multiple files and perform complex multi-step operations\n\n## Code Execution Strategy\nWhen asked to run code or perform computations, choose the most appropriate approach:\n- **For quick computations or one-off code execution**: Use kernel commands to start a kernel and execute code directly, without creating notebook files. This is ideal for calculations, data lookups, or testing code snippets.\n- **For work that should be saved**: Create or use notebooks when the user needs a persistent record of their work, wants to iterate on code, or is building something they'll return to later.\n\nThis means if the user asks you to \"calculate the factorial of 100\" or \"check what library version is installed\", run that directly in a kernel rather than creating a new notebook file.\n\n## Your Approach\n- **Context-aware**: You understand the user is working in a data science/research environment\n- **Practical**: You focus on actionable solutions that work in the user's current setup\n- **Educational**: You explain your reasoning and teach best practices along the way\n- **Collaborative**: You are a pair programming partner, not just a code generator\n\n## Communication Style & Agent Behavior\n- **Conversational**: You maintain a friendly, natural conversation flow throughout the interaction\n- **Progress Updates**: You write brief progress messages between tool uses that appear directly in the conversation\n- **No Filler**: You avoid empty acknowledgments like \"Sounds good!\" or \"Okay, I will...\" - you get straight to work\n- **Purposeful Communication**: You start with what you're doing, use tools, then share what you found and what's next\n- **Active Narration**: You actively write progress updates like \"Looking at the current code structure...\" or \"Found the issue in the notebook...\" between tool calls\n- **Checkpoint Updates**: After several operations, you summarize what you've accomplished and what remains\n- **Natural Flow**: Your explanations and progress reports appear as normal conversation text, not just in tool blocks\n\n## IMPORTANT: Always write progress messages between tools that explain what you're doing and what you found. These should be conversational updates that help the user follow along with your work.\n\n## Technical Communication\n- Code is formatted in proper markdown blocks with syntax highlighting\n- Mathematical notation uses LaTeX formatting: \\\\(equations\\\\) and \\\\[display math\\\\]\n- You provide context for your actions and explain your reasoning as you work\n- When creating or modifying multiple files, you give brief summaries of changes\n- You keep users informed of progress while staying focused on the task\n\n## Multi-Step Task Handling\nWhen users request complex tasks, you use the command system to accomplish them:\n- For file and notebook operations, use discover_commands with query 'jupyterlab-ai-commands' to find the curated set of AI commands (~17 commands)\n- For other JupyterLab operations (terminal, launcher, UI), use specific keywords like 'terminal', 'launcher', etc.\n- IMPORTANT: Always use 'jupyterlab-ai-commands' as the query for file/notebook tasks - this returns a focused set instead of 100+ generic commands\n- For example, to create a notebook with cells:\n  1. discover_commands with query 'jupyterlab-ai-commands' to find available file/notebook commands\n  2. execute_command with 'jupyterlab-ai-commands:create-notebook' and required arguments\n  3. execute_command with 'jupyterlab-ai-commands:add-cell' multiple times to add cells\n  4. execute_command with 'jupyterlab-ai-commands:set-cell-content' to add content to cells\n  5. execute_command with 'jupyterlab-ai-commands:run-cell' when appropriate\n\n## Kernel Preference for Notebooks and Consoles\nWhen creating notebooks or consoles for a specific programming language, use the 'kernelPreference' argument:\n- To specify by language: { \"kernelPreference\": { \"language\": \"python\" } } or { \"kernelPreference\": { \"language\": \"julia\" } }\n- To specify by kernel name: { \"kernelPreference\": { \"name\": \"python3\" } } or { \"kernelPreference\": { \"name\": \"julia-1.10\" } }\n- Example: execute_command with commandId=\"notebook:create-new\" and args={ \"kernelPreference\": { \"language\": \"python\" } }\n- Example: execute_command with commandId=\"console:create\" and args={ \"kernelPreference\": { \"name\": \"python3\" } }\n- Common kernel names: \"python3\" (Python), \"julia-1.10\" (Julia), \"ir\" (R), \"xpython\" (xeus-python)\n- If unsure of exact kernel name, prefer using \"language\" which will match any kernel supporting that language\n\nAlways think through multi-step tasks and use commands to fully complete the user's request rather than stopping after just one action.\n\nYou are ready to help users build something great!"
+      "default": "You are Jupyternaut, an AI coding assistant built specifically for the JupyterLab environment.\n\n## Your Core Mission\nYou're designed to be a capable partner for data science, research, and development work in Jupyter notebooks. You can help with everything from quick code snippets to complex multi-notebook projects.\n\n## Your Capabilities\n**📁 File & Project Management:**\n- Create, read, edit, and organize files and notebooks in any language\n- Manage project structure and navigate file systems\n- Help with version control and project organization\n\n**📊 Notebook Operations:**\n- Create new notebooks and manage existing ones\n- Add, edit, delete, and run cells (both code and markdown)\n- Help with notebook structure and organization\n- Retrieve and analyze cell outputs and execution results\n\n**⚡ Kernel Management:**\n- Start new kernels with specified language or kernel name\n- Execute code directly in a kernel using jupyterlab-ai-commands execution commands (not console), without creating cells\n- List running kernels and monitor their status\n- Manage kernel lifecycle (start, monitor, shutdown)\n\n**🧠 Coding & Development:**\n- Write, debug, and optimize code in any language supported by Jupyter kernels (Python, R, Julia, JavaScript, C++, and more)\n- Explain complex algorithms and data structures\n- Help with data analysis, visualization, and machine learning\n- Support for libraries and packages across different languages\n- Code reviews and best practices recommendations\n\n**💡 Adaptive Assistance:**\n- Understand context from the user's current work environment\n- Provide suggestions tailored to the user's specific use case\n- Help with both quick fixes and long-term project planning\n\n## How You Work\nYou interact with the user's JupyterLab environment primarily through the command system:\n- Use 'discover_commands' to find available JupyterLab commands\n- Use 'execute_command' to perform operations\n- For file and notebook operations, use commands from the jupyterlab-ai-commands extension (prefixed with 'jupyterlab-ai-commands:')\n- These commands provide comprehensive file and notebook manipulation: create, read, edit files/notebooks, manage cells, run code, etc.\n- You can make systematic changes across multiple files and perform complex multi-step operations\n- Skills are available via the skills tools: discover_skills (list) and load_skill (load instructions/resources)\n\n## Tool & Skill Use Policy\\n- When tools or skills are available and the task requires actions or environment-specific facts, use them instead of guessing\\n- Never guess command IDs. Always use discover_commands with a relevant query before execute_command, unless you already discovered the command earlier in this conversation\\n- If a preloaded skills snapshot is provided in the system prompt, use it instead of calling discover_skills to list skills\\n- Only call discover_skills if the user explicitly asks for the latest list or you need to verify a skill not in the snapshot\n- When a skill is relevant, call load_skill with the skill name to load instructions; if it returns a non-empty resources array, load each listed resource with load_skill before proceeding\\n- If you're unsure how to perform a request, discover relevant commands (discover_commands with task keywords)\\n- Use a relevant skill even when the user doesn't explicitly mention it\\n- Prefer the single most relevant tool or skill; if multiple could apply, ask a brief clarifying question\n- Ask for missing required inputs before calling a tool or skill\n- Before calling a tool or skill, briefly state why you're calling it\n\n## Code Execution Strategy\nWhen asked to run code or perform computations, choose the most appropriate approach:\n- **For quick computations or one-off code execution**: Use the kernel execution commands from jupyterlab-ai-commands to run code directly (no notebook/console). Discover these commands first with query 'jupyterlab-ai-commands' and use the returned command IDs. This is ideal for calculations, data lookups, or testing code snippets.\n- **For work that should be saved**: Create or use notebooks when the user needs a persistent record of their work, wants to iterate on code, or is building something they'll return to later.\n\nThis means if the user asks you to \"calculate the factorial of 100\" or \"check what library version is installed\", run that directly with the jupyterlab-ai-commands kernel execution command rather than creating a new notebook file.\n\n## Your Approach\n- **Context-aware**: You understand the user is working in a data science/research environment\n- **Practical**: You focus on actionable solutions that work in the user's current setup\n- **Educational**: You explain your reasoning and teach best practices along the way\n- **Collaborative**: You are a pair programming partner, not just a code generator\n\n## Communication Style & Agent Behavior\nIMPORTANT: Follow this message flow pattern for better user experience:\n\n1. FIRST: Explain what you're going to do and your approach\n2. THEN: Execute tools (these will show automatically with step numbers)\n3. FINALLY: Provide a concise summary of what was accomplished\n\nExample flow:\n- \"I'll help you create a notebook with example cells. Let me first create the file structure, then add Python and Markdown cells.\"\n- [Tool executions happen with automatic step display]\n- \"Successfully created your notebook with 3 cells: a title, code example, and visualization cell.\"\n\nGuidelines:\n- Start responses with your plan/approach before tool execution\n- Let the system handle tool execution display (don't duplicate details)\n- End with a brief summary of accomplishments\n- Use natural, conversational tone throughout\n\n- **Conversational**: You maintain a friendly, natural conversation flow throughout the interaction\n- **Progress Updates**: You write brief progress messages between tool uses that appear directly in the conversation\n- **No Filler**: You avoid empty acknowledgments like \"Sounds good!\" or \"Okay, I will...\" - you get straight to work\n- **Purposeful Communication**: You start with what you're doing, use tools, then share what you found and what's next\n- **Active Narration**: You actively write progress updates like \"Looking at the current code structure...\" or \"Found the issue in the notebook...\" between tool calls\n- **Checkpoint Updates**: After several operations, you summarize what you've accomplished and what remains\n- **Natural Flow**: Your explanations and progress reports appear as normal conversation text, not just in tool blocks\n\n## IMPORTANT: Always write progress messages between tools that explain what you're doing and what you found. These should be conversational updates that help the user follow along with your work.\n\n## Technical Communication\n- Code is formatted in proper markdown blocks with syntax highlighting\n- Mathematical notation uses LaTeX formatting: \\\\(equations\\\\) and \\\\[display math\\\\]\n- You provide context for your actions and explain your reasoning as you work\n- When creating or modifying multiple files, you give brief summaries of changes\n- You keep users informed of progress while staying focused on the task\n\n## Multi-Step Task Handling\nWhen users request complex tasks, you use the command system to accomplish them:\n- For file and notebook operations, use discover_commands with query 'jupyterlab-ai-commands' to find the curated set of AI commands (~17 commands)\n- For other JupyterLab operations (terminal, launcher, UI), use specific keywords like 'terminal', 'launcher', etc.\n- IMPORTANT: Always use 'jupyterlab-ai-commands' as the query for file/notebook tasks - this returns a focused set instead of 100+ generic commands\n- For example, to create a notebook with cells:\n  1. discover_commands with query 'jupyterlab-ai-commands' to find available file/notebook commands\n  2. execute_command with 'jupyterlab-ai-commands:create-notebook' and required arguments\n  3. execute_command with 'jupyterlab-ai-commands:add-cell' multiple times to add cells\n  4. execute_command with 'jupyterlab-ai-commands:set-cell-content' to add content to cells\n  5. execute_command with 'jupyterlab-ai-commands:run-cell' when appropriate\n\n## Kernel Preference for Notebooks and Consoles\nWhen creating notebooks or consoles for a specific programming language, use the 'kernelPreference' argument:\nOnly create consoles when the user explicitly asks for one; otherwise prefer the jupyterlab-ai-commands kernel execution commands for running code.\n- To specify by language: { \"kernelPreference\": { \"language\": \"python\" } } or { \"kernelPreference\": { \"language\": \"julia\" } }\n- To specify by kernel name: { \"kernelPreference\": { \"name\": \"python3\" } } or { \"kernelPreference\": { \"name\": \"julia-1.10\" } }\n- Example: execute_command with commandId=\"notebook:create-new\" and args={ \"kernelPreference\": { \"language\": \"python\" } }\n- Example: execute_command with commandId=\"console:create\" and args={ \"kernelPreference\": { \"name\": \"python3\" } }\n- Common kernel names: \"python3\" (Python), \"julia-1.10\" (Julia), \"ir\" (R), \"xpython\" (xeus-python)\n- If unsure of exact kernel name, prefer using \"language\" which will match any kernel supporting that language\n\nAlways think through multi-step tasks and use commands to fully complete the user's request rather than stopping after just one action.\n\nYou are ready to help users build something great!"
     },
     "completionSystemPrompt": {
       "title": "Completion System Prompt",
@@ -189,6 +189,13 @@
       "type": "string",
       "enum": ["split", "unified"],
       "default": "split"
+    },
+    "skillsPaths": {
+      "title": "Skills Paths",
+      "description": "Paths to directories containing agent skills, relative to the server root. Skills are loaded from all paths; the first occurrence of a skill name takes priority.",
+      "type": "array",
+      "items": { "type": "string" },
+      "default": [".agents/skills", "_agents/skills"]
     }
   },
   "additionalProperties": false

package/src/agent.ts

@@ -2,6 +2,7 @@ import { ISignal, Signal } from '@lumino/signaling';
 import {
   ToolLoopAgent,
   type ModelMessage,
+  type LanguageModel,
   stepCountIs,
   type StreamTextResult,
   type Tool,
@@ -14,7 +15,14 @@ import { ISecretsManager } from 'jupyter-secrets-manager';
 import { AISettingsModel } from './models/settings-model';
 import { createModel } from './providers/models';
 import type { IProviderRegistry } from './tokens';
-import { ITool, IToolRegistry, ITokenUsage, SECRETS_NAMESPACE } from './tokens';
+import {
+  ISkillRegistry,
+  ISkillSummary,
+  ITool,
+  IToolRegistry,
+  ITokenUsage,
+  SECRETS_NAMESPACE
+} from './tokens';
 
 /**
  * Interface for MCP client wrapper to track connection state
@@ -46,6 +54,10 @@ export namespace AgentManagerFactory {
      * The settings model.
      */
     settingsModel: AISettingsModel;
+    /**
+     * The skill registry for discovering skills.
+     */
+    skillRegistry?: ISkillRegistry;
     /**
      * The secrets manager.
      */
@@ -60,10 +72,17 @@ export class AgentManagerFactory {
   constructor(options: AgentManagerFactory.IOptions) {
     Private.setToken(options.token);
     this._settingsModel = options.settingsModel;
+    this._skillRegistry = options.skillRegistry;
     this._secretsManager = options.secretsManager;
     this._mcpClients = [];
     this._mcpConnectionChanged = new Signal<this, boolean>(this);
 
+    if (this._skillRegistry) {
+      this._skillRegistry.skillsChanged.connect(() => {
+        this.refreshSkillSnapshots();
+      });
+    }
+
     // Initialize agent on construction
     this._initializeAgents().catch(error =>
       console.warn('Failed to initialize agent in constructor:', error)
@@ -76,6 +95,7 @@ export class AgentManagerFactory {
   createAgent(options: IAgentManagerOptions): AgentManager {
     const agentManager = new AgentManager({
       ...options,
+      skillRegistry: this._skillRegistry,
       secretsManager: this._secretsManager
     });
     this._agentManagers.push(agentManager);
@@ -181,31 +201,39 @@ export class AgentManagerFactory {
    * Sets up the agent with model configuration, tools, and MCP servers.
    */
   private async _initializeAgents(): Promise<void> {
-    if (this._isInitializing) {
-      return;
-    }
-    this._isInitializing = true;
-
-    try {
-      await this._initializeMCPClients();
-      const mcpTools = await this.getMCPTools();
-
-      this._agentManagers.forEach(manager => {
-        manager.initializeAgent(mcpTools);
+    this._initQueue = this._initQueue
+      .catch(() => undefined)
+      .then(async () => {
+        try {
+          await this._initializeMCPClients();
+          const mcpTools = await this.getMCPTools();
+
+          this._agentManagers.forEach(manager => {
+            manager.initializeAgent(mcpTools);
+          });
+        } catch (error) {
+          console.warn('Failed to initialize agents:', error);
+        }
       });
-    } catch (error) {
-      console.warn('Failed to initialize agents:', error);
-    } finally {
-      this._isInitializing = false;
-    }
+    return this._initQueue;
+  }
+
+  /**
+   * Refresh skill snapshots across all agents.
+   */
+  refreshSkillSnapshots(): void {
+    this._agentManagers.forEach(manager => {
+      manager.refreshSkills();
+    });
   }
 
   private _agentManagers: AgentManager[] = [];
   private _settingsModel: AISettingsModel;
+  private _skillRegistry?: ISkillRegistry;
   private _secretsManager?: ISecretsManager;
   private _mcpClients: IMCPClientWrapper[];
   private _mcpConnectionChanged: Signal<this, boolean>;
-  private _isInitializing: boolean = false;
+  private _initQueue: Promise<void> = Promise.resolve();
 }
 
 /**
@@ -268,6 +296,19 @@ export type IAgentEvent<
     }
   : never;
 
+/**
+ * Cached configuration used to (re)build the agent.
+ */
+interface IAgentConfig {
+  model: LanguageModel;
+  tools: ToolMap;
+  temperature: number;
+  maxOutputTokens?: number;
+  maxTurns: number;
+  baseSystemPrompt: string;
+  shouldUseTools: boolean;
+}
+
 /**
  * Configuration options for the AgentManager
  */
@@ -287,6 +328,11 @@ export interface IAgentManagerOptions {
    */
   providerRegistry?: IProviderRegistry;
 
+  /**
+   * The skill registry for discovering skills.
+   */
+  skillRegistry?: ISkillRegistry;
+
   /**
    * The secrets manager.
    */
@@ -318,12 +364,12 @@ export class AgentManager {
     this._settingsModel = options.settingsModel;
     this._toolRegistry = options.toolRegistry;
     this._providerRegistry = options.providerRegistry;
+    this._skillRegistry = options.skillRegistry;
     this._secretsManager = options.secretsManager;
     this._selectedToolNames = [];
     this._agent = null;
     this._history = [];
     this._mcpTools = {};
-    this._isInitializing = false;
     this._controller = null;
     this._agentEvent = new Signal<this, IAgentEvent>(this);
     this._tokenUsage = options.tokenUsage ?? {
@@ -331,6 +377,8 @@ export class AgentManager {
       outputTokens: 0
     };
     this._tokenUsageChanged = new Signal<this, ITokenUsage>(this);
+    this._skills = [];
+    this._agentConfig = null;
 
     this.activeProvider =
       options.activeProvider ?? this._settingsModel.config.defaultProvider;
@@ -369,6 +417,21 @@ export class AgentManager {
     return this._tokenUsageChanged;
   }
 
+  /**
+   * Refresh the skills snapshot and rebuild the agent if resources are ready.
+   */
+  refreshSkills(): void {
+    this._initQueue = this._initQueue
+      .catch(() => undefined)
+      .then(async () => {
+        this._refreshSkills();
+        if (!this._agentConfig) {
+          return;
+        }
+        this._rebuildAgent();
+      });
+  }
+
   /**
    * The active provider for this agent.
    */
@@ -597,59 +660,108 @@ export class AgentManager {
    * Sets up the agent with model configuration, tools, and MCP tools.
    */
   initializeAgent = async (mcpTools?: ToolMap): Promise<void> => {
-    if (this._isInitializing) {
+    this._initQueue = this._initQueue
+      .catch(() => undefined)
+      .then(async () => {
+        try {
+          this._refreshSkills();
+          await this._prepareAgentConfig(mcpTools);
+          this._rebuildAgent();
+        } catch (error) {
+          console.warn('Failed to initialize agent:', error);
+          this._agent = null;
+        }
+      });
+    return this._initQueue;
+  };
+
+  /**
+   * Refresh the in-memory skills snapshot from the skill registry.
+   */
+  private _refreshSkills(): void {
+    if (!this._skillRegistry) {
+      this._skills = [];
       return;
     }
-    this._isInitializing = true;
-
-    try {
-      const config = this._settingsModel.config;
-      if (mcpTools !== undefined) {
-        this._mcpTools = mcpTools;
-      }
+    this._skills = this._skillRegistry.listSkills();
+  }
 
-      const model = await this._createModel();
+  /**
+   * Prepare model, tools, and settings needed to (re)build the agent.
+   */
+  private async _prepareAgentConfig(mcpTools?: ToolMap): Promise<void> {
+    const config = this._settingsModel.config;
+    if (mcpTools !== undefined) {
+      this._mcpTools = mcpTools;
+    }
 
-      const shouldUseTools =
-        config.toolsEnabled &&
-        this._selectedToolNames.length > 0 &&
-        this._toolRegistry &&
-        Object.keys(this._toolRegistry.tools).length > 0 &&
-        this._supportsToolCalling();
+    const model = await this._createModel();
 
-      const tools = shouldUseTools
-        ? { ...this.selectedAgentTools, ...this._mcpTools }
-        : this._mcpTools;
+    const shouldUseTools = !!(
+      config.toolsEnabled &&
+      this._selectedToolNames.length > 0 &&
+      this._toolRegistry &&
+      Object.keys(this._toolRegistry.tools).length > 0 &&
+      this._supportsToolCalling()
+    );
 
-      const activeProviderConfig = this._settingsModel.getProvider(
-        this._activeProvider
-      );
+    const tools = shouldUseTools
+      ? { ...this.selectedAgentTools, ...this._mcpTools }
+      : this._mcpTools;
 
-      const temperature =
-        activeProviderConfig?.parameters?.temperature ?? DEFAULT_TEMPERATURE;
-      const maxTokens = activeProviderConfig?.parameters?.maxOutputTokens;
-      const maxTurns =
-        activeProviderConfig?.parameters?.maxTurns ?? DEFAULT_MAX_TURNS;
+    const activeProviderConfig = this._settingsModel.getProvider(
+      this._activeProvider
+    );
 
-      const instructions = shouldUseTools
-        ? this._getEnhancedSystemPrompt(config.systemPrompt || '')
-        : config.systemPrompt || 'You are a helpful assistant.';
+    const temperature =
+      activeProviderConfig?.parameters?.temperature ?? DEFAULT_TEMPERATURE;
+    const maxTokens = activeProviderConfig?.parameters?.maxOutputTokens;
+    const maxTurns =
+      activeProviderConfig?.parameters?.maxTurns ?? DEFAULT_MAX_TURNS;
+
+    this._agentConfig = {
+      model,
+      tools,
+      temperature,
+      maxOutputTokens: maxTokens,
+      maxTurns,
+      baseSystemPrompt: config.systemPrompt || '',
+      shouldUseTools
+    };
+  }
 
-      this._agent = new ToolLoopAgent({
-        model,
-        instructions,
-        tools,
-        temperature,
-        maxOutputTokens: maxTokens,
-        stopWhen: stepCountIs(maxTurns)
-      });
-    } catch (error) {
-      console.warn('Failed to initialize agent:', error);
+  /**
+   * Rebuild the agent using cached resources and the current skills snapshot.
+   */
+  private _rebuildAgent(): void {
+    if (!this._agentConfig) {
       this._agent = null;
-    } finally {
-      this._isInitializing = false;
+      return;
     }
-  };
+
+    const {
+      model,
+      tools,
+      temperature,
+      maxOutputTokens,
+      maxTurns,
+      baseSystemPrompt,
+      shouldUseTools
+    } = this._agentConfig;
+
+    const instructions = shouldUseTools
+      ? this._getEnhancedSystemPrompt(baseSystemPrompt)
+      : baseSystemPrompt || 'You are a helpful assistant.';
+
+    this._agent = new ToolLoopAgent({
+      model,
+      instructions,
+      tools,
+      temperature,
+      maxOutputTokens,
+      stopWhen: stepCountIs(maxTurns)
+    });
+  }
 
   /**
    * Processes the stream result from agent execution.
@@ -892,69 +1004,53 @@ export class AgentManager {
   }
 
   /**
-   * Enhances the base system prompt with tool usage guidelines.
+   * Enhances the base system prompt with dynamic context like skills.
    * @param baseSystemPrompt The base system prompt from settings
-   * @returns The enhanced system prompt with tool usage instructions
+   * @returns The enhanced system prompt with dynamic additions
    */
   private _getEnhancedSystemPrompt(baseSystemPrompt: string): string {
-    const progressReportingPrompt = `
-
-IMPORTANT: Follow this message flow pattern for better user experience:
-
-1. FIRST: Explain what you're going to do and your approach
-2. THEN: Execute tools (these will show automatically with step numbers)
-3. FINALLY: Provide a concise summary of what was accomplished
-
-Example flow:
-- "I'll help you create a notebook with example cells. Let me first create the file structure, then add Python and Markdown cells."
-- [Tool executions happen with automatic step display]
-- "Successfully created your notebook with 3 cells: a title, code example, and visualization cell."
-
-Guidelines:
-- Start responses with your plan/approach before tool execution
-- Let the system handle tool execution display (don't duplicate details)
-- End with a brief summary of accomplishments
-- Use natural, conversational tone throughout
-
-PRIMARY TOOL USAGE - COMMAND-BASED OPERATIONS:
-Most operations in JupyterLab should be performed using the command system:
-1. Use 'discover_commands' to find available commands and their metadata
-2. Use 'execute_command' to perform the actual operation
-
-COMMAND DISCOVERY WORKFLOW:
-- For file and notebook operations, use query 'jupyterlab-ai-commands' to discover the curated set of AI commands (~17 commands for file/notebook/directory operations)
-- For other JupyterLab operations (terminal, launcher, UI), use specific keywords like 'terminal', 'launcher', etc.
-- IMPORTANT: Always use 'jupyterlab-ai-commands' as the query for file/notebook tasks - this returns a focused set of commands instead of 100+ generic JupyterLab commands
-
-KERNEL PREFERENCE FOR NOTEBOOKS AND CONSOLES:
-When creating notebooks or consoles for a specific programming language, use the 'kernelPreference' argument to specify the kernel:
-- To specify by language: { "kernelPreference": { "language": "python" } } or { "kernelPreference": { "language": "julia" } }
-- To specify by kernel name: { "kernelPreference": { "name": "python3" } } or { "kernelPreference": { "name": "julia-1.10" } }
-- Example: execute_command with commandId="notebook:create-new" and args={ "kernelPreference": { "language": "python" } }
-- Example: execute_command with commandId="console:create" and args={ "kernelPreference": { "name": "python3" } }
-- Common kernel names: "python3" (Python), "julia-1.10" (Julia), "ir" (R), "xpython" (xeus-python)
-- If unsure of exact kernel name, prefer using "language" which will match any kernel supporting that language
+    if (this._skills.length === 0) {
+      return baseSystemPrompt;
+    }
+
+    const lines = this._skills.map(
+      skill => `- ${skill.name}: ${skill.description}`
+    );
+    const skillsPrompt = `
+
+AGENT SKILLS:
+Skills are provided via the skills registry and accessed through tools (not commands).
+When a skill is relevant to the user's task, activate it by calling load_skill with the skill name to load its full instructions, then follow those instructions.
+If the user explicitly asks for the latest list of skills, call discover_skills (optionally with a query).
+Do NOT call discover_skills just to list skills; use the preloaded snapshot below instead unless you need to verify a skill not present in the snapshot.
+If the load_skill result includes a non-empty "resources" array, those are bundled files (scripts, references, templates) you MUST load before proceeding. Only load the listed resource paths; never invent resource names. For each resource path, execute load_skill again with the resource argument, e.g.: load_skill({ name: "<skill>", resource: "<path>" }). Load all listed resources before starting the task.
+
+AVAILABLE SKILLS (preloaded snapshot):
+${lines.join('\n')}
 `;
 
-    return baseSystemPrompt + progressReportingPrompt;
+    return baseSystemPrompt + skillsPrompt;
   }
 
   // Private attributes
   private _settingsModel: AISettingsModel;
   private _toolRegistry?: IToolRegistry;
   private _providerRegistry?: IProviderRegistry;
+  private _skillRegistry?: ISkillRegistry;
   private _secretsManager?: ISecretsManager;
   private _selectedToolNames: string[];
   private _agent: ToolLoopAgent<never, ToolMap> | null;
   private _history: ModelMessage[];
   private _mcpTools: ToolMap;
-  private _isInitializing: boolean;
   private _controller: AbortController | null;
   private _agentEvent: Signal<this, IAgentEvent>;
   private _tokenUsage: ITokenUsage;
   private _tokenUsageChanged: Signal<this, ITokenUsage>;
   private _activeProvider: string = '';
   private _activeProviderChanged = new Signal<this, string | undefined>(this);
+  private _skills: ISkillSummary[];
+  private _initQueue: Promise<void> = Promise.resolve();
+  private _agentConfig: IAgentConfig | null;
   private _pendingApprovals: Map<
     string,
     { resolve: (approved: boolean, reason?: string) => void }

package/src/chat-commands/clear.ts

@@ -0,0 +1,46 @@
+import { ChatCommand, IChatCommandProvider, IInputModel } from '@jupyter/chat';
+
+import { AIChatModel } from '../chat-model';
+
+export class ClearCommandProvider implements IChatCommandProvider {
+  public id: string = '@jupyterlite/ai:clear-command';
+
+  async listCommandCompletions(
+    inputModel: IInputModel
+  ): Promise<ChatCommand[]> {
+    const match = inputModel.currentWord?.match(this._regex)?.[0];
+    if (!match) {
+      return [];
+    }
+
+    if (this._command.name.startsWith(match)) {
+      return [this._command];
+    }
+
+    return [];
+  }
+
+  async onSubmit(inputModel: IInputModel): Promise<void> {
+    const trimmed = inputModel.value.trim();
+    if (trimmed !== this._command.name) {
+      return;
+    }
+
+    const context = inputModel.chatContext as
+      | AIChatModel.IAIChatContext
+      | undefined;
+    context?.clearMessages?.();
+
+    inputModel.value = '';
+    inputModel.clearAttachments();
+    inputModel.clearMentions();
+  }
+
+  private _command: ChatCommand = {
+    name: '/clear',
+    providerId: this.id,
+    description: 'Clear the current chat history'
+  };
+
+  private _regex: RegExp = /^\/\w*$/;
+}

package/src/chat-commands/index.ts

@@ -0,0 +1,2 @@
+export * from './clear';
+export * from './skills';

package/src/chat-commands/skills.ts

@@ -0,0 +1,87 @@
+import { ChatCommand, IChatCommandProvider, IInputModel } from '@jupyter/chat';
+
+import { CommandRegistry } from '@lumino/commands';
+
+import { AIChatModel } from '../chat-model';
+import { CommandIds, ISkillRegistry } from '../tokens';
+
+export class SkillsCommandProvider implements IChatCommandProvider {
+  constructor(options: SkillsCommandProvider.IOptions) {
+    this._skillRegistry = options.skillRegistry;
+    this._commands = options.commands;
+  }
+
+  public id: string = '@jupyterlite/ai:skills-command';
+
+  async listCommandCompletions(
+    inputModel: IInputModel
+  ): Promise<ChatCommand[]> {
+    const match = inputModel.currentWord?.match(this._regex)?.[0];
+    if (!match) {
+      return [];
+    }
+
+    if (this._command.name.startsWith(match)) {
+      return [this._command];
+    }
+
+    return [];
+  }
+
+  async onSubmit(inputModel: IInputModel): Promise<void> {
+    const trimmed = inputModel.value.trim();
+    const match = trimmed.match(/^\/skills(?:\s+(.+))?$/);
+    if (!match) {
+      return;
+    }
+
+    // Refresh skills from disk before listing
+    if (this._commands.hasCommand(CommandIds.refreshSkills)) {
+      await this._commands.execute(CommandIds.refreshSkills);
+    }
+
+    const query = match[1]?.trim();
+    const filtered = this._skillRegistry.listSkills(query);
+
+    let body = '';
+    if (filtered.length === 0) {
+      body = query
+        ? `No skills found matching "${query}".`
+        : 'No skills are currently registered.';
+    } else {
+      const heading = query
+        ? `Skills matching "${query}" (${filtered.length}):`
+        : `Available skills (${filtered.length}):`;
+      const lines = filtered.map(
+        skill => `- \`${skill.name}\` — ${skill.description}`
+      );
+      body = [heading, '', ...lines].join('\n');
+    }
+
+    const context = inputModel.chatContext as
+      | AIChatModel.IAIChatContext
+      | undefined;
+    context?.addSystemMessage?.(body);
+
+    inputModel.value = '';
+    inputModel.clearAttachments();
+    inputModel.clearMentions();
+  }
+
+  private _command: ChatCommand = {
+    name: '/skills',
+    providerId: this.id,
+    description: 'List available skills'
+  };
+
+  private _regex: RegExp = /^\/\w*$/;
+  private _commands: CommandRegistry;
+  private _skillRegistry: ISkillRegistry;
+}
+
+export namespace SkillsCommandProvider {
+  export interface IOptions {
+    skillRegistry: ISkillRegistry;
+    commands: CommandRegistry;
+  }
+}

package/src/chat-model-registry.ts

@@ -75,6 +75,9 @@ export class ChatModelRegistry implements IChatModelRegistry {
   add(model: AIChatModel): void {
     if (!this._models.find(m => m.name === model.name)) {
       this._models.push(model);
+      model.disposed.connect(() => {
+        this.remove(model.name);
+      });
     }
   }
 
@@ -93,6 +96,16 @@ export class ChatModelRegistry implements IChatModelRegistry {
     }
   }
 
+  /**
+   * Getter/setter for the active cell manager.
+   */
+  get activeCellManager(): ActiveCellManager | undefined {
+    return this._activeCellManager;
+  }
+  set activeCellManager(manager: ActiveCellManager | undefined) {
+    this._activeCellManager = manager;
+  }
+
   private _models: AIChatModel[] = [];
   private _docManager: IDocumentManager;
   private _agentManagerFactory: AgentManagerFactory;
@@ -128,7 +141,7 @@ export namespace ChatModelRegistry {
     /**
      * The active cell manager.
      */
-    activeCellManager: ActiveCellManager | undefined;
+    activeCellManager?: ActiveCellManager | undefined;
     /**
      * The application language translation bundle.
      */