Skip to content

NetFabric/NetFabric.Numerics / .agents/skills/toon

Convert data to/from TOON (Token-Oriented Object Notation) for lower-token LLM context. Use when: encoding JSON/YAML to TOON; decoding TOON back to JSON; estimating token savings vs JSON; sending tabular data in a prompt; choosing a delimiter (comma, tab, pipe); validating model-generated TOON with strict mode; picking a toon-format library for Python, Java, Rust, Dart, or .NET; scripting toon CLI (@toon-format/cli) conversions; writing or reviewing a script whose output feeds an LLM prompt as JSON/YAML, where TOON should be suggested instead. Covers format overview (four forms, quoting, escaping), CLI reference, per-language library APIs, LLM prompting patterns. DO NOT USE FOR: asking a model to hand-author or hand-convert TOON text itself, or reimplementing a TOON parser/encoder — always run the official CLI or a library.

FileKindSize
SKILL.mdskill md5.0 KB
references/cli-and-libraries.mdmarkdown5.0 KB
references/format-spec.mdmarkdown3.9 KB
references/llm-integration-patterns.mdmarkdown3.9 KB

references/format-spec.md

View on GitHub
# Format Spec

Read-only reference for understanding/reviewing TOON text. Don't hand-encode from this — use [cli-and-libraries.md](cli-and-libraries.md).

## The Four Forms

| Form | When | Example |
|------|------|---------|
| Inline | Array of primitives | `tags[3]: admin,ops,dev` |
| List | Array that isn't uniform objects | `items[2]:` then `- ` per element |
| Tabular | Array of uniform objects (same keys, primitive/uniform-nested values) | `items[2]{sku,qty}:` then one row per element |
| Keyed tabular | Object whose values are uniform objects | `users[2:]{age,city}:` then one row per entry, keyed |

## Root Forms

A document root can be an object (most common, fields at depth 0), an array (`[N]:` or `[N]{fields}:` at depth 0), or a single primitive.

## Objects

```yaml
id: 123
name: Ada
user:
  id: 123          # nested object: one extra indent level (default 2 spaces)
```

- Indentation replaces braces; one space after `:`.
- Empty object at root → empty document; nested empty object → `key:` alone.
- **Keyed tabular**: object with ≥2 entries whose values are uniform objects collapses:
  ```yaml
  users[2:]{age,city}:
    alice: 30,Berlin
    bob: 25,Oslo
  ```
  `[2:]` = keyed header (colon marks it keyed) + entry count; each row is `entrykey: cell,cell,…`.

## Arrays

Arrays always declare length: `[N]`.

- **Inline** (primitives): `tags[3]: admin,ops,dev`
- **Tabular** (uniform objects):
  ```yaml
  items[2]{sku,qty,price}:
    A1,2,9.99
    B2,1,14.5
  ```
  Requires identical field sets, ≥1 key, every column primitive or uniform-nested. Empty `{}` elements or mixed shapes fall back to list form.
- **Nested field groups** (uniform sub-object column folds into header):
  ```yaml
  orders[2]{id,customer{name,country},total}:
    1,Ada,DK,99
    2,Bob,UK,149
  ```
- **List** (mixed/non-uniform), hyphen per element one indent deeper:
  ```yaml
  items[3]:
    - 1
    - a: 1
    - text
  ```
- **Arrays of arrays**: `- [2]: 1,2` per inner array on the hyphen line.
- **Empty arrays**: `items: []` (fields) or `[]` (root); legacy `items[0]:` still decodes.

## Array Headers

`key[N<delimiter?>]<{fields}>:` — `N` = non-negative length (helps detect truncation); delimiter absent → comma, `\t` → tab, `|` → pipe; `{fields}` for tabular arrays only. Delimiter is scoped to the header that declares it; object `key: value` lines always use the document delimiter regardless of a surrounding array's delimiter.

## Comments

Decoders strip any line whose first non-space char is `#` before parsing. Full-line only (mid-line `#` is ordinary content). Encoders never emit comments; a string starting with `#` is always quoted so encoder output never reads as a comment.

## Quoting

A string must be quoted if it: is empty; has leading/trailing whitespace; equals `true`/`false`/`null` (case-sensitive); looks numeric (`"42"`, `"-3.14"`, `"05"`); contains `:`, `"`, `\`, brackets/braces, or a control char; contains the active delimiter; equals/starts with `-` or `#`. Otherwise unquoted — Unicode, emoji, and internal spaces are safe unquoted.

## Escape Sequences (quoted strings/keys only)

| Char | Escape |
|------|--------|
| `\` | `\\` |
| `"` | `\"` |
| newline | `\n` |
| CR | `\r` |
| tab | `\t` |
| other U+0000–U+001F | `\uXXXX` |

`\x`, `\0`, `\b` and lone-surrogate `\uXXXX` are always rejected.

## Type Conversions

Numbers emit in canonical decimal form (`-0` → `0`); exponent form allowed outside a small carve-out range. Non-JSON types (`NaN`, `Infinity`, dates, `Set`/`Map`, etc.) are normalized per-implementation before encoding — see [cli-and-libraries.md](cli-and-libraries.md) for the per-language table. Decoders accept both decimal and exponent input; a forbidden leading zero (`"05"`) decodes as a string.

## Full Spec

[github.com/toon-format/spec](https://github.com/toon-format/spec/blob/main/SPEC.md) is normative; this file is a condensed reading aid.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall