shortcutxl 0.2.14 → 0.2.16

package/README.md

@@ -1,13 +1,33 @@
 # ShortcutXL
 
-An AI agent that lives on your computer and has Excel superpowers. Made by the Shortcut team [Shortcut](https://shortcut.ai).
+An AI agent that lives on your computer and has Excel superpowers. Made by the [Shortcut](https://shortcut.ai) team.
+
+## Install
+
+### 1. Open Command Prompt or PowerShell and install Node.js
+
+```bash
+winget install OpenJS.NodeJS.LTS
+```
+
+### 2. Install ShortcutXL
 
 ```bash
 npm install -g shortcutxl
+```
+
+### 3. Launch ShortcutXL
+
+Type `shortcut` in your terminal:
+
+```bash
 shortcut
 ```
 
-> **Important:** Install globally with `-g`. Do not use `npm install shortcutxl` without it.
+## Requirements
+
+- **Windows 10/11** with **Excel 2016+** (64-bit)
+- **Node.js >= 20**
 
 ## Capabilities
 
@@ -19,8 +39,3 @@ shortcut
 - **Extensible** — Integrate any API or data source by adding a skill file or a custom tool extension.
 - **User-defined functions (UDFs)** — Custom Excel formulas powered by Python for live data, calculations, or database queries.
 - **External data connections** — ODBC, OLE DB, QueryTables, Power Query.
-
-## Prerequisites
-
-- **Windows 10/11** with **Excel 2016+** (64-bit)
-- **Node.js >= 20** — If missing: `winget install OpenJS.NodeJS.LTS`

package/dist/cli.js

@@ -14,6 +14,8 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const agentRoot = resolve(__dirname, '..');
 dotenv.config({ path: resolve(agentRoot, '.env.development') });
 process.title = 'shortcut';
+// Clear terminal (scrollback + visible area) for a clean slate on launch.
+process.stdout.write('\x1b[2J\x1b[3J\x1b[H');
 const { main } = await import('./main.js');
 main(process.argv.slice(2));
 //# sourceMappingURL=cli.js.map

package/dist/core/system-prompt.js

@@ -45,11 +45,6 @@ export function buildSystemPrompt(options = {}) {
                 prompt += `## ${filePath}\n\n${content}\n\n`;
             }
         }
-        // Append skills section (only if read tool is available)
-        const customPromptHasRead = !selectedTools || selectedTools.includes(READ);
-        if (customPromptHasRead && skills.length > 0) {
-            prompt += formatSkillsForPrompt(skills);
-        }
         // Add date/time and working directory last
         prompt += `\n\nCurrent date and time: ${dateTime}`;
         prompt += `\nCurrent working directory: ${resolvedCwd}`;

package/dist/custom/prompts/action.js

@@ -2,15 +2,16 @@
  * Action-mode system prompt for the Shortcut agent.
  *
  * This is the normal post-installation prompt. Passed as `customPrompt` to
- * the core buildSystemPrompt(), which automatically appends: project context
- * files, skills, date/time, and cwd.
+ * the core buildSystemPrompt(), which appends only: project context files,
+ * date/time, and cwd. Skills are loaded and injected here directly.
  *
  * The prompt does NOT embed runtime-discovered paths (xllDir, modulesPath).
  * Those are shown in the TUI status line. The agent discovers them dynamically
  * via the health check endpoint or excel_exec.
  */
 import { join, resolve } from 'path';
-import { getAgentDir, getInstalledMarkerPath, getPackageDir, getSessionsDir } from '../../config.js';
+import { getAgentDir, getBundledSkillsDir, getInstalledMarkerPath, getPackageDir, getSessionsDir } from '../../config.js';
+import { loadSkills } from '../../core/skills.js';
 import { EXCEL_HTTP_URL } from '../constants.js';
 import { EXCEL_COM_API_GUIDELINES } from './api.js';
 import { CODING_GUIDELINES, COMMUNICATION_GUIDELINES, DATA_FORMATTING_GUIDELINES, EXPLORATION_GUIDELINES, NOTES_COMMENTS_GUIDELINES, NUMBER_FORMAT_REFERENCE } from './shared.js';
@@ -66,10 +67,15 @@ For any extension requests, ask the user which approach fits their need, or reco
 const INSTALLATION = (markerPath) => `\
 ## Installation
 The installed marker file is at \`${markerPath}\`. If the user needs to re-run installation (e.g. something is broken), delete this file and use switch_mode to switch to "installation" mode`;
-const DOCS = (paths) => `\
+const SELF_REFERENCE = (paths) => `\
+======================
+## SELF REFERENCE
+======================
+
 ## Key Directories
 - Package directory (shipped code, read-only): ${paths.packageDir}
 - Agent directory (user config, state, XLL binaries): ${paths.agentDir}
+- User skills (create new skills here): ${paths.userSkillsDir}
 - Sessions (prior conversation JSONL transcripts): ${paths.sessionsDir}
 - Temp directory (dump temporary/scratch files here, e.g. exported Excel files): ${paths.tempDir}
 
@@ -86,33 +92,56 @@ Read these for introspection, customization, debugging of Shortcut itself, its S
 - Examples: ${paths.examples} (extensions, custom tools, SDK)
 - Topics: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI (docs/tui.md), keybindings (docs/keybindings.md), SDK (docs/sdk.md), custom providers (docs/custom-provider.md), models (docs/models.md), packages (docs/packages.md)
 - Always read Shortcut .md files completely and follow links to related docs`;
+const SKILLS = (skills, userSkillsDir) => {
+    const visible = skills.filter((s) => !s.disableModelInvocation);
+    const lines = [
+        '======================',
+        '## SKILLS',
+        '======================',
+        'The following skills provide specialized instructions for specific tasks.',
+        'When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md).',
+        '',
+        `To create a new user skill: ${userSkillsDir}/<skill-name>/SKILL.md`,
+        'Format:',
+        '  ---',
+        '  name: <skill-name>       # must match the parent directory name',
+        '  description: "..."       # one-line summary shown here; max 1024 chars',
+        '  ---',
+        '  <skill body — clear and concise instructions the agent reads when the skill is invoked>',
+        ''
+    ];
+    for (const skill of visible) {
+        lines.push(`- ${skill.name} (${skill.filePath}): ${skill.description}`);
+    }
+    return lines.join('\n');
+};
 // ---------------------------------------------------------------------------
-// Assembly — resolves runtime paths, joins sections
+// Assembly — resolves runtime paths, loads skills, joins sections
 // ---------------------------------------------------------------------------
 export function buildActionPrompt() {
+    const agentDir = getAgentDir();
     const agentDocsDir = resolve(join(getPackageDir(), 'agent-docs'));
     const installedMarker = getInstalledMarkerPath();
-    return [
+    const userSkillsDir = join(agentDir, 'skills');
+    const { skills } = loadSkills({ agentDir, skillPaths: [getBundledSkillsDir()] });
+    const skillsSection = SKILLS(skills, userSkillsDir);
+    const sections = [
         CORE(),
         INSTALLATION(installedMarker),
-        EXPLORATION_GUIDELINES,
-        DATA_FORMATTING_GUIDELINES,
-        NUMBER_FORMAT_REFERENCE,
-        NOTES_COMMENTS_GUIDELINES,
-        CODING_GUIDELINES,
-        COMMUNICATION_GUIDELINES,
-        DOCS({
+        SELF_REFERENCE({
             packageDir: getPackageDir(),
-            agentDir: getAgentDir(),
+            agentDir,
+            userSkillsDir: join(agentDir, 'skills'),
             sessionsDir: getSessionsDir(),
-            tempDir: join(getAgentDir(), 'temp'),
+            tempDir: join(agentDir, 'temp'),
             xllSpec: join(agentDocsDir, 'xll-spec.md'),
             xllSkill: join(agentDocsDir, 'xll-skill.md'),
             readme: join(agentDocsDir, 'README.md'),
             docs: join(agentDocsDir, 'docs'),
             examples: join(agentDocsDir, 'examples')
-        }),
-        EXCEL_COM_API_GUIDELINES
-    ].join('\n\n');
+        })
+    ];
+    sections.push(skillsSection, COMMUNICATION_GUIDELINES, CODING_GUIDELINES, EXPLORATION_GUIDELINES, DATA_FORMATTING_GUIDELINES, NUMBER_FORMAT_REFERENCE, NOTES_COMMENTS_GUIDELINES, EXCEL_COM_API_GUIDELINES);
+    return sections.join('\n\n');
 }
 //# sourceMappingURL=action.js.map

package/dist/custom/tools/excel-approval.js

@@ -42,6 +42,7 @@ function padVisible(text, targetWidth) {
 export class ExcelApprovalComponent extends Container {
     selectedButton = 0;
     scrollOffset = 0;
+    cursorRow = 0;
     diff;
     theme;
     onDone;
@@ -63,7 +64,8 @@ export class ExcelApprovalComponent extends Container {
         this.tableContainer = new Container();
         this.addChild(this.tableContainer);
         if (diff.total > diff.cells.length) {
-            this.addChild(new Text(theme.fg('dim', `  ... and ${diff.total - diff.cells.length} more cells`), 0, 0));
+            const hidden = diff.total - diff.cells.length;
+            this.addChild(new Text(theme.fg('dim', `  ... ${hidden} more cell${hidden !== 1 ? 's' : ''} not shown`), 0, 0));
         }
         this.addChild(new Spacer(1));
         this.buttonContainer = new Container();
@@ -77,51 +79,58 @@ export class ExcelApprovalComponent extends Container {
         const cells = this.diff.cells;
         const visible = cells.slice(this.scrollOffset, this.scrollOffset + MAX_VISIBLE_ROWS);
         // Compute column widths from visible data
-        const colWidths = { cell: 4, before: 6, after: 5, formula: 7 };
+        const colWidths = { addr: 7, before: 6, after: 5, detail: 7 };
         for (const c of visible) {
-            colWidths.cell = Math.max(colWidths.cell, String(c.cell).length);
+            colWidths.addr = Math.max(colWidths.addr, String(c.address).length);
             colWidths.before = Math.max(colWidths.before, String(c.before).length);
             colWidths.after = Math.max(colWidths.after, String(c.after).length);
-            const formulaText = c.formula || c.oldFormula || '';
-            colWidths.formula = Math.max(colWidths.formula, formulaText.length);
+            colWidths.detail = Math.max(colWidths.detail, (c.formula || c.oldFormula || '').length);
         }
-        colWidths.cell = Math.min(colWidths.cell, 20);
+        colWidths.addr = Math.min(colWidths.addr, 24);
         colWidths.before = Math.min(colWidths.before, 16);
         colWidths.after = Math.min(colWidths.after, 16);
-        colWidths.formula = Math.min(colWidths.formula, 30);
+        colWidths.detail = Math.min(colWidths.detail, 30);
         // Header
         const header = '  ' +
-            this.theme.fg('dim', padVisible('Cell', colWidths.cell) +
+            this.theme.fg('dim', padVisible('Address', colWidths.addr) +
                 '  ' +
                 padVisible('Before', colWidths.before) +
                 '  ' +
                 padVisible('After', colWidths.after) +
                 '  ' +
-                padVisible('Formula', colWidths.formula));
+                padVisible('Detail', colWidths.detail));
         this.tableContainer.addChild(new Text(header, 0, 0));
-        // Rows
-        for (const c of visible) {
-            const cellStr = truncateToWidth(String(c.cell), colWidths.cell, '..', true);
+        for (let idx = 0; idx < visible.length; idx++) {
+            const c = visible[idx];
+            const absIdx = this.scrollOffset + idx;
+            const isCursor = absIdx === this.cursorRow;
+            const marker = isCursor ? '▸ ' : '  ';
+            const addrStr = truncateToWidth(String(c.address), colWidths.addr, '..', true);
             const beforeStr = truncateToWidth(String(c.before), colWidths.before, '..', true);
             const afterStr = truncateToWidth(String(c.after), colWidths.after, '..', true);
-            const formulaStr = c.formula
-                ? truncateToWidth(c.formula, colWidths.formula, '..', true)
-                : c.oldFormula
-                    ? truncateToWidth(this.theme.fg('dim', c.oldFormula), colWidths.formula, '..', true)
-                    : padVisible(this.theme.fg('dim', 'hardcoded'), colWidths.formula);
-            const row = '  ' +
-                this.theme.fg('text', padVisible(cellStr, colWidths.cell)) +
+            let detailStr;
+            if (c.formula) {
+                detailStr = truncateToWidth(c.formula, colWidths.detail, '..', true);
+            }
+            else if (c.oldFormula) {
+                detailStr = truncateToWidth(this.theme.fg('dim', c.oldFormula), colWidths.detail, '..', true);
+            }
+            else {
+                detailStr = padVisible(this.theme.fg('dim', 'hardcoded'), colWidths.detail);
+            }
+            const row = marker +
+                this.theme.fg(isCursor ? 'accent' : 'text', padVisible(addrStr, colWidths.addr)) +
                 '  ' +
                 this.theme.fg(c.before !== 'empty' ? 'error' : 'dim', padVisible(beforeStr, colWidths.before)) +
                 '  ' +
                 this.theme.fg('accent', padVisible(afterStr, colWidths.after)) +
                 '  ' +
-                formulaStr;
+                detailStr;
             this.tableContainer.addChild(new Text(row, 0, 0));
         }
         if (cells.length > MAX_VISIBLE_ROWS) {
             const scrollInfo = `  ${this.scrollOffset + 1}-${Math.min(this.scrollOffset + MAX_VISIBLE_ROWS, cells.length)} of ${cells.length}`;
-            this.tableContainer.addChild(new Text(this.theme.fg('dim', scrollInfo + '  (\u2191\u2193 scroll)'), 0, 0));
+            this.tableContainer.addChild(new Text(this.theme.fg('dim', scrollInfo + '  (\u2191\u2193 navigate)'), 0, 0));
         }
     }
     updateButtons() {
@@ -145,29 +154,37 @@ export class ExcelApprovalComponent extends Container {
             }
         }
         this.buttonContainer.addChild(new Text('  ' + parts.join('  '), 0, 0));
-        this.buttonContainer.addChild(new Text(this.theme.fg('dim', '  \u2190\u2192 navigate  enter select  esc cancel'), 0, 0));
+        this.buttonContainer.addChild(new Text(this.theme.fg('dim', '  \u2191\u2193 navigate  \u2190\u2192 select  enter confirm  esc cancel'), 0, 0));
+    }
+    moveCursor(delta) {
+        const maxRow = this.diff.cells.length - 1;
+        const next = Math.max(0, Math.min(maxRow, this.cursorRow + delta));
+        if (next === this.cursorRow)
+            return;
+        this.cursorRow = next;
+        if (this.cursorRow < this.scrollOffset) {
+            this.scrollOffset = this.cursorRow;
+        }
+        else if (this.cursorRow >= this.scrollOffset + MAX_VISIBLE_ROWS) {
+            this.scrollOffset = this.cursorRow - MAX_VISIBLE_ROWS + 1;
+        }
+        this.updateTable();
     }
     handleInput(keyData) {
         const kb = getEditorKeybindings();
-        if (keyData === '\x1b[D' || keyData === 'h') {
+        if (kb.matches(keyData, 'cursorLeft') || keyData === 'h') {
             this.selectedButton = Math.max(0, this.selectedButton - 1);
             this.updateButtons();
         }
-        else if (keyData === '\x1b[C' || keyData === 'l') {
+        else if (kb.matches(keyData, 'cursorRight') || keyData === 'l') {
             this.selectedButton = Math.min(BUTTONS.length - 1, this.selectedButton + 1);
             this.updateButtons();
         }
-        else if (keyData === '\x1b[A' || keyData === 'k') {
-            if (this.scrollOffset > 0) {
-                this.scrollOffset--;
-                this.updateTable();
-            }
+        else if (kb.matches(keyData, 'selectUp') || keyData === 'k') {
+            this.moveCursor(-1);
         }
-        else if (keyData === '\x1b[B' || keyData === 'j') {
-            if (this.scrollOffset + MAX_VISIBLE_ROWS < this.diff.cells.length) {
-                this.scrollOffset++;
-                this.updateTable();
-            }
+        else if (kb.matches(keyData, 'selectDown') || keyData === 'j') {
+            this.moveCursor(1);
         }
         else if (kb.matches(keyData, 'selectConfirm') || keyData === '\n' || keyData === '\r') {
             this.onDone(BUTTONS[this.selectedButton]);

package/dist/custom/tools/switch-mode.js

@@ -68,8 +68,8 @@ export function createSwitchModeTool(session) {
                 };
             }
             const s = session();
-            s.setBaseSystemPrompt(target.systemPrompt);
             s.setActiveToolsByName([...target.tools]);
+            s.setBaseSystemPrompt(target.systemPrompt);
             currentModeRef = target.name;
             // Snapshot the new system prompt + tools into the session trace so the
             // JSONL reflects the mode switch (otherwise only the initial prompt is recorded).

package/dist/modes/interactive/interactive-mode.js

@@ -1603,10 +1603,12 @@ export class InteractiveMode {
             // No image — check if clipboard contains a file path
             if (this.tryAttachClipboardFilePath()) {
                 this.ui.requestRender();
+                return;
             }
+            this.showStatus('Nothing to attach — clipboard has no image or file path');
         }
-        catch {
-            // Silently ignore clipboard errors (may not have permission, etc.)
+        catch (err) {
+            this.showError(`Clipboard paste failed: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
     /**

package/dist/utils/clipboard-image.js

@@ -83,6 +83,36 @@ function runCommand(command, args, options) {
         : Buffer.from(result.stdout ?? '', typeof result.stdout === 'string' ? 'utf-8' : undefined);
     return { ok: true, stdout };
 }
+/**
+ * PowerShell fallback for Windows image reading.
+ * Handles BMP/DIB format (Snipping Tool, Win+Shift+S) and cases where the
+ * native @mariozechner/clipboard module is unavailable or returns hasImage()=false.
+ * Saves clipboard image as PNG via System.Windows.Forms and returns base64-encoded bytes.
+ */
+function readClipboardImageViaPowerShell() {
+    const result = runCommand('powershell.exe', [
+        '-NoProfile',
+        '-Command',
+        'Add-Type -AssemblyName System.Windows.Forms; ' +
+            '$img = [System.Windows.Forms.Clipboard]::GetImage(); ' +
+            'if ($img -eq $null) { exit 1 }; ' +
+            '$ms = New-Object System.IO.MemoryStream; ' +
+            '$img.Save($ms, [System.Drawing.Imaging.ImageFormat]::Png); ' +
+            '[System.Convert]::ToBase64String($ms.ToArray())'
+    ], { timeoutMs: 8000 });
+    if (!result.ok || result.stdout.length === 0)
+        return null;
+    try {
+        const base64 = result.stdout.toString('utf-8').trim();
+        const bytes = Buffer.from(base64, 'base64');
+        if (bytes.length === 0)
+            return null;
+        return { bytes, mimeType: 'image/png' };
+    }
+    catch {
+        return null;
+    }
+}
 function readClipboardImageViaWlPaste() {
     const list = runCommand('wl-paste', ['--list-types'], { timeoutMs: DEFAULT_LIST_TIMEOUT_MS });
     if (!list.ok) {
@@ -137,8 +167,22 @@ export async function readClipboardImage(options) {
     if (platform === 'linux' && isWaylandSession(env)) {
         image = readClipboardImageViaWlPaste() ?? readClipboardImageViaXclip();
     }
+    else if (platform === 'win32') {
+        // Try native module first (fast), then PowerShell fallback.
+        // PowerShell catches BMP/DIB format (Snipping Tool, Win+Shift+S) which
+        // hasImage() misses, and also works when the native module fails to load.
+        if (clipboard?.hasImage()) {
+            const imageData = await clipboard.getImageBinary();
+            if (imageData && imageData.length > 0) {
+                const bytes = imageData instanceof Uint8Array ? imageData : Uint8Array.from(imageData);
+                image = { bytes, mimeType: 'image/png' };
+            }
+        }
+        image ??= readClipboardImageViaPowerShell();
+    }
     else {
-        if (!clipboard || !clipboard.hasImage()) {
+        // macOS and other platforms
+        if (!clipboard?.hasImage()) {
             return null;
         }
         const imageData = await clipboard.getImageBinary();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shortcutxl",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "type": "module",
   "files": [
     "dist/",
@@ -33,6 +33,7 @@
     "format:check": "prettier --check 'src/**/*.{ts,tsx,js,json}'",
     "test": "vitest --run",
     "test:e2e": "vitest --run --config vitest.e2e.config.ts",
+    "release": "node -e \"const v=require('./package.json').version;const t='shortcutxl/v'+v;require('child_process').execSync('git tag '+t,{stdio:'inherit'});require('child_process').execSync('git push origin '+t,{stdio:'inherit'});console.log('Tagged and pushed '+t)\"",
     "test:watch": "vitest",
     "knip": "knip",
     "lint:python": "cd .. && uvx ruff check modules/ tests/",

package/xll/modules/debug_render.py

@@ -71,7 +71,6 @@ def debug_grid_test():
 
         def _do(app):
             sheet = app.ActiveSheet
-            top = sheet.Range("Z5").Cells(1, 1)
             sheet.Range("Z5:AD9").Value = grid
 
         shortcut_xl.xl_batch(_do)
@@ -107,7 +106,7 @@ def debug_grid_tuple_test():
             sheet.Range("Z5:AD9").Value = grid
 
         shortcut_xl.xl_batch(_do)
-        xl_log(f"debug_grid_tuple_test: wrote tuple grid to Z5:AD9")
+        xl_log("debug_grid_tuple_test: wrote tuple grid to Z5:AD9")
         return "Wrote tuple-of-tuples 5x5 to Z5:AD9"
     except Exception as e:
         xl_log(f"debug_grid_tuple_test FAILED: {e}")
@@ -207,9 +206,7 @@ def debug_frame_ascii():
             row = []
             for c in range(WIDTH):
                 ch = "."  # visible empty (not "")
-                if c == 0 and paddle_l <= r < paddle_l + PADDLE_H:
-                    ch = "|"
-                elif c == WIDTH - 1 and paddle_r <= r < paddle_r + PADDLE_H:
+                if c == 0 and paddle_l <= r < paddle_l + PADDLE_H or c == WIDTH - 1 and paddle_r <= r < paddle_r + PADDLE_H:
                     ch = "|"
                 elif r == ball_y and c == ball_x:
                     ch = "O"