[0.1 draft] [guide 15 · spec 15 pages]

For agents

A Text Tables file answers most questions about itself before a single row is read: how many rows, what a row is, which column is money and in what currency, what the totals are, which values are known to be wrong. An agent that reads the system lines first works faster, uses less context and stops summing ids.

The txtab skill

A ready-made skill teaches an agent to read and write .txtab and .txtab.zip. It works with Claude and any agent that loads skills in the SKILL.md format.

shell

# from the repository
npx skills add boligolov/txtab

# or by hand
mkdir -p ~/.claude/skills          # or your agent's skills folder
curl -LO https://texttables.dev/skills/txtab.zip
unzip txtab.zip -d ~/.claude/skills/

download txtab.zip

FileWhat it covers
SKILL.mdWhen to use the skill and the workflow: find the prefix, read the system lines, load rows by count.
references/format.mdThe vocabulary in short: first line, keywords, attributes, error levels.
references/writing.mdWriting and converting: choosing a prefix, row counts, aggregates, notes.
references/archives.md.txtab.zip: the main file, column storage, the ZIP comment.
scripts/read_txtab.pyA minimal reader with no dependencies beyond the Python standard library.

Without the skill

Point the agent at the system lines yourself. Two shell lines find the prefix and list everything that describes the data, with line numbers:

shell

P=$(head -1 orders.txtab | sed 's/^\xEF\xBB\xBF//' | cut -d' ' -f1)
awk -v p="$P " 'index($0, p) == 1 || $0 == substr(p, 1, length(p) - 1) { print NR": "$0 }' orders.txtab

Then tell it the rules that matter most:

  • Each # table line declares rows=: read exactly that many records after the header.
  • agg-* lines describe all declared rows; trust them over a sum of a preview.
  • role=id columns are counted and joined, never summed; agg=avg measures are not summed either.
  • unit= with a currency code is money; never add up different currencies.

Writing for agents

When you export data an agent will read, the lines that help most are meta-grain (what one row is), type= and unit= on every column, role= and agg= on measures, and the aggregates. See metadata, columns and aggregates in the guide.

A list of every page in plain text for crawlers and agents: /llms.txt.