feat: add batch mode CLI command for bulk operations (#464)

* feat: add batch mode CLI command for bulk operations (#463)

Add 'excelcli batch' command that executes multiple CLI commands in a single
process launch, eliminating per-process startup overhead and terminal buffer
saturation for agents performing bulk operations.

Key features:
- Session auto-capture from session.open/create results
- NDJSON output (one JSON result per line)
- --stop-on-error flag to halt on first failure
- --input <file> for JSON array or NDJSON input
- --session <id> to pre-set default session

Includes 13 integration tests covering:
- Single/multiple command execution
- Continue-on-error and stop-on-error behavior
- Input validation (empty array, missing command, file not found)
- NDJSON output format verification
- NDJSON input format support
- Exit code semantics

Bug fixes included:
- Fix 'unknown' category fallback in source generators
- Add HasMcpToolAttribute filter for MCP tool generation
- Escape Spectre.Console markup chars in CLI descriptions
- Fix wrong param names in conditionalformat.md and slicer.md
- Fix bash to PowerShell syntax in skills docs
- Strip skills/README.md to minimal content

* docs: update CHANGELOG for batch mode and bug fixes

---------

Co-authored-by: Stefan Broenner <[email protected]>

Author: sbroenne

CHANGELOG.md

@@ -13,10 +13,17 @@ This changelog covers all components:
 ### Added
 
 - **CLI `--output` flag** for all commands: Save command output directly to a file. Screenshot commands automatically save decoded PNG images instead of base64 JSON
+- **CLI Batch Mode** (#463): New `excelcli batch` command executes multiple CLI commands from a JSON file in a single process launch
+  - Session auto-capture from `session.open`/`session.create`, auto-clear on `session.close`
+  - NDJSON output for machine-readable results
+  - `--stop-on-error` flag to halt on first failure (default: continue all)
 
 ### Fixed
 
 - **Screenshot reliability**: Screenshots now work reliably regardless of whether Excel is visible or hidden. Added automatic retry for transient capture failures
+- **CLI `--help` crash** (#463): Fixed Spectre.Console markup crash when parameter descriptions contain `[`/`]` characters (e.g., `[A1 notation]`)
+- **Source generator tool filtering**: Fixed `mcpTool ?? "unknown"` fallback; added `HasMcpToolAttribute` to correctly filter MCP-only tools
+- **Skills docs parameter names**: Fixed wrong CLI parameter names in `conditionalformat.md` and `slicer.md` reference files
 
 ## [1.7.2] - 2026-02-15
 

skills/README.md

@@ -1,198 +1,37 @@
 # Excel MCP Server - Agent Skills
 
-Cross-platform AI assistant guidance for Excel MCP Server, following the emerging Agent Skills specification.
-
-## Two Skills for Different Use Cases
+Two skill packages for AI coding assistants:
 
 | Skill | Target | Best For |
 |-------|--------|----------|
-| **[excel-cli](excel-cli/SKILL.md)** | CLI Tool | **Coding agents** (Copilot, Cursor, Windsurf) - token-efficient, `--help` discoverable |
-| **[excel-mcp](excel-mcp/SKILL.md)** | MCP Server | **Conversational AI** (Claude Desktop, VS Code Chat) - rich tool schemas, exploratory workflows |
-
-### When to use CLI (Recommended for Coding Agents)
-
-Modern coding agents increasingly favor CLI-based workflows over MCP because:
-- **Token-efficient**: No large tool schemas loaded into context
-- **Discoverable**: Agents can run `excelcli --help` to learn commands
-- **Scriptable**: Works in PowerShell pipelines, CI/CD, batch processing
-- **Quiet mode**: `-q` flag outputs clean JSON only
-
-```powershell
-# Coding agent workflow
-excelcli -q session open C:\Data\Report.xlsx
-excelcli -q range set-values --session 1 --sheet Sheet1 --range A1 --values-json '[["Hello"]]'
-excelcli -q session close --session 1 --save
-```
-
-### When to use MCP Server
-
-MCP remains relevant for:
-- Exploratory automation with iterative reasoning
-- Self-healing workflows needing rich introspection  
-- Long-running autonomous tasks with continuous context
-- Conversational interfaces (Claude Desktop, VS Code Chat)
+| **[excel-cli](excel-cli/SKILL.md)** | CLI Tool | Coding agents - token-efficient, `--help` discoverable |
+| **[excel-mcp](excel-mcp/SKILL.md)** | MCP Server | Conversational AI - rich tool schemas |
 
-## What Are Agent Skills?
-
-Agent Skills are reusable instruction sets that extend AI coding assistants with domain-specific knowledge. They enable consistent, reliable behavior when working with specific tools like Excel MCP Server.
-
-## Supported Platforms
-
-| Platform | Install Location | Auto-Install |
-|----------|------------------|--------------|
-| **GitHub Copilot** | `~/.copilot/skills/excel-mcp/` | Via VS Code extension |
-| **Claude Code** | `.claude/skills/excel-mcp/` | Manual or npx |
-| **Cursor** | `.cursor/skills/excel-mcp/` | Manual or npx |
-| **Windsurf** | `.windsurf/skills/excel-mcp/` | Manual or npx |
-| **Gemini CLI** | `.gemini/skills/excel-mcp/` | Manual or npx |
-| **Goose** | `.goose/skills/excel-mcp/` | Manual or npx |
-
-## Installation Methods
-
-### Method 1: VS Code Extension (Copilot)
-
-Install the [Excel MCP Server extension](https://marketplace.visualstudio.com/items?itemName=sbroenne.excel-mcp) - skills are installed automatically to `~/.copilot/skills/`.
-
-Enable skills in VS Code settings:
-```json
-{
-  "chat.useAgentSkills": true
-}
-```
-
-### Method 2: npx skills add (Cross-Platform)
-
-The repository contains TWO skills. The CLI will prompt you to select which one(s) to install:
+## Installation
 
 ```bash
-# Interactive install - prompts to select excel-cli, excel-mcp, or both
-npx skills add sbroenne/mcp-server-excel
-
-# Install specific skill directly
+# Via VS Code extension (auto-installs excel-mcp)
+# Or via npx:
 npx skills add sbroenne/mcp-server-excel --skill excel-cli   # Coding agents
 npx skills add sbroenne/mcp-server-excel --skill excel-mcp   # Conversational AI
-
-# Install both skills
-npx skills add sbroenne/mcp-server-excel --skill '*'
-
-# Install for specific agent
-npx skills add sbroenne/mcp-server-excel --skill excel-cli -a cursor
-npx skills add sbroenne/mcp-server-excel --skill excel-mcp -a claude-code
-
-# Install globally (user-wide)
-npx skills add sbroenne/mcp-server-excel --skill excel-cli --global
 ```
 
-### Method 3: GitHub Release Download
-
-Download `excel-skills-vX.X.X.zip` from [GitHub Releases](https://github.com/sbroenne/mcp-server-excel/releases/latest).
-
-The package contains both skills:
-- `skills/excel-cli/` - for coding agents (Copilot, Cursor, Windsurf)
-- `skills/excel-mcp/` - for conversational AI (Claude Desktop, VS Code Chat)
-
-Extract the skill(s) you need to your AI assistant's skills directory:
-- Copilot: `~/.copilot/skills/excel-cli/` or `~/.copilot/skills/excel-mcp/`
-- Claude Code: `.claude/skills/excel-cli/` or `.claude/skills/excel-mcp/`
-- Cursor: `.cursor/skills/excel-mcp/` or `.cursor/skills/excel-cli/`
-- Windsurf: `.windsurf/skills/excel-mcp/` or `.windsurf/skills/excel-cli/`
-
-### Method 4: Git Clone (Development)
-
-```bash
-# Clone and copy
-git clone https://github.com/sbroenne/mcp-server-excel.git
-cp -r mcp-server-excel/skills/excel-mcp ~/.copilot/skills/
-```
-
-## Directory Structure
-
-```
-skills/
-├── README.md                    # This file
-├── shared/                      # Shared behavioral guidance (source of truth)
-│   ├── behavioral-rules.md      # Core execution rules
-│   ├── anti-patterns.md         # Common mistakes to avoid
-│   ├── workflows.md             # Production workflow patterns
-│   ├── powerquery.md        # Power Query specifics
-│   ├── datamodel.md         # Data Model/DAX specifics
-│   ├── table.md             # Table operations
-│   ├── range.md             # Range operations
-│   ├── worksheet.md         # Worksheet operations
-│   ├── chart.md             # Chart operations
-│   ├── slicer.md            # Slicer operations
-│   └── conditionalformat.md # Conditional formatting
-├── excel-mcp/                   # MCP Server skill package
-│   ├── SKILL.md                 # Primary skill definition (MCP tools)
-│   ├── README.md                # MCP skill installation guide
-│   ├── VERSION                  # Version tracking
-│   └── references/              # MCP-specific + shared (copied during build)
-│       ├── claude-desktop.md    # Claude Desktop setup (MCP-specific)
-│       └── (shared files)       # Copied from shared/ by build script
-├── excel-cli/                   # CLI skill package
-│   ├── SKILL.md                 # CLI commands documentation
-│   ├── README.md                # CLI skill installation guide
-│   └── references/              # CLI-specific + shared (copied during build)
-│       ├── README.md            # Explains build process
-│       └── (shared files)       # Copied from shared/ by build script
-├── CLAUDE.md                    # Claude Code project instructions
-└── .cursorrules                 # Cursor-specific rules
-```
-
-**Note:** Shared behavioral guidance lives in `shared/` and is copied to each skill's `references/` folder during the build. Run `dotnet build -c Release` to generate SKILL.md and copy references.
-
-## Platform-Specific Files
-
-### For Claude Code Users
-
-Copy `CLAUDE.md` to your project root:
-```bash
-cp skills/CLAUDE.md /path/to/your/project/CLAUDE.md
-```
-
-Or reference from `.claude/skills/`:
-```bash
-mkdir -p .claude/skills
-cp -r skills/excel-mcp .claude/skills/
-```
-
-### For Cursor Users
-
-Copy `.cursorrules` to your project root:
-```bash
-cp skills/.cursorrules /path/to/your/project/.cursorrules
-```
-
-## Building the Skills Package
-
-Skill files are generated automatically during Release builds:
+## Building
 
 ```powershell
-# Build solution - generates SKILL.md and copies references
 dotnet build -c Release
-
-# Output (in skills/ folder):
-#   excel-mcp/SKILL.md        - Generated MCP skill documentation
-#   excel-mcp/references/     - Copied shared reference files
-#   excel-cli/SKILL.md        - Generated CLI skill documentation  
-#   excel-cli/references/     - Copied shared reference files
 ```
 
-For release artifacts (ZIP package), the GitHub Actions workflow handles packaging.
+Generates `SKILL.md` and copies `shared/` references into each skill's `references/` folder.
 
-## Version Compatibility
+## Structure
 
-| Skills Version | MCP Server Version | Minimum Excel |
-|----------------|-------------------|---------------|
-| 1.2.0+ | 1.2.0+ | Excel 2016+ |
-| 1.1.x | 1.1.x | Excel 2016+ |
-
-## Contributing
-
-See [CONTRIBUTING.md](../docs/CONTRIBUTING.md) for guidelines on improving the skills.
-
-## Related Resources
-
-- [Excel MCP Server Documentation](https://excelmcpserver.dev/)
-- [MCP Registry](https://mcp.run/registry)
-- [agentskills.io Specification](https://agentskills.io)
+```
+skills/
+├── shared/          # Shared behavioral guidance (source of truth)
+├── excel-mcp/       # MCP Server skill (SKILL.md + references/)
+├── excel-cli/       # CLI skill (SKILL.md + references/)
+├── templates/       # Scriban templates for SKILL.md generation
+├── CLAUDE.md        # Claude Code project instructions
+└── .cursorrules     # Cursor-specific rules
+```

skills/excel-cli/SKILL.md

@@ -25,6 +25,8 @@ documentation: https://excelmcpserver.dev/
 | 3. Write data | See below | If writing values |
 | 4. Save & close | `session close --save` | Always last |
 
+> **10+ commands?** Use `excelcli -q batch --input commands.json` — sends all commands in one process with automatic session management. See Rule 8.
+
 **Writing Data (Step 3):**
 - `--values` takes a JSON 2D array string: `--values '[["Header1","Header2"],[1,2]]'`
 - Write **one row at a time** for reliability: `--range-address A1:B1 --values '[["Name","Age"]]'`
@@ -33,6 +35,8 @@ documentation: https://excelmcpserver.dev/
 
 ## CRITICAL RULES (MUST FOLLOW)
 
+> **⚡ Building dashboards or bulk operations?** Skip to **Rule 8: Batch Mode** — it eliminates per-command process overhead and auto-manages session IDs.
+
 ### Rule 1: NEVER Ask Clarifying Questions
 
 Execute commands to discover the answer instead:
@@ -120,6 +124,35 @@ excelcli -q calculationmode calculate --session 1 --scope workbook
 excelcli -q calculationmode set-mode --session 1 --mode automatic
 ```
 
+### Rule 8: Use Batch Mode for Bulk Operations (10+ commands)
+
+When executing 10+ commands on the same file, use `excelcli batch` to send all commands in a single process launch. This avoids per-process startup overhead and terminal buffer saturation.
+
+```powershell
+# Create a JSON file with all commands
+@'
+[
+  {"command": "session.open", "args": {"filePath": "C:\\path\\file.xlsx"}},
+  {"command": "range.set-values", "args": {"sheetName": "Sheet1", "rangeAddress": "A1", "values": [["Hello"]]}},
+  {"command": "range.set-values", "args": {"sheetName": "Sheet1", "rangeAddress": "A2", "values": [["World"]]}},
+  {"command": "session.close", "args": {"save": true}}
+]
+'@ | Set-Content commands.json
+
+# Execute all commands at once
+excelcli -q batch --input commands.json
+```
+
+**Key features:**
+- **Session auto-capture**: `session.open`/`create` result sessionId auto-injected into subsequent commands — no need to parse and pass session IDs
+- **NDJSON output**: One JSON result per line: `{"index": 0, "command": "...", "success": true, "result": {...}}`
+- **`--stop-on-error`**: Exit on first failure (default: continue all)
+- **`--session <id>`**: Pre-set session ID for all commands (skip session.open)
+
+**Input formats:**
+- JSON array from file: `excelcli -q batch --input commands.json`
+- NDJSON from stdin: `Get-Content commands.ndjson | excelcli -q batch`
+
 ## CLI Command Reference
 
 > Auto-generated from `excelcli --help`. Use these exact parameter names.
@@ -299,7 +332,7 @@ Data Model relationships - link tables for cross-table DAX calculations. CRITICA
 
 
 
-### unknown
+### diag
 
 Diagnostic commands for testing CLI/MCP infrastructure without Excel. These commands validate parameter parsing, routing, JSON serialization, and error handling — no Excel COM session needed.
 
@@ -520,7 +553,7 @@ Hyperlink and cell protection operations for Excel ranges. Use range for values/
 
 
 
-### unknown
+### screenshot
 
 Capture Excel worksheet content as images for visual verification. Uses Excel's built-in rendering (CopyPicture) to capture ranges as PNG images. Captures formatting, conditional formatting, charts, and all visual elements. ACTIONS: - capture: Capture a specific range as an image - capture-sheet: Capture the entire used area of a worksheet RETURNS: Base64-encoded PNG image data with dimensions metadata. For MCP: returned as inline ImageContent. For CLI: saved to file.
 

skills/excel-cli/references/conditionalformat.md

@@ -84,17 +84,17 @@
 
 **CLI Usage**:
 
-```bash
+```powershell
 # Add rule: highlight values > 100 in yellow
-excelcli conditionalformat add-rule --session <id> --sheet "Data" --range "B2:B100" \
-  --rule-type "cell-value" --operator "greater" --formula1 "100" --interior-color "#FFFF00"
+excelcli conditionalformat add-rule --session <id> --sheet-name "Data" --range-address "B2:B100" `
+  --rule-type "cell-value" --operator-type "greater" --formula1 "100" --interior-color "#FFFF00"
 
 # Add expression rule: highlight entire row if column A is "Error"
-excelcli conditionalformat add-rule --session <id> --sheet "Data" --range "A2:E100" \
-  --rule-type "expression" --formula "=\$A2=\"Error\"" --interior-color "#FF0000" --font-color "#FFFFFF"
+excelcli conditionalformat add-rule --session <id> --sheet-name "Data" --range-address "A2:E100" `
+  --rule-type "expression" --formula1 "=`$A2=`"Error`"" --interior-color "#FF0000" --font-color "#FFFFFF"
 
 # Clear all rules from range
-excelcli conditionalformat clear-rules --session <id> --sheet "Data" --range "A1:E100"
+excelcli conditionalformat clear-rules --session <id> --sheet-name "Data" --range-address "A1:E100"
 ```
 
 **Common Mistakes**:

skills/excel-cli/references/slicer.md

@@ -39,12 +39,12 @@ Two distinct slicer types exist:
 
 The `--selected-items` parameter requires a JSON array. Use proper shell escaping:
 
-```bash
+```powershell
 # PowerShell: use single quotes around the JSON, double quotes inside
 --selected-items '["West","East"]'
 
-# Or escape inner quotes with backslash
---selected-items "[\"West\",\"East\"]"
+# Or escape inner quotes with backtick
+--selected-items "[`"West`",`"East`"]"
 
 # Clear filter (show all items)
 --selected-items '[]'
@@ -72,12 +72,12 @@ The `--selected-items` parameter requires a JSON array. Use proper shell escapin
 
 **CLI Usage**:
 
-```bash
+```powershell
 # Create PivotTable slicer
-excelcli slicer create-slicer --session <id> --pivottable-name "SalesPivot" --field-name "Region" --destination-sheet "Dashboard"
+excelcli slicer create-slicer --session <id> --pivot-table-name "SalesPivot" --field-name "Region" --destination-sheet "Dashboard"
 
 # Set slicer filter
-excelcli slicer set-slicer-selection --session <id> --slicer-name "RegionSlicer" --selected-items "[\"West\",\"East\"]"
+excelcli slicer set-slicer-selection --session <id> --slicer-name "RegionSlicer" --selected-items "[`"West`",`"East`"]"
 
 # Clear slicer filter (show all)
 excelcli slicer set-slicer-selection --session <id> --slicer-name "RegionSlicer" --selected-items "[]"

skills/excel-mcp/references/conditionalformat.md

@@ -84,17 +84,17 @@
 
 **CLI Usage**:
 
-```bash
+```powershell
 # Add rule: highlight values > 100 in yellow
-excelcli conditionalformat add-rule --session <id> --sheet "Data" --range "B2:B100" \
-  --rule-type "cell-value" --operator "greater" --formula1 "100" --interior-color "#FFFF00"
+excelcli conditionalformat add-rule --session <id> --sheet-name "Data" --range-address "B2:B100" `
+  --rule-type "cell-value" --operator-type "greater" --formula1 "100" --interior-color "#FFFF00"
 
 # Add expression rule: highlight entire row if column A is "Error"
-excelcli conditionalformat add-rule --session <id> --sheet "Data" --range "A2:E100" \
-  --rule-type "expression" --formula "=\$A2=\"Error\"" --interior-color "#FF0000" --font-color "#FFFFFF"
+excelcli conditionalformat add-rule --session <id> --sheet-name "Data" --range-address "A2:E100" `
+  --rule-type "expression" --formula1 "=`$A2=`"Error`"" --interior-color "#FF0000" --font-color "#FFFFFF"
 
 # Clear all rules from range
-excelcli conditionalformat clear-rules --session <id> --sheet "Data" --range "A1:E100"
+excelcli conditionalformat clear-rules --session <id> --sheet-name "Data" --range-address "A1:E100"
 ```
 
 **Common Mistakes**: