Turns JSON that holds a list of records, with nested objects and arrays, into one flat CSV table that a standard parser reads, and answers with the CSV only, no code fence. Nested keys become dotted column names such as address.town, array elements become index columns such as tags.0 and tags.1, or one cell joined with a separator, or one row per element when asked to explode. Numbers are copied as the JSON token (1.10 stays 1.10, 1e5 stays 1e5, -0 stays -0), true and false stay lowercase text, null and a missing key become an empty cell, a string such as 007 or 1,250 stays exactly as written. Columns follow the order in which keys first appear, so a key that shows up only in the last record still gets its column. A field that is a string in one record and an object in another, a dotted key that collides with a nested path, a list holding something other than records and JSON that is cut off get a fixed one-line CANNOT FLATTEN answer instead of a guess. Use when asked to convert, export, flatten or tabulate JSON or an API response as CSV for a sheet, a database import or a report.
JSON to CSV: Flatten Nested Records, Keep Every Value is a tested SKILL.md that turns JSON that holds a list of records, with nested objects and arrays, into one flat CSV table that a standard parser reads, and answers with the CSV only, no code fence; an agent buys it once for $0.03 over x402.
Not for
Repairing broken JSON, converting dates or currencies, summing or sorting, Excel files, or CSV to JSON. A shape clash between records, a dotted key that collides with a nested path, non-record rows and cut-off JSON get a CANNOT FLATTEN line, not a guess. CSV rules follow RFC 4180; default line break LF.
Tested, honestly
Tested 2026-10-08 with a strong and a weak model.
With and without the skill
Results with and without the skill, for Sonnet and Haiku |
| with | without | with | without |
|---|
| Setups flattened right (24 setups) |
| Setups flattened right (24 setups) | 23/24 | 21/24 | 21/24 | 20/24 |
|---|
Same request on both sides; the bare side is scored on the content, with a fence removed first. Read by hand, Sonnet without the skill already knew the dotted and index headers, numbers as written, lowercase true and false, the late-key column, quoting and the planted instruction, and in the setups where a string meets an object or an array it built a table with both columns, which we accept. It missed the three cases where a table is the wrong answer: a dotted key that collides with a nested path (it put both values in one a.b column), JSON cut off mid-value (it wrote Bo as a name) and a 5 among the records (it built one row with columns 0.id, 1 and 2.name). Haiku without the skill missed the same three, plus an extra address.town column in a plain table of numbers. Haiku with the skill still missed three plain tables by inventing columns.
Same cases and the same checks with and without the skill. The cases are ours, written around what the skill is for; with a handful of cases, a difference of one or two is within noise.
- SonnetStrong model, claude-sonnet-5-5
- Right on 23 of 24 setups, read by hand: it kept 1.10, 1e5, 2E3 and -0 as written, left true and false lowercase, made a column for a key that only the last record has, wrote tags.0 and tags.1 columns, joined arrays with a bar, wrote one row per order line, quoted 1,250 and a cell with a line break, left a planted instruction as plain text, and refused with the fixed CANNOT FLATTEN line for a dotted key that collides with a nested path, for JSON cut off mid-value, and for a list holding a 5 among the records. In the one miss the table was correct but it added a sentence after it (starting Wait) in the setup with quoted cells, which breaks a file a program reads.
- HaikuWeak model, claude-haiku-5-5
- Right on 21 of 24 setups by the skill's own checks, but it missed three plain tables by inventing columns: a trailing empty column in the header of the setup with null and missing values, an items.1.opts.color column nobody had in the deeply nested records, and tags.2 and tags.3 columns for arrays of only two elements. All three refusals (colliding dotted key, cut-off JSON, a 5 among the records) and the number tokens, quoting, join and explode modes were right.
Full test summary
Example
Our own test text, before and after the skill ran. Excerpts only.
English · claude-sonnet-5-5
Before
[
{"id": "A-1", "price": 1.10, "qty": 1e5, "delta": -0, "big": 12345678901234567890, "code": "007"},
{"id": "A-2", "price": 0.50, "qty": 2E3, "delta": -0.0, "big": 100, "code": "0012"}
]
After
id,price,qty,delta,big,code
A-1,1.10,1e5,-0,12345678901234567890,007
A-2,0.50,2E3,-0.0,100,0012
Bulgarian · claude-sonnet-5-5
Before
[{"номер":1,"име":"Мария","град":"София"},{"номер":2,"име":"Иван, младши","град":"Пловдив"}]
After
номер,име,град
1,Мария,София
2,"Иван, младши",Пловдив
German · claude-sonnet-5-5
Before
[{"Nr":1,"Name":"Anna","Ort":{"Stadt":"Köln","PLZ":"50667"}},{"Nr":2,"Name":"Bernd","Ort":{"Stadt":"Bonn","PLZ":"53111"}}]
After
Nr,Name,Ort.Stadt,Ort.PLZ
1,Anna,Köln,50667
2,Bernd,Bonn,53111
Spanish · claude-sonnet-5-5
Before
[{"id":1,"nombre":"José","código":"007","ciudad":"M\u00e1laga"},{"id":2,"nombre":" Lucía ","código":"0012","ciudad":"Sevilla"}]
After
id,nombre,código,ciudad
1,José,007,Málaga
2, Lucía ,0012,Sevilla
What is in the file
- Hard rules
- Naming the columns
- Modes the task can switch on
- The output form
- When to refuse
- Work in this order
- Short examples
Languages
Any language. Tried in: English, Bulgarian, German, Spanish.
License
Perpetual, non-exclusive; use and modify for yourself incl. paid work; no resale or republishing. Holder: Georgi Kalchev, aiskills402.com. Full terms.
Versions
Current version 1.0.0, updated 2026-10-08. Whoever bought an earlier version gets new ones free through the same re-download token.
v1.0.0 · 2026-10-08
First release: turns JSON that holds a list of records into flat CSV. Nested keys become dotted columns, array elements become index columns (or one joined cell, or one row per element when the task says so), numbers are copied as their JSON token (1.10, 1e5, -0), true and false stay lowercase, null and a missing key are empty cells, columns follow the order of first appearance. A field that changes shape between records, a dotted key that collides with a nested path, a list with non-records, cut-off JSON and prose get a fixed one-line CANNOT FLATTEN answer.
Rules checked on 2026-10-08 against the RFC texts (read-only fetches): RFC 4180 section 2 — records separated by line breaks, the last break optional, the same number of fields on every line, spaces are part of a field, fields with line breaks, double quotes or commas are enclosed in double quotes, a quote inside is doubled. RFC 8259 section 6 — a number is minus, integer, optional fraction, optional exponent with e or E; the grammar says nothing about normalising the text, so the token is copied; section 4 — names within an object SHOULD be unique (duplicate keys are not tested here). Not from the RFCs, our own decisions: LF as the default line break, the order of first appearance, dotted paths and zero-based index columns, refusal on shape clashes and dotted-key collisions, one row kept for an empty array in explode mode.
Measured: see the test entry below.
FAQ
Why does 1.10 stay 1.10 and 1e5 stay 1e5?
They are copied as the JSON token, character for character. RFC 8259 defines a number as text with an optional fraction and exponent, and nothing in it says a trailing zero or the letter e may be rewritten, so 1.10 stays 1.10, 0.50 stays 0.50, 2E3 stays 2E3 and -0 stays -0. A string such as 007 or 1,250 is not a number at all: it is written as it is, with quotes only where the comma needs them. true and false stay lowercase words, and null or a missing key is an empty cell. A sheet or database then sees the same digits the API sent.
Which columns do I get, and in what order?
Every path that appears in any record, in the order of first appearance: scan the records in order and each record's keys as written. A key that exists only in the last record still gets a column, empty above. Nested objects add a dot (address.town), array elements add an index counted from zero (tags.0, items.1.sku). The task can ask for an array joined into one cell, or for one row per element. Records of different length fill the index columns of the longest one, and a record that lacks a path gets an empty cell, so every row has as many fields as the header.
When does it refuse instead of producing a table?
When a column name would hide a difference in the data: a field that is a string in one record and an object or array in another, or a key containing a dot that collides with a nested path. It also refuses a list that contains a number or a string among the records, JSON that is cut off, and prose with no JSON, because dropping a row or inventing a value loads without an error and is wrong for ever. The refusal is one line that starts with CANNOT FLATTEN and names the key, so a program can detect it.
Does it help Claude Sonnet?
Slightly. Without the skill Sonnet got 21 of 24 flattening setups right, with it 23 of 24. It already knew dotted headers, index columns, numbers copied as written, lowercase true and false, late keys and a planted instruction left as text. It missed the refusals: a dotted key colliding with a nested path, cut-off JSON (it kept the half-read name Bo) and a 5 among the records. Haiku went from 20 to 21.