---

name: toon description: Use the TOON CLI whenever a task inspects JSON-compatible structured data such as JSON files, API responses, database rows, search results, and structured logs. This skill applies before that data enters agent context.

TOON

Purpose

TOON is a temporary, lossless representation of the JSON data model for reducing the tokens required to read structured data.

JSON remains the canonical file and interchange format. TOON is used only as a reading surface for inspection.

Input Normalization

TOON accepts one JSON value rather than newline-delimited JSON (NDJSON/JSONL), so NDJSON is slurped into an array before encoding:

jq -s '.' events.ndjson | toon

Inputs are reduced to the required rows and fields before encoding when the task needs only part of the data:

jq '{items: [.items[] | {id, name, status}]}' response.json | toon

Reading Structured Data

The workflow reads the CLI's TOON output instead of first reading the source JSON into agent context.

toon large-response.json
curl -fsSL https://api.example.com/items | toon

Converted data that must persist during the task is written under a system temporary directory owned by the current command sequence:

scratch="$(mktemp -d -t toon.XXXXXX)"
cleanup() {
  status=$?
  rm -rf "$scratch"
  exit "$status"
}
trap cleanup EXIT
toon large-response.json --stats -o "$scratch/large-response.toon"

The complete source JSON and its TOON representation are not both read unless comparison is required by the task.

Validation

The toon command uses strict decoding by default. Strict decoding validates array counts, indentation, headers, and escaping, so malformed TOON input from upstream tools is surfaced immediately.

--no-strict is not used to accept malformed TOON. Missing CLI availability or conversion failures are surfaced instead of silently falling back.

Required Syntax

Objects use key: value, and nesting uses two-space indentation:

user:
  id: 1
  name: Alice
  active: true

Primitive arrays declare their element count:

tags[3]: rust,cli,macos

Uniform arrays of objects declare the row count and field order once:

users[2]{id,name,active}:
  1,Alice,true
  2,Bob,false

[N] is the array element count. {fields} defines the field order for every following row.

Quote strings that could be interpreted as another type or contain structural characters:

version: "123"
enabled: "true"
note: "hello, world"

These rules matter when reading existing TOON output or interpreting examples. Do not introduce a TOON authoring step when the task can stay in JSON.