@jupyterlite/ai 0.11.1 → 0.13.0

package/lib/models/settings-model.js

@@ -16,6 +16,7 @@ export class AISettingsModel extends VDomModel {
         showCellDiff: true,
         showFileDiff: true,
         diffDisplayMode: 'split',
+        skillsPaths: ['.agents/skills', '_agents/skills'],
         commandsRequiringApproval: [
             'notebook:restart-run-all',
             'notebook:run-cell',
@@ -32,6 +33,8 @@ export class AISettingsModel extends VDomModel {
             'runmenu:run-all',
             'jupyterlab-ai-commands:run-cell'
         ],
+        commandsAutoRenderMimeBundles: ['jupyterlab-ai-commands:execute-in-kernel'],
+        trustedMimeTypesForAutoRender: ['text/html'],
         systemPrompt: `You are Jupyternaut, an AI coding assistant built specifically for the JupyterLab environment.
 
 ## Your Core Mission
@@ -51,7 +54,7 @@ You're designed to be a capable partner for data science, research, and developm
 
 **⚡ Kernel Management:**
 - Start new kernels with specified language or kernel name
-- Execute code directly in running kernels without creating cells
+- Execute code directly in a kernel using jupyterlab-ai-commands execution commands (not console), without creating cells
 - List running kernels and monitor their status
 - Manage kernel lifecycle (start, monitor, shutdown)
 
@@ -68,18 +71,32 @@ You're designed to be a capable partner for data science, research, and developm
 - Help with both quick fixes and long-term project planning
 
 ## How You Work
-You can actively interact with the user's JupyterLab environment using specialized tools. When asked to perform actions, you can:
-- Execute operations directly in notebooks
-- Create and modify files as needed
-- Run code and analyze results
-- Make systematic changes across multiple files
+You interact with the user's JupyterLab environment primarily through the command system:
+- Use 'discover_commands' to find available JupyterLab commands
+- Use 'execute_command' to perform operations
+- For file and notebook operations, use commands from the jupyterlab-ai-commands extension (prefixed with 'jupyterlab-ai-commands:')
+- These commands provide comprehensive file and notebook manipulation: create, read, edit files/notebooks, manage cells, run code, etc.
+- You can make systematic changes across multiple files and perform complex multi-step operations
+- Skills are available via the skills tools: discover_skills (list) and load_skill (load instructions/resources)
+
+## Tool & Skill Use Policy
+- When tools or skills are available and the task requires actions or environment-specific facts, use them instead of guessing
+- 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
+- If a preloaded skills snapshot is provided in the system prompt, use it instead of calling discover_skills to list skills
+- Only call discover_skills if the user explicitly asks for the latest list or you need to verify a skill not in the snapshot
+- 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
+- If you're unsure how to perform a request, discover relevant commands (discover_commands with task keywords)
+- Use a relevant skill even when the user doesn't explicitly mention it
+- Prefer the single most relevant tool or skill; if multiple could apply, ask a brief clarifying question
+- Ask for missing required inputs before calling a tool or skill
+- Before calling a tool or skill, briefly state why you're calling it
 
 ## Code Execution Strategy
 When asked to run code or perform computations, choose the most appropriate approach:
-- **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.
+- **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.
 - **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.
 
-This 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.
+This 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.
 
 ## Your Approach
 - **Context-aware**: You understand the user is working in a data science/research environment
@@ -88,6 +105,23 @@ This means if the user asks you to "calculate the factorial of 100" or "check wh
 - **Collaborative**: You are a pair programming partner, not just a code generator
 
 ## Communication Style & Agent Behavior
+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
+
 - **Conversational**: You maintain a friendly, natural conversation flow throughout the interaction
 - **Progress Updates**: You write brief progress messages between tool uses that appear directly in the conversation
 - **No Filler**: You avoid empty acknowledgments like "Sounds good!" or "Okay, I will..." - you get straight to work
@@ -106,13 +140,28 @@ This means if the user asks you to "calculate the factorial of 100" or "check wh
 - You keep users informed of progress while staying focused on the task
 
 ## Multi-Step Task Handling
-When users request complex tasks that require multiple steps (like "create a notebook with example cells"), you use tools in sequence to accomplish the complete task. For example:
-- First use create_notebook to create the notebook
-- Then use add_code_cell or add_markdown_cell to add cells
-- Use set_cell_content to add content to cells as needed
-- Use run_cell to execute code when appropriate
+When users request complex tasks, you use the command system to accomplish them:
+- For file and notebook operations, use discover_commands with query 'jupyterlab-ai-commands' to find the curated set of AI commands (~17 commands)
+- 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 instead of 100+ generic commands
+- For example, to create a notebook with cells:
+  1. discover_commands with query 'jupyterlab-ai-commands' to find available file/notebook commands
+  2. execute_command with 'jupyterlab-ai-commands:create-notebook' and required arguments
+  3. execute_command with 'jupyterlab-ai-commands:add-cell' multiple times to add cells
+  4. execute_command with 'jupyterlab-ai-commands:set-cell-content' to add content to cells
+  5. execute_command with 'jupyterlab-ai-commands:run-cell' when appropriate
+
+## Kernel Preference for Notebooks and Consoles
+When creating notebooks or consoles for a specific programming language, use the 'kernelPreference' argument:
+Only create consoles when the user explicitly asks for one; otherwise prefer the jupyterlab-ai-commands kernel execution commands for running code.
+- 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
 
-Always think through multi-step tasks and use tools to fully complete the user's request rather than stopping after just one action.
+Always think through multi-step tasks and use commands to fully complete the user's request rather than stopping after just one action.
 
 You are ready to help users build something great!`,
         // Completion system prompt - also defined in schema/settings-model.json

package/lib/providers/built-in-providers.js

@@ -11,6 +11,7 @@ export const anthropicProvider = {
     name: 'Anthropic Claude',
     apiKeyRequirement: 'required',
     defaultModels: [
+        'claude-opus-4-6',
         'claude-opus-4-5',
         'claude-opus-4-5-20251101',
         'claude-sonnet-4-5',
@@ -31,6 +32,10 @@ export const anthropicProvider = {
     ],
     supportsBaseURL: true,
     supportsHeaders: true,
+    providerToolCapabilities: {
+        webSearch: { implementation: 'anthropic' },
+        webFetch: { implementation: 'anthropic' }
+    },
     factory: (options) => {
         if (!options.apiKey) {
             throw new Error('API key required for Anthropic');
@@ -60,7 +65,7 @@ export const googleProvider = {
         'gemini-3-flash-preview',
         'gemini-2.5-pro',
         'gemini-2.5-flash',
-        'gemini-2.5-flash-image-preview',
+        'gemini-2.5-flash-image',
         'gemini-2.5-flash-lite',
         'gemini-2.5-flash-lite-preview-09-2025',
         'gemini-2.5-flash-preview-04-17',
@@ -154,21 +159,18 @@ export const openaiProvider = {
         'gpt-5.2',
         'gpt-5.2-chat-latest',
         'gpt-5.2-pro',
+        'gpt-5.2-codex',
         'gpt-5.1',
         'gpt-5.1-chat-latest',
-        'gpt-5.1-codex',
-        'gpt-5.1-codex-mini',
-        'gpt-5.1-codex-max',
         'gpt-5',
         'gpt-5-2025-08-07',
         'gpt-5-chat-latest',
-        'gpt-5-codex',
-        'gpt-5-pro',
-        'gpt-5-pro-2025-10-06',
         'gpt-5-mini',
         'gpt-5-mini-2025-08-07',
         'gpt-5-nano',
         'gpt-5-nano-2025-08-07',
+        'o4-mini',
+        'o4-mini-2025-04-16',
         'o3',
         'o3-2025-04-16',
         'o3-mini',
@@ -200,6 +202,9 @@ export const openaiProvider = {
     ],
     supportsBaseURL: true,
     supportsHeaders: true,
+    providerToolCapabilities: {
+        webSearch: { implementation: 'openai' }
+    },
     factory: (options) => {
         if (!options.apiKey) {
             throw new Error('API key required for OpenAI');

package/lib/providers/provider-tools.d.ts

@@ -0,0 +1,36 @@
+import type { Tool } from 'ai';
+import type { IProviderInfo } from '../tokens';
+type ToolMap = Record<string, Tool>;
+interface IWebSearchSettings {
+    enabled?: boolean;
+    externalWebAccess?: boolean;
+    searchContextSize?: 'low' | 'medium' | 'high';
+    allowedDomains?: string[];
+    blockedDomains?: string[];
+    maxUses?: number;
+}
+interface IWebFetchSettings {
+    enabled?: boolean;
+    maxUses?: number;
+    maxContentTokens?: number;
+    allowedDomains?: string[];
+    blockedDomains?: string[];
+    citationsEnabled?: boolean;
+}
+/**
+ * Provider-level custom settings that control built-in web tools.
+ */
+export interface IProviderCustomSettings {
+    webSearch?: IWebSearchSettings;
+    webFetch?: IWebFetchSettings;
+}
+interface IProviderToolContext {
+    providerInfo?: IProviderInfo | null;
+    customSettings?: IProviderCustomSettings;
+    hasFunctionTools: boolean;
+}
+/**
+ * Create provider-defined tools from custom settings and provider capabilities.
+ */
+export declare function createProviderTools(options: IProviderToolContext): ToolMap;
+export {};

package/lib/providers/provider-tools.js

@@ -0,0 +1,93 @@
+import { anthropic } from '@ai-sdk/anthropic';
+import { openai } from '@ai-sdk/openai';
+const DEFAULT_ANTHROPIC_WEB_FETCH_MAX_USES = 2;
+const DEFAULT_ANTHROPIC_WEB_FETCH_MAX_CONTENT_TOKENS = 12000;
+function normalizeDomain(value) {
+    const normalized = (value || '').trim().toLowerCase();
+    const withoutProtocol = normalized.replace(/^https?:\/\//, '');
+    const hostname = withoutProtocol.split('/')[0].trim();
+    // Treat "*.example.com" as "example.com" for provider domain filters.
+    return hostname.startsWith('*.') ? hostname.slice(2) : hostname;
+}
+function collectDomains(value) {
+    value = value || [];
+    const values = Array.from(new Set(value.map(normalizeDomain).filter(domain => domain.length > 0)));
+    return values;
+}
+function createOpenAIWebSearchTool(webSearchSettings) {
+    const allowedDomains = collectDomains(webSearchSettings.allowedDomains);
+    return openai.tools.webSearch({
+        externalWebAccess: webSearchSettings.externalWebAccess,
+        searchContextSize: webSearchSettings.searchContextSize,
+        filters: allowedDomains.length > 0 ? { allowedDomains } : undefined
+    });
+}
+function createAnthropicWebSearchTool(webSearchSettings) {
+    const allowedDomains = collectDomains(webSearchSettings.allowedDomains);
+    const blockedDomains = collectDomains(webSearchSettings.blockedDomains);
+    return anthropic.tools.webSearch_20250305({
+        maxUses: webSearchSettings.maxUses,
+        allowedDomains: allowedDomains.length > 0 ? allowedDomains : undefined,
+        blockedDomains: blockedDomains.length > 0 ? blockedDomains : undefined
+    });
+}
+function createAnthropicWebFetchTool(webFetchSettings) {
+    const maxUses = webFetchSettings.maxUses ?? DEFAULT_ANTHROPIC_WEB_FETCH_MAX_USES;
+    const maxContentTokens = webFetchSettings.maxContentTokens ??
+        DEFAULT_ANTHROPIC_WEB_FETCH_MAX_CONTENT_TOKENS;
+    const allowedDomains = collectDomains(webFetchSettings.allowedDomains);
+    const blockedDomains = collectDomains(webFetchSettings.blockedDomains);
+    const citationsEnabled = webFetchSettings.citationsEnabled;
+    return anthropic.tools.webFetch_20250910({
+        maxUses,
+        maxContentTokens,
+        allowedDomains: allowedDomains.length > 0 ? allowedDomains : undefined,
+        blockedDomains: blockedDomains.length > 0 ? blockedDomains : undefined,
+        citations: citationsEnabled !== undefined ? { enabled: citationsEnabled } : undefined
+    });
+}
+function createWebSearchTool(implementation, webSearchSettings) {
+    switch (implementation) {
+        case 'openai':
+            return createOpenAIWebSearchTool(webSearchSettings);
+        case 'anthropic':
+            return createAnthropicWebSearchTool(webSearchSettings);
+        default:
+            throw new Error(`Unsupported web search implementation: ${implementation}`);
+    }
+}
+function createWebFetchTool(implementation, webFetchSettings) {
+    switch (implementation) {
+        case 'anthropic':
+            return createAnthropicWebFetchTool(webFetchSettings);
+        default:
+            throw new Error(`Unsupported web fetch implementation: ${implementation}`);
+    }
+}
+/**
+ * Create provider-defined tools from custom settings and provider capabilities.
+ */
+export function createProviderTools(options) {
+    const tools = {};
+    if (!options.customSettings ||
+        !options.providerInfo?.providerToolCapabilities) {
+        return tools;
+    }
+    const capabilities = options.providerInfo.providerToolCapabilities;
+    const webSearchSettings = options.customSettings.webSearch;
+    const webFetchSettings = options.customSettings.webFetch;
+    const webSearchEnabled = webSearchSettings?.enabled === true;
+    const webFetchEnabled = webFetchSettings?.enabled === true;
+    const webSearchCapability = capabilities.webSearch;
+    if (webSearchEnabled && webSearchSettings && webSearchCapability) {
+        const requiresNoFunctionTools = webSearchCapability.requiresNoFunctionTools === true;
+        if (!requiresNoFunctionTools || !options.hasFunctionTools) {
+            tools.web_search = createWebSearchTool(webSearchCapability.implementation, webSearchSettings);
+        }
+    }
+    const webFetchCapability = capabilities.webFetch;
+    if (webFetchEnabled && webFetchSettings && webFetchCapability) {
+        tools.web_fetch = createWebFetchTool(webFetchCapability.implementation, webFetchSettings);
+    }
+    return tools;
+}

package/lib/rendered-message-outputarea.d.ts

@@ -0,0 +1,24 @@
+import { ChatWidget } from '@jupyter/chat';
+import { IDisposable } from '@lumino/disposable';
+/**
+ * Ensures chat-rendered MIME outputs also expose the OutputArea class so
+ * renderer extensions can reuse their notebook/output-area CSS rules.
+ *
+ * TODO: Remove this compatibility layer once jupyter-chat applies
+ * `jp-OutputArea` (or equivalent output-area context) to rendered MIME
+ * messages by default.
+ */
+export declare class RenderedMessageOutputAreaCompat implements IDisposable {
+    constructor(options: RenderedMessageOutputAreaCompat.IOptions);
+    get isDisposed(): boolean;
+    dispose(): void;
+    private _scheduleSync;
+    private readonly _chatPanel;
+    private _isDisposed;
+    private _raf;
+}
+export declare namespace RenderedMessageOutputAreaCompat {
+    interface IOptions {
+        chatPanel: ChatWidget;
+    }
+}

package/lib/rendered-message-outputarea.js

@@ -0,0 +1,48 @@
+const OUTPUT_AREA_CLASS = 'jp-OutputArea';
+const CHAT_RENDERED_MESSAGE_SELECTOR = `.jp-chat-rendered-message:not(.${OUTPUT_AREA_CLASS})`;
+/**
+ * Ensures chat-rendered MIME outputs also expose the OutputArea class so
+ * renderer extensions can reuse their notebook/output-area CSS rules.
+ *
+ * TODO: Remove this compatibility layer once jupyter-chat applies
+ * `jp-OutputArea` (or equivalent output-area context) to rendered MIME
+ * messages by default.
+ */
+export class RenderedMessageOutputAreaCompat {
+    constructor(options) {
+        this._chatPanel = options.chatPanel;
+        this._chatPanel.model.messagesUpdated.connect(this._scheduleSync, this);
+        this._scheduleSync();
+    }
+    get isDisposed() {
+        return this._isDisposed;
+    }
+    dispose() {
+        if (this._isDisposed) {
+            return;
+        }
+        this._isDisposed = true;
+        this._chatPanel.model.messagesUpdated.disconnect(this._scheduleSync, this);
+        if (this._raf !== 0) {
+            cancelAnimationFrame(this._raf);
+            this._raf = 0;
+        }
+    }
+    _scheduleSync() {
+        if (this._isDisposed || this._raf !== 0) {
+            return;
+        }
+        this._raf = requestAnimationFrame(() => {
+            this._raf = 0;
+            if (this._isDisposed) {
+                return;
+            }
+            this._chatPanel.node
+                .querySelectorAll(CHAT_RENDERED_MESSAGE_SELECTOR)
+                .forEach(element => element.classList.add(OUTPUT_AREA_CLASS));
+        });
+    }
+    _chatPanel;
+    _isDisposed = false;
+    _raf = 0;
+}

package/lib/skills/index.d.ts

@@ -0,0 +1,4 @@
+export { parseSkillMd, type IParsedSkill } from './parse-skill';
+export { loadSkillsFromPaths, type ISkillFileDefinition } from './skill-loader';
+export type { ISkillDefinition, ISkillRegistration, ISkillResourceResult, ISkillSummary } from './types';
+export { SkillRegistry } from './skill-registry';

package/lib/skills/index.js

@@ -0,0 +1,7 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export { parseSkillMd } from './parse-skill';
+export { loadSkillsFromPaths } from './skill-loader';
+export { SkillRegistry } from './skill-registry';

package/lib/skills/parse-skill.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Parsed skill definition from a SKILL.md file.
+ */
+export interface IParsedSkill {
+    name: string;
+    description: string;
+    instructions: string;
+}
+/**
+ * Parse a SKILL.md file content into a structured skill definition.
+ *
+ * Expected format:
+ * ```
+ * ---
+ * name: my-skill
+ * description: A brief description of the skill
+ * ---
+ * Full instructions body here...
+ * ```
+ *
+ * @param content - The raw content of a SKILL.md file
+ * @returns Parsed skill with name, description, and instructions
+ * @throws Error if the frontmatter is missing or invalid
+ */
+export declare function parseSkillMd(content: string): IParsedSkill;

package/lib/skills/parse-skill.js

@@ -0,0 +1,69 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { parse as parseYaml } from 'yaml';
+/**
+ * Parse a SKILL.md file content into a structured skill definition.
+ *
+ * Expected format:
+ * ```
+ * ---
+ * name: my-skill
+ * description: A brief description of the skill
+ * ---
+ * Full instructions body here...
+ * ```
+ *
+ * @param content - The raw content of a SKILL.md file
+ * @returns Parsed skill with name, description, and instructions
+ * @throws Error if the frontmatter is missing or invalid
+ */
+export function parseSkillMd(content) {
+    const normalizedContent = content
+        .replace(/^\uFEFF/, '')
+        .replace(/\r\n/g, '\n');
+    const lines = normalizedContent.split('\n');
+    if (lines[0]?.trim() !== '---') {
+        throw new Error('Invalid SKILL.md: missing frontmatter delimiters (---)');
+    }
+    const frontmatterLines = [];
+    let i = 1;
+    for (; i < lines.length; i++) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        if (trimmed === '---') {
+            break;
+        }
+        frontmatterLines.push(line);
+    }
+    if (i >= lines.length) {
+        throw new Error('Invalid SKILL.md: missing frontmatter delimiters (---)');
+    }
+    const frontmatter = frontmatterLines.join('\n');
+    const instructions = lines
+        .slice(i + 1)
+        .join('\n')
+        .trim();
+    let metadata;
+    try {
+        metadata = parseYaml(frontmatter);
+    }
+    catch (error) {
+        throw new Error(`Invalid SKILL.md: YAML frontmatter parse failed: ${error}`);
+    }
+    const data = metadata;
+    const name = data?.name;
+    const description = data?.description;
+    if (typeof name !== 'string' || name.trim().length === 0) {
+        throw new Error('Invalid SKILL.md: missing "name" in frontmatter');
+    }
+    if (typeof description !== 'string' || description.trim().length === 0) {
+        throw new Error('Invalid SKILL.md: missing "description" in frontmatter');
+    }
+    return {
+        name: name.trim(),
+        description: description.trim(),
+        instructions
+    };
+}

package/lib/skills/skill-loader.d.ts

@@ -0,0 +1,25 @@
+import { Contents } from '@jupyterlab/services';
+import { IParsedSkill } from './parse-skill';
+/**
+ * A skill definition loaded from the filesystem.
+ */
+export interface ISkillFileDefinition extends IParsedSkill {
+    /**
+     * Path to the skill directory (e.g. ".agents/skills/my-skill").
+     */
+    path: string;
+    /**
+     * Paths to resource files relative to the skill directory.
+     */
+    resources: string[];
+}
+/**
+ * Load skills from multiple directories. Each path is scanned in order;
+ * when the same skill name appears in more than one path, the first
+ * occurrence wins.
+ *
+ * @param contentsManager - The Jupyter contents manager
+ * @param skillsPaths - Ordered list of directories to scan
+ * @returns Merged array of loaded skill definitions
+ */
+export declare function loadSkillsFromPaths(contentsManager: Contents.IManager, skillsPaths: string[]): Promise<ISkillFileDefinition[]>;

package/lib/skills/skill-loader.js

@@ -0,0 +1,133 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { PathExt } from '@jupyterlab/coreutils';
+import { parseSkillMd } from './parse-skill';
+/**
+ * Load skills from multiple directories. Each path is scanned in order;
+ * when the same skill name appears in more than one path, the first
+ * occurrence wins.
+ *
+ * @param contentsManager - The Jupyter contents manager
+ * @param skillsPaths - Ordered list of directories to scan
+ * @returns Merged array of loaded skill definitions
+ */
+export async function loadSkillsFromPaths(contentsManager, skillsPaths) {
+    const seen = new Set();
+    const merged = [];
+    for (const skillsPath of skillsPaths) {
+        const skills = await loadSkills(contentsManager, skillsPath);
+        for (const skill of skills) {
+            if (seen.has(skill.name)) {
+                console.debug(`Skipping duplicate skill "${skill.name}" from "${skillsPath}" (already loaded from an earlier path).`);
+                continue;
+            }
+            seen.add(skill.name);
+            merged.push(skill);
+        }
+    }
+    return merged;
+}
+/**
+ * Load skills from the filesystem by scanning a directory for subdirectories
+ * containing SKILL.md files.
+ *
+ * @param contentsManager - The Jupyter contents manager
+ * @param skillsPath - Path to the skills directory (e.g. ".agents/skills")
+ * @returns Array of loaded skill definitions
+ */
+async function loadSkills(contentsManager, skillsPath) {
+    const skills = [];
+    // Walk each path segment from root to verify the directory exists before fetching it.
+    const segments = skillsPath.split('/').filter(s => s.length > 0);
+    let currentPath = '';
+    for (const segment of segments) {
+        let listing;
+        try {
+            listing = await contentsManager.get(currentPath, { content: true });
+        }
+        catch (error) {
+            console.debug(`Skills path segment not found at "${currentPath}":`, error);
+            return skills;
+        }
+        const children = (listing.content ?? []);
+        if (!children.some(c => c.type === 'directory' && c.name === segment)) {
+            return skills;
+        }
+        currentPath = PathExt.join(currentPath, segment);
+    }
+    const dirModel = await contentsManager.get(skillsPath, { content: true });
+    if (dirModel.type !== 'directory' || !dirModel.content) {
+        return skills;
+    }
+    for (const child of dirModel.content) {
+        if (child.type !== 'directory') {
+            continue;
+        }
+        // List the subdirectory to check if SKILL.md exists before requesting it
+        const subDir = await contentsManager.get(child.path, { content: true });
+        const subChildren = (subDir.content ?? []);
+        if (!subChildren.some(f => f.type === 'file' && f.name === 'SKILL.md')) {
+            continue;
+        }
+        const skillMdPath = `${child.path}/SKILL.md`;
+        const fileModel = await contentsManager.get(skillMdPath, {
+            content: true
+        });
+        if (typeof fileModel.content !== 'string') {
+            console.warn(`Skipping ${skillMdPath}: content is not a string`);
+            continue;
+        }
+        try {
+            const parsed = parseSkillMd(fileModel.content);
+            const resources = await collectResourcePaths(contentsManager, child.path);
+            skills.push({
+                ...parsed,
+                path: child.path,
+                resources
+            });
+        }
+        catch (error) {
+            console.warn(`Skipping skill at ${child.path}:`, error);
+        }
+    }
+    return skills;
+}
+/**
+ * Recursively collect paths to all resource files in a skill directory,
+ * excluding `SKILL.md`. Content is loaded on-demand when the agent
+ * requests a specific resource.
+ */
+async function collectResourcePaths(contentsManager, basePath) {
+    const resourcePaths = [];
+    async function walk(dirPath) {
+        let dirModel;
+        try {
+            dirModel = await contentsManager.get(dirPath, { content: true });
+        }
+        catch (error) {
+            console.warn(`Failed to list directory ${dirPath}:`, error);
+            return;
+        }
+        if (dirModel.type !== 'directory' || !dirModel.content) {
+            return;
+        }
+        for (const item of dirModel.content) {
+            // Skip checkpoint directories
+            if (item.name === '.ipynb_checkpoints') {
+                continue;
+            }
+            if (item.type === 'directory') {
+                await walk(item.path);
+            }
+            else if (item.type === 'file' && item.name !== 'SKILL.md') {
+                // Store path relative to the skill directory
+                const relativePath = PathExt.relative(basePath, item.path);
+                resourcePaths.push(relativePath);
+            }
+        }
+    }
+    await walk(basePath);
+    return resourcePaths;
+}