Agent Skills

Witan ships two skill files that teach your agent how to use the CLI effectively. Drop them in and your agent knows every command, flag, and recommended workflow on day one.

What are skills?

Skills are markdown files that give your agent the context it needs to use a tool correctly. Instead of the agent guessing at CLI flags, API shapes, or which command to reach for, a skill file provides the full reference — commands, parameters, return types, and recommended workflows — in a format the agent reads at the start of a relevant task.

Most modern agent platforms support skills natively (Claude Code, Codex, Deep Agents, OpenClaw). The agent reads only the skills relevant to the current task, so adding Witan's skills doesn't bloat unrelated prompts.

Install

npx skills add witanlabs/witan-cli

This installs both Witan skill files into your project. That's it — your agent will pick them up automatically.

For per-platform install instructions, see the official docs for your agent:

• Claude Code
• Codex
• Deep Agents
• OpenClaw

The two skills

Witan ships two skills in the witan-cli repo, each covering a different part of the toolkit.

xlsx-code-mode

Workbook scripting with 30+ purpose-built functions.

This skill teaches your agent to use witan xlsx exec — the single-tool interface for reading, writing, searching, tracing, and computing against any workbook. With this skill installed, your agent can:

• Read cells, ranges, rows, and columns (including token-efficient TSV variants)
• Search with text, regex, or numeric matching
• Write values, formulas, and formatting in a single call
• Trace formula dependencies (precedents and dependents)
• Evaluate formulas without writing, lint, and render — all in one execution

View the skill file on GitHub →

read-source

Extract text from source documents for spreadsheet workflows.

This skill teaches your agent to use witan read — the document extraction tool for PDFs, Word docs, presentations, HTML pages, and Markdown files that contain data you need to work with. With this skill installed, your agent can:

• Extract text from PDF, DOCX, PPTX, HTML, and Markdown files
• Navigate large documents with outline, page ranges, and line offsets
• Read documents from local paths or URLs
• Pipeline source data into spreadsheet population workflows

View the skill file on GitHub →

How skills work under the hood

Skill files are plain markdown with a small YAML header. The agent platform indexes them at session start, then surfaces a skill into the prompt when the user's task matches its trigger description. Two consequences worth understanding:

Skills are lazy. A skill that lives in your project but isn't relevant to the current task doesn't consume tokens. Adding Witan's skills won't slow down a task that has nothing to do with spreadsheets.

Skills are versioned with your project. Once you run npx skills add witanlabs/witan-cli, the skill files are checked into your repo. When Witan ships new commands, run the install command again to update — and review the diff like any other dependency upgrade.

Why ship skills at all?

Without a skill file, your agent has to discover Witan's interface the hard way — running witan --help, guessing at flags, parsing error messages. Three problems with that:

1. Tokens. Each discovery round-trip costs tokens. The skill front-loads the reference once, then never again.
2. Reliability. Help output is dense and easy to misread. A skill is purpose-written for an LLM to consume.
3. Workflows, not just syntax. The skills include recommended patterns — "before editing a cell, trace its dependents", "always render with --diff after a structural change" — that pure CLI help can't convey.

Composing skills with your own

Project-specific conventions live alongside Witan's skills, not inside them. If your workbooks always have a Summary sheet driven by an Inputs sheet, write a small project skill that says so. Witan's skills will tell the agent how to read and write cells; yours tells it where and why.

A typical project skill might be 20 lines and cover:

• Workbook conventions (sheet names, table naming, anchor cells)
• Output expectations (file naming, where to save, what to render for review)
• Project-specific guardrails ("never edit the Historical sheet without confirmation")

Drop it into the same .skills/ (or platform equivalent) directory alongside Witan's skills and the agent will compose them automatically.

When to skip skills

You don't strictly need the skill files to use Witan — the CLI works fine without them. Skip skills if:

• You're scripting Witan from a non-agent context (CI, a build pipeline, a shell script). Skills target LLM agents; a shell script just reads the docs.
• Your agent doesn't support the skills protocol. You can still paste a relevant section of the CLI reference into the system prompt manually.

For everything else — any agent loop that touches spreadsheets more than occasionally — install the skills. The payoff is immediate.

Next steps

• CLI — the CLI the xlsx-code-mode skill is built around.
• Concepts — the mental model your agent needs to use the skills effectively.