agent-xlsx
Interact with Excel files (.xlsx, .xlsm, .xlsb, .xls, .ods) using the agent-xlsx CLI for data extraction, analysis, writing, formatting, visual capture, VBA analysis, and sheet management. Use when the user asks to: (1) Read, analyse, or search data in spreadsheets, (2) Write values or formulas to cells, (3) Inspect formatting, formulas, charts, or metadata, (4) Take screenshots or visual captures of sheets, (5) Export sheets to CSV/JSON/Markdown, (6) Manage sheets (create, rename, delete, copy, hide), (7) Analyse or execute VBA macros, (8) List/export embedded objects (charts, shapes, pictures), (9) Check for formula errors, or (10) Any task involving Excel file interaction. Prefer over openpyxl/pandas scripts — faster, structured JSON optimised for AI.
What this skill does
# agent-xlsx
XLSX CLI for AI agents. JSON to stdout by default (raw text for `--format csv|markdown`). Polars+fastexcel for data reads (7-10x faster than openpyxl), openpyxl for metadata/writes, three rendering engines for visual capture (Aspose → Excel → LibreOffice), oletools for VBA.
## Running
If `agent-xlsx` is not already installed, use `uvx` for zero-install execution:
```bash
uvx agent-xlsx probe report.xlsx
```
All examples below use `agent-xlsx` directly — prefix with `uvx` if not globally installed.
> **This file is a quick-start summary.** Before constructing any command beyond the basic examples shown here, **you must read [commands.md](references/commands.md)** for the full flag reference (types, defaults, edge cases, output schemas). For screenshot/recalc engine setup, read [backends.md](references/backends.md). Guessing at flags leads to errors — the reference is the source of truth.
## Workflow: Progressive Disclosure
Start lean, opt into detail:
```
probe (fast) → screenshot (visual) → read (data) → inspect (metadata)
```
**Always start with `probe`:**
```bash
agent-xlsx probe <file> # Sheet names, dims, headers, column_map
agent-xlsx probe <file> --types # + column types, null counts
agent-xlsx probe <file> --brief # Condensed: headers + column_map + types + nulls (minimal tokens)
agent-xlsx probe <file> --full # + types, sample(3), stats, date_summary
agent-xlsx probe <file> -s "Sales" --full # Single-sheet deep-dive
agent-xlsx probe <file> --no-header # Non-tabular: P&L, dashboards (cols as A,B,C)
agent-xlsx probe <file> --types --no-header # + potential_headers auto-detection
```
Tabular probes return `column_map` — map headers to column letters for building ranges:
```json
{ "column_map": { "user_id": "A", "amount": "E" }, "last_col": "W" }
```
Non-tabular probes (`--no-header`) with `--types` return `potential_headers` — auto-detected header rows:
```json
{
"potential_headers": [
{ "row": 6, "values": { "I": "Dec", "J": "% sales", "L": "Nov" } }
]
}
```
## Essential Commands
### Data (Polars — fast)
```bash
# Read
agent-xlsx read <file> "A1:F50" # Range (positional arg)
agent-xlsx read <file> -s Sales "B2:G100" # Sheet + range
agent-xlsx read <file> --limit 500 --offset 100 # Pagination
agent-xlsx read <file> --sort amount --descending # Sorted
agent-xlsx read <file> --formulas # Formula strings (slower, openpyxl)
agent-xlsx read <file> "H54:AT54" -s 2022 --no-header # Non-tabular (compact by default)
agent-xlsx read <file> "H54:AT54,H149:AT149" -s 2022 # Multi-range (1 call)
agent-xlsx read <file> "H54:AT54" --all-sheets # Same range, every sheet (1 call)
agent-xlsx read <file> "H54:AT54,H149:AT149" --all-sheets # Multi-range × all sheets
agent-xlsx read <file> "A1:F50" --precision 2 # Round floats to 2 decimal places
# Search
agent-xlsx search <file> "revenue" # Substring match, all sheets
agent-xlsx search <file> "rev.*" --regex # Regex
agent-xlsx search <file> "stripe" --ignore-case # Case-insensitive
agent-xlsx search <file> "SUM(" --in-formulas # Inside formula strings
agent-xlsx search <file> "GDP" --columns "C" # Search only column C
agent-xlsx search <file> "GDP" --columns "Indicator Name" # By header name
agent-xlsx search <file> "^ARG$" --regex --limit 1 # First match only
agent-xlsx search <file> "code" --range "A100:D200" # Scoped to row range
agent-xlsx search <file> "GDP" -c C --range "Series!A1:Z1000" -l 5 # All combined
# Read — column letter → header name resolution
agent-xlsx read <file> "A500:D500" --headers # Resolve A,B,C,D to row-1 names
# Export
agent-xlsx export <file> --format csv # CSV to stdout (compact by default)
agent-xlsx export <file> --format markdown # Markdown table
agent-xlsx export <file> --format csv -o out.csv -s Sales
agent-xlsx export <file> --format markdown --no-header -s 2022 # Non-tabular export
```
### Metadata (openpyxl)
```bash
# Overview — structural summary
agent-xlsx overview <file>
agent-xlsx overview <file> --include-formulas --include-formatting
# Inspect — comprehensive single-pass metadata
agent-xlsx inspect <file> -s Sales # Everything: formulas, merges, tables, charts, comments, cond. formatting, validation, hyperlinks, freeze panes
agent-xlsx inspect <file> -s Sales --range A1:C10 # Scoped
agent-xlsx inspect <file> --names # Named ranges
agent-xlsx inspect <file> --charts # Chart metadata
agent-xlsx inspect <file> --vba # VBA modules
agent-xlsx inspect <file> --format "A1" -s Sales # Cell formatting detail
agent-xlsx inspect <file> --comments # Cell comments
# Format — read/write cell formatting
agent-xlsx format <file> "A1" --read -s Sales # Read formatting
agent-xlsx format <file> "A1:D1" --font '{"bold": true, "size": 14}'
agent-xlsx format <file> "B2:B100" --number-format "#,##0.00"
agent-xlsx format <file> "A1:D10" --copy-from "G1" # Copy all formatting
agent-xlsx format <file> "A1:D1" --horizontal center --bold # Alignment shorthands
agent-xlsx format <file> "A1:D1" --batch '[{"range": "A1:L1", "bold": true, "fill_color": "4472C4"}, {"range": "A2:L50", "number_format": "#,##0.00"}]' # Batch: different styles per range, one save
```
### Write (openpyxl)
```bash
agent-xlsx write <file> "A1" "Hello" # Single value
agent-xlsx write <file> "A1" "=SUM(B1:B100)" --formula # Formula
agent-xlsx write <file> "A1:C3" --json '[[1,2,3],[4,5,6],[7,8,9]]' # 2D array
agent-xlsx write <file> "A1" --from-csv data.csv # CSV import
agent-xlsx write <file> "A1" "Hello" -o new.xlsx -s Sales # Copy to new file
agent-xlsx write new.xlsx "A1" --json '[[1,2],[3,4]]' # Auto-creates new.xlsx
agent-xlsx write <file> "A1:B2" --json '[["=SUM(C1:C10)","=AVERAGE(D1:D10)"]]' --formula # Batch formulas
# Sheet management
agent-xlsx sheet <file> --list
agent-xlsx sheet <file> --create "New Sheet"
agent-xlsx sheet <file> --rename "Old" --new-name "New"
agent-xlsx sheet <file> --delete "Temp"
agent-xlsx sheet <file> --copy "Template" --new-name "Q1"
agent-xlsx sheet <file> --hide "Internal"
```
### Visual & Analysis (3 engines: Aspose → Excel → LibreOffice)
```bash
# Screenshot — HD PNG capture (auto-fits columns)
agent-xlsx screenshot <file> # All sheets
agent-xlsx screenshot <file> -s Sales # Specific sheet
agent-xlsx screenshot <file> -s "Sales,Summary" # Multiple sheets
agent-xlsx screenshot <file> "Sales!A1:F20" # Range capture
agent-xlsx screenshot <file> -o ./shots/ # Output directory
agent-xlsx screenshot <file> --engine aspose # Force engine
agent-xlsx screenshot <file> --dpi 300 # DPI (Aspose/LibreOffice)
# Objects — embedded charts, shapes, pictures
agent-xlsx objects <file> # List all
agent-xlsx objects <file> --export "Chart 1" # Export chart as PNG
# Recalc — formula error checking
agent-xlsx recalc <file> --check-only # Scan for #REF!, #DIV/0! (no engine needed)
agent-xlsx recalc <file> # Full recalculation (needs engine)
```
### VBA (oletools + xlwings)
```bash
agent-xlsx vba <file> --list # List modules + security summary
agent-xlsx vba <file> --read ModuleName # Read module code
agent-xlsx vba <file> --read-all # All module code
agent-xlsx vba <file> --security # Full security analysis (risk level, IOCs)
agent-xlsx vba <file> --run "Module1.MyMacro" # Execute (requires Excel)
agent-xlsx vba <file> --run "MyMacro" --args '[1]' # With arguments
```
### Config
```bash
agent-Related in AI Agents
skill-development
IncludedComprehensive meta-skill for creating, managing, validating, auditing, and distributing Claude Code skills and slash commands (unified in v2.1.3+). Provides skill templates, creation workflows, validation patterns, audit checklists, naming conventions, YAML frontmatter guidance, progressive disclosure examples, and best practices lookup. Use when creating new skills, validating existing skills, auditing skill quality, understanding skill architecture, needing skill templates, learning about YAML frontmatter requirements, progressive disclosure patterns, tool restrictions (allowed-tools), skill composition, skill naming conventions, troubleshooting skill activation issues, creating custom slash commands, configuring command frontmatter, using command arguments ($ARGUMENTS, $1, $2), bash execution in commands, file references in commands, command namespacing, plugin commands, MCP slash commands, Skill tool configuration, or deciding between skills vs slash commands. Delegates to docs-management skill for official documentation.
reprompter
IncludedTransform messy prompts into well-structured, effective prompts — single or multi-agent. Use when: "reprompt", "reprompt this", "clean up this prompt", "structure my prompt", rough text needing XML tags and best practices, "reprompter teams", "repromptception", "run with quality", "smart run", "smart agents", multi-agent tasks, audits, parallel work, anything going to agent teams. Don't use when: simple Q&A, pure chat, immediate execution-only tasks. See "Don't Use When" section for details. Outputs: Structured XML/Markdown prompt, quality score (before/after), optional team brief + per-agent sub-prompts, agent team output files. Success criteria: Single mode quality score ≥ 7/10; Repromptception per-agent prompt quality score 8+/10; all required sections present, actionable and specific.
adaptive-compaction
IncludedAdaptive add-on policy and recovery layer that decides WHEN to compact, prune, snapshot, or fork -- replacing fixed-percent auto-compaction across Claude Code, Codex, and MCP-capable hosts. Trigger on auto-compact timing or damage: "when should I compact", "is it safe to compact now or start a fresh session", "auto-compact fires too early/mid-task", "switching to an unrelated task but the window still has space", "context rot", "answers get worse the longer the session runs", "the agent forgot the plan or my decisions after it summarized", "add a layer on top that manages context without changing the agent", raising autoCompactWindow to give the policy room, or installing/tuning a cross-tool compaction policy or PreCompact hook -- even when "compaction" is never said but the problem is context-window pressure or post-summarization memory loss. Do NOT use to summarize a conversation, build RAG, write a summarization prompt (decides WHEN not HOW), or answer max-context-length trivia.
agent-skill-creator
IncludedCreate cross-platform agent skills from workflow descriptions. Activates when users ask to create an agent, automate a repetitive workflow, create a custom skill, or need advanced agent creation. Triggers on phrases like create agent for, automate workflow, create skill for, every day I have to, daily I need to, turn process into agent, need to automate, create a cross-platform skill, validate this skill, export this skill, migrate this skill. Supports single skills, multi-agent suites, transcript processing, template-based creation, interactive configuration, cross-platform export, and spec validation.
llm-wiki
IncludedUse when building or maintaining a persistent personal knowledge base (second brain) in Obsidian where an LLM incrementally ingests sources, updates entity/concept pages, maintains cross-references, and keeps a synthesis current. Triggers include "second brain", "Obsidian wiki", "personal knowledge management", "ingest this paper/article/book", "build a research wiki", "compound knowledge", "Memex", or whenever the user wants knowledge to accumulate across sessions instead of being re-derived by RAG on every query.
skill-master
IncludedAgent Skills authoring, evaluation, and optimization. Create, edit, validate, benchmark, and improve skills following the agentskills.io specification. Use when designing SKILL.md files, structuring skill folders (references, scripts, assets), ingesting external documentation into skills, running trigger evals, benchmarking skill quality, optimizing descriptions, or performing blind A/B comparisons. Keywords: agentskills.io, SKILL.md, skill authoring, eval, benchmark, trigger optimization.