toon-formatter

仓库: raintree-technology/claude-starter
安装量: 95
排名: #8573

安装

npx skills add https://github.com/raintree-technology/claude-starter --skill toon-formatter

TOON (Token-Oriented Object Notation) saves 30-60% tokens on structured data by eliminating repetitive keys in uniform arrays.

When to Use

Automatically apply TOON when:

  • Arrays with 5+ similar objects

  • API responses with repeated structure

  • Database query results

  • Log entries, events, transactions

  • Metrics, analytics, benchmarks

  • Any tabular data

Keep as JSON when:

  • Small arrays (<5 items)

  • Deeply nested non-uniform data

  • Single objects

  • Narrative text or instructions

Format Specification

Tabular Format (Most Common)

For arrays of uniform objects:

[count]{field1,field2,field3}:
  value1,value2,value3
  value1,value2,value3

Example - JSON (120 tokens):

[
  {"id": 1, "name": "Alice", "role": "admin", "active": true},
  {"id": 2, "name": "Bob", "role": "user", "active": true},
  {"id": 3, "name": "Carol", "role": "user", "active": false}
]

TOON (70 tokens, 42% savings):

[3]{id,name,role,active}:
  1,Alice,admin,true
  2,Bob,user,true
  3,Carol,user,false

Inline Format

For primitive arrays (10 or fewer items):

fieldName[count]: value1,value2,value3

Example:

tags[4]: javascript,react,nodejs,api
ids[3]: 101,102,103

Expanded Format

For complex nested values (one per line):

items[3]|:
  | {"complex": "object1"}
  | {"complex": "object2"}
  | {"complex": "object3"}

Delimiters

Choose based on data content:

| Comma | [N] | Default, no commas in values

| Tab | [N\t] | Values contain commas

| Pipe | [N|] | Values contain commas and tabs

Tab-delimited example:

[2\t]{name,description}:
  Product A A great product, really
  Product B Another one, even better

Key Folding (Nested Objects)

Flatten nested structures:

server.host: localhost
server.port: 8080
server.ssl.enabled: true
database.url: postgres://localhost/db

Special Values

| null | ~

| empty string | ""

| true | true

| false | false

Conversion Patterns

API Response

Before (JSON):

{
  "users": [
    {"id": 1, "email": "a@x.com", "plan": "pro"},
    {"id": 2, "email": "b@x.com", "plan": "free"},
    {"id": 3, "email": "c@x.com", "plan": "pro"}
  ],
  "total": 3
}

After (TOON):

users[3]{id,email,plan}:
  1,a@x.com,pro
  2,b@x.com,free
  3,c@x.com,pro
total: 3

Log Entries

Before (JSON):

[
  {"ts": "2024-01-15T10:00:00Z", "level": "INFO", "msg": "Server started"},
  {"ts": "2024-01-15T10:00:01Z", "level": "DEBUG", "msg": "Connection pool ready"},
  {"ts": "2024-01-15T10:00:02Z", "level": "INFO", "msg": "Listening on :8080"}
]

After (TOON):

[3]{ts,level,msg}:
  2024-01-15T10:00:00Z,INFO,Server started
  2024-01-15T10:00:01Z,DEBUG,Connection pool ready
  2024-01-15T10:00:02Z,INFO,Listening on :8080

Database Results

Before (JSON):

[
  {"product_id": 101, "name": "Widget", "price": 29.99, "stock": 150},
  {"product_id": 102, "name": "Gadget", "price": 49.99, "stock": 75},
  {"product_id": 103, "name": "Gizmo", "price": 19.99, "stock": 200}
]

After (TOON):

[3]{product_id,name,price,stock}:
  101,Widget,29.99,150
  102,Gadget,49.99,75
  103,Gizmo,19.99,200

Mixed Content

Combine formats as needed:

config.name: MyApp
config.version: 1.0.0
config.features[3]: auth,logging,metrics

endpoints[4]{method,path,auth}:
  GET,/api/users,required
  POST,/api/users,required
  GET,/api/health,none
  DELETE,/api/users/:id,admin

tags[5]: api,rest,json,http,web

Decision Flowchart

Is it an array?
├─ No → Use standard JSON/key-value
└─ Yes → How many items?
    ├─ <5 → Keep as JSON (overhead not worth it)
    └─ ≥5 → Are objects uniform (≥60% same keys)?
        ├─ No → Use expanded format
        └─ Yes → Are values primitives?
            ├─ Yes, ≤10 items → Inline format
            └─ Otherwise → Tabular format

Token Savings Reference

| User lists | 40-50%

| Log entries | 35-45%

| API responses | 30-50%

| Database rows | 45-55%

| Event streams | 40-60%

| Config arrays | 25-35%

Binary Encoder

A compiled Zig encoder (20x faster than JS) is available:

# Encode JSON to TOON
.claude/utils/toon/bin/toon encode data.json

# Decode TOON to JSON  
.claude/utils/toon/bin/toon decode data.toon

# Check if TOON recommended
.claude/utils/toon/bin/toon check data.json

# Analyze token savings
.claude/utils/toon/bin/toon analyze data.json

Commands

| /toon-encode <file> | Convert JSON to TOON

| /toon-decode <file> | Convert TOON to JSON

| /toon-validate <file> | Validate TOON syntax

| /analyze-tokens <file> | Compare JSON vs TOON size

| /convert-to-toon <file> | Full conversion workflow

Best Practices

DO:

  • Use TOON for data payloads in RAG pipelines

  • Apply to tool call responses with arrays

  • Convert benchmark results and metrics

  • Use tab delimiter when values have commas

DON'T:

  • Convert small arrays (<5 items)

  • Force non-uniform data into tabular format

  • Use for deeply nested structures

  • Apply to human-readable documentation

Resources

← 返回排行榜