@jupyterlite/ai 0.11.1 → 0.12.0

package/lib/index.d.ts

@@ -1,9 +1,9 @@
 import { JupyterFrontEndPlugin } from '@jupyterlab/application';
-import { IInputToolbarRegistryFactory } from '@jupyter/chat';
+import { IChatCommandRegistry, IInputToolbarRegistryFactory } from '@jupyter/chat';
 import { AgentManagerFactory } from './agent';
-import { IProviderRegistry, IToolRegistry, IChatModelRegistry, IDiffManager } from './tokens';
+import { IProviderRegistry, IToolRegistry, ISkillRegistry, IChatModelRegistry, IDiffManager } from './tokens';
 import { AISettingsModel } from './models/settings-model';
-declare const _default: (JupyterFrontEndPlugin<IProviderRegistry> | JupyterFrontEndPlugin<void> | JupyterFrontEndPlugin<IChatModelRegistry> | JupyterFrontEndPlugin<AgentManagerFactory> | JupyterFrontEndPlugin<AISettingsModel> | JupyterFrontEndPlugin<IDiffManager> | JupyterFrontEndPlugin<IToolRegistry> | JupyterFrontEndPlugin<IInputToolbarRegistryFactory>)[];
+declare const _default: (JupyterFrontEndPlugin<IProviderRegistry> | JupyterFrontEndPlugin<void> | JupyterFrontEndPlugin<IChatCommandRegistry> | JupyterFrontEndPlugin<IChatModelRegistry> | JupyterFrontEndPlugin<AgentManagerFactory> | JupyterFrontEndPlugin<AISettingsModel> | JupyterFrontEndPlugin<IDiffManager> | JupyterFrontEndPlugin<ISkillRegistry> | JupyterFrontEndPlugin<IToolRegistry> | JupyterFrontEndPlugin<IInputToolbarRegistryFactory>)[];
 export default _default;
 export * from './tokens';
 export * from './icons';

package/lib/index.js

@@ -1,5 +1,5 @@
 import { ILabShell, ILayoutRestorer } from '@jupyterlab/application';
-import { ActiveCellManager, AttachmentOpenerRegistry, chatIcon, ChatWidget, IInputToolbarRegistryFactory, InputToolbarRegistry, MultiChatPanel } from '@jupyter/chat';
+import { ActiveCellManager, AttachmentOpenerRegistry, chatIcon, ChatCommandRegistry, ChatWidget, IChatCommandRegistry, IInputToolbarRegistryFactory, InputToolbarRegistry, MultiChatPanel } from '@jupyter/chat';
 import { ICommandPalette, IThemeManager, WidgetTracker } from '@jupyterlab/apputils';
 import { ICompletionProviderManager } from '@jupyterlab/completer';
 import { IDocumentManager } from '@jupyterlab/docmanager';
@@ -7,22 +7,28 @@ import { INotebookTracker } from '@jupyterlab/notebook';
 import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
 import { ISettingRegistry } from '@jupyterlab/settingregistry';
 import { IStatusBar } from '@jupyterlab/statusbar';
+import { PathExt } from '@jupyterlab/coreutils';
 import { ITranslator, nullTranslator } from '@jupyterlab/translation';
 import { settingsIcon, Toolbar, ToolbarButton } from '@jupyterlab/ui-components';
 import { ISecretsManager, SecretsManager } from 'jupyter-secrets-manager';
 import { PromiseDelegate, UUID } from '@lumino/coreutils';
+import { DisposableSet } from '@lumino/disposable';
 import { AgentManagerFactory } from './agent';
+import { ClearCommandProvider } from './chat-commands/clear';
+import { SkillsCommandProvider } from './chat-commands/skills';
 import { ProviderRegistry } from './providers/provider-registry';
 import { ApprovalButtons } from './approval-buttons';
 import { ChatModelRegistry } from './chat-model-registry';
-import { CommandIds, IAgentManagerFactory, IProviderRegistry, IToolRegistry, SECRETS_NAMESPACE, IAISettingsModel, IChatModelRegistry, IDiffManager } from './tokens';
+import { CommandIds, IAgentManagerFactory, IProviderRegistry, IToolRegistry, ISkillRegistry, SECRETS_NAMESPACE, IAISettingsModel, IChatModelRegistry, IDiffManager } from './tokens';
 import { anthropicProvider, googleProvider, mistralProvider, openaiProvider, genericProvider } from './providers/built-in-providers';
 import { AICompletionProvider } from './completion';
 import { clearItem, createModelSelectItem, createToolSelectItem, stopItem, CompletionStatusWidget, TokenUsageWidget } from './components';
 import { AISettingsModel } from './models/settings-model';
+import { loadSkillsFromPaths, SkillRegistry } from './skills';
 import { DiffManager } from './diff-manager';
 import { ToolRegistry } from './tools/tool-registry';
 import { createDiscoverCommandsTool, createExecuteCommandTool } from './tools/commands';
+import { createDiscoverSkillsTool, createLoadSkillTool } from './tools/skills';
 import { AISettingsWidget } from './widgets/ai-settings';
 import { MainAreaChat } from './widgets/main-area-chat';
 /**
@@ -97,6 +103,45 @@ const genericProviderPlugin = {
         providerRegistry.registerProvider(genericProvider);
     }
 };
+/**
+ * Chat command registry plugin.
+ */
+const chatCommandRegistryPlugin = {
+    id: '@jupyterlite/ai:chat-command-registry',
+    description: 'Provide the chat command registry for JupyterLite AI.',
+    autoStart: true,
+    provides: IChatCommandRegistry,
+    activate: () => {
+        return new ChatCommandRegistry();
+    }
+};
+/**
+ * Clear chat command plugin.
+ */
+const clearCommandPlugin = {
+    id: '@jupyterlite/ai:clear-command',
+    description: 'Register the /clear chat command.',
+    autoStart: true,
+    requires: [IChatCommandRegistry],
+    activate: (app, registry) => {
+        registry.addProvider(new ClearCommandProvider());
+    }
+};
+/**
+ * Skills chat command plugin.
+ */
+const skillsCommandPlugin = {
+    id: '@jupyterlite/ai:skills-command',
+    description: 'Register the /skills chat command.',
+    autoStart: true,
+    requires: [IChatCommandRegistry, ISkillRegistry],
+    activate: (app, registry, skillRegistry) => {
+        registry.addProvider(new SkillsCommandProvider({
+            skillRegistry,
+            commands: app.commands
+        }));
+    }
+};
 /**
  * The chat model registry.
  */
@@ -130,7 +175,8 @@ const plugin = {
         IRenderMimeRegistry,
         IInputToolbarRegistryFactory,
         IChatModelRegistry,
-        IAISettingsModel
+        IAISettingsModel,
+        IChatCommandRegistry
     ],
     optional: [
         IThemeManager,
@@ -139,7 +185,7 @@ const plugin = {
         INotebookTracker,
         ITranslator
     ],
-    activate: (app, rmRegistry, inputToolbarFactory, modelRegistry, settingsModel, themeManager, restorer, labShell, notebookTracker, translator) => {
+    activate: (app, rmRegistry, inputToolbarFactory, modelRegistry, settingsModel, chatCommandRegistry, themeManager, restorer, labShell, notebookTracker, translator) => {
         const trans = (translator ?? nullTranslator).load('jupyterlite_ai');
         // Create attachment opener registry to handle file attachments
         const attachmentOpenerRegistry = new AttachmentOpenerRegistry();
@@ -165,6 +211,7 @@ const plugin = {
             themeManager: themeManager ?? null,
             inputToolbarFactory,
             attachmentOpenerRegistry,
+            chatCommandRegistry,
             createModel: async (name) => {
                 const model = modelRegistry.createModel(name);
                 return { model };
@@ -260,10 +307,10 @@ const plugin = {
                 app.commands.execute(CommandIds.openChat);
             }
         });
-        registerCommands(app, rmRegistry, chatPanel, attachmentOpenerRegistry, inputToolbarFactory, settingsModel, tracker, modelRegistry, trans, themeManager, labShell);
+        registerCommands(app, rmRegistry, chatPanel, attachmentOpenerRegistry, inputToolbarFactory, settingsModel, chatCommandRegistry, tracker, modelRegistry, trans, themeManager, labShell);
     }
 };
-function registerCommands(app, rmRegistry, chatPanel, attachmentOpenerRegistry, inputToolbarFactory, settingsModel, tracker, modelRegistry, trans, themeManager, labShell) {
+function registerCommands(app, rmRegistry, chatPanel, attachmentOpenerRegistry, inputToolbarFactory, settingsModel, chatCommandRegistry, tracker, modelRegistry, trans, themeManager, labShell) {
     const { commands } = app;
     if (labShell) {
         commands.addCommand(CommandIds.reposition, {
@@ -314,7 +361,8 @@ function registerCommands(app, rmRegistry, chatPanel, attachmentOpenerRegistry,
                 rmRegistry,
                 themeManager: themeManager ?? null,
                 inputToolbarRegistry: inputToolbarFactory.create(),
-                attachmentOpenerRegistry
+                attachmentOpenerRegistry,
+                chatCommandRegistry
             });
             const widget = new MainAreaChat({
                 content,
@@ -464,6 +512,7 @@ const agentManagerFactory = SecretsManager.sign(SECRETS_NAMESPACE, token => ({
     provides: IAgentManagerFactory,
     requires: [IAISettingsModel, IProviderRegistry],
     optional: [
+        ISkillRegistry,
         ICommandPalette,
         ICompletionProviderManager,
         ILayoutRestorer,
@@ -471,10 +520,11 @@ const agentManagerFactory = SecretsManager.sign(SECRETS_NAMESPACE, token => ({
         IThemeManager,
         ITranslator
     ],
-    activate: (app, settingsModel, providerRegistry, palette, completionManager, restorer, secretsManager, themeManager, translator) => {
+    activate: (app, settingsModel, providerRegistry, skillRegistry, palette, completionManager, restorer, secretsManager, themeManager, translator) => {
         const trans = (translator ?? nullTranslator).load('jupyterlite_ai');
         const agentManagerFactory = new AgentManagerFactory({
             settingsModel,
+            skillRegistry,
             secretsManager,
             token
         });
@@ -567,19 +617,36 @@ const diffManager = {
         });
     }
 };
+/**
+ * Skill registry plugin
+ */
+const skillRegistryPlugin = {
+    id: '@jupyterlite/ai:skill-registry',
+    description: 'Provide the skill registry',
+    autoStart: true,
+    provides: ISkillRegistry,
+    activate: () => {
+        return new SkillRegistry();
+    }
+};
 const toolRegistry = {
     id: '@jupyterlite/ai:tool-registry',
     description: 'Provide the AI tool registry',
     autoStart: true,
     requires: [IAISettingsModel],
+    optional: [ISkillRegistry],
     provides: IToolRegistry,
-    activate: (app, settingsModel) => {
+    activate: (app, settingsModel, skillRegistry) => {
         const toolRegistry = new ToolRegistry();
         // Add command operation tools
         const discoverCommandsTool = createDiscoverCommandsTool(app.commands);
         const executeCommandTool = createExecuteCommandTool(app.commands, settingsModel);
         toolRegistry.add('discover_commands', discoverCommandsTool);
         toolRegistry.add('execute_command', executeCommandTool);
+        if (skillRegistry) {
+            toolRegistry.add('discover_skills', createDiscoverSkillsTool(skillRegistry));
+            toolRegistry.add('load_skill', createLoadSkillTool(skillRegistry));
+        }
         return toolRegistry;
     }
 };
@@ -643,6 +710,111 @@ const completionStatus = {
         });
     }
 };
+/**
+ * Skills plugin: discovers and registers agent skills from the filesystem.
+ */
+const skillsPlugin = {
+    id: '@jupyterlite/ai:skills',
+    description: 'Discover and register agent skills',
+    autoStart: true,
+    requires: [IAISettingsModel, IDocumentManager, ISkillRegistry],
+    optional: [ICommandPalette, ITranslator],
+    activate: async (app, settingsModel, docManager, skillRegistry, palette, translator) => {
+        const trans = (translator ?? nullTranslator).load('jupyterlite_ai');
+        const validateResourcePath = (resourcePath) => {
+            if (resourcePath.startsWith('/')) {
+                return null;
+            }
+            const normalized = PathExt.normalize(resourcePath);
+            if (normalized.startsWith('..') || normalized === '') {
+                return null;
+            }
+            return normalized;
+        };
+        let currentSkillsPaths = settingsModel.config.skillsPaths;
+        let currentSkillDisposables = new DisposableSet();
+        const loadAndRegister = async () => {
+            const skillsPaths = settingsModel.config.skillsPaths;
+            const skills = await loadSkillsFromPaths(docManager.services.contents, skillsPaths);
+            const registrations = skills.map(skill => ({
+                name: skill.name,
+                description: skill.description,
+                instructions: skill.instructions,
+                resources: skill.resources,
+                loadResource: async (resource) => {
+                    const validatedPath = validateResourcePath(resource);
+                    if (validatedPath === null) {
+                        return {
+                            name: skill.name,
+                            resource,
+                            error: 'Invalid resource path: path traversal not allowed'
+                        };
+                    }
+                    if (!skill.resources.includes(validatedPath)) {
+                        return {
+                            name: skill.name,
+                            resource,
+                            error: `Resource not found: ${resource}`
+                        };
+                    }
+                    const resourcePath = `${skill.path}/${validatedPath}`;
+                    try {
+                        const fileModel = await docManager.services.contents.get(resourcePath, {
+                            content: true
+                        });
+                        if (typeof fileModel.content !== 'string') {
+                            return {
+                                name: skill.name,
+                                resource,
+                                error: 'Resource content is not a string'
+                            };
+                        }
+                        return {
+                            name: skill.name,
+                            resource,
+                            content: fileModel.content
+                        };
+                    }
+                    catch (error) {
+                        return {
+                            name: skill.name,
+                            resource,
+                            error: `Failed to read resource: ${error}`
+                        };
+                    }
+                }
+            }));
+            currentSkillDisposables.dispose();
+            currentSkillDisposables = new DisposableSet();
+            for (const registration of registrations) {
+                currentSkillDisposables.add(skillRegistry.registerSkill(registration));
+            }
+        };
+        app.commands.addCommand(CommandIds.refreshSkills, {
+            label: trans.__('Refresh Agents Skills'),
+            caption: trans.__('Re-scan the agents skills directory and update the registry'),
+            execute: async () => {
+                await loadAndRegister();
+            }
+        });
+        if (palette) {
+            palette.addItem({
+                command: CommandIds.refreshSkills,
+                category: trans.__('AI Assistant')
+            });
+        }
+        loadAndRegister().catch(error => console.warn('Failed to load skills on activation:', error));
+        settingsModel.stateChanged.connect(() => {
+            const newPaths = settingsModel.config.skillsPaths;
+            if (newPaths.length === currentSkillsPaths.length &&
+                newPaths.every((p, i) => p === currentSkillsPaths[i])) {
+                return;
+            }
+            currentSkillsPaths = newPaths;
+            loadAndRegister().catch(error => console.warn('Failed to reload skills:', error));
+        });
+    }
+};
 export default [
     providerRegistryPlugin,
     anthropicProviderPlugin,
@@ -652,12 +824,17 @@ export default [
     genericProviderPlugin,
     settingsModel,
     diffManager,
+    chatCommandRegistryPlugin,
+    clearCommandPlugin,
+    skillRegistryPlugin,
+    skillsCommandPlugin,
     chatModelRegistry,
     plugin,
     toolRegistry,
     agentManagerFactory,
     inputToolbarFactory,
-    completionStatus
+    completionStatus,
+    skillsPlugin
 ];
 // Export extension points for other extensions to use
 export * from './tokens';

package/lib/models/settings-model.d.ts

@@ -44,6 +44,7 @@ export interface IAIConfig {
     showCellDiff: boolean;
     showFileDiff: boolean;
     diffDisplayMode: 'split' | 'unified';
+    skillsPaths: string[];
 }
 export declare class AISettingsModel extends VDomModel {
     private _config;

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',
@@ -51,7 +52,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 +69,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 +103,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 +138,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',
@@ -60,7 +61,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 +155,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',

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[]>;