docs(skills): tell agents what a load does not report - #296
Conversation
Three things an agent cannot infer from the load's own output. A `;`- or tab-separated csv loads with no error into a single column named `id;name` — the load has no delimiter option, so a load that mangles every row still prints "Table loaded" and a row count, and an agent reports success. The skill now says to check the column list with `databases tables show` after loading a csv it did not write, which is where the single column shows up (verified). A `.tsv` extension fails with a 500, so that is named too. "json in any shape" is the CLI's local reshape, not an API feature: the load API and both SDKs take newline-delimited json only. An agent that prototypes with `databases load --file data.json` and then writes SDK code hits a schema inference error with nothing to connect it to. The two local json refusals — `one object per row` and `carries no json rows` — are worth naming as not-retryable. An unrecognised error is exactly what an agent retries unchanged. Skills ship in the release artifact (`skills.tar.gz`), so this reaches agents with the next tag rather than on merge.
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
|
|
||
| **Loading — three checks before you trust a load:** | ||
|
|
||
| - **A csv must be comma-separated.** A `;`- or tab-separated file loads **with no error** into a single column named `id;name` — the load has no delimiter option, so nothing reports this. After loading a csv you did not write yourself, run `databases tables show` and check the column list before you query or report success. (A `.tsv` extension currently fails with a 500.) |
There was a problem hiding this comment.
super nit: the column name id;name only matches the ;-separated case (not blocking). A tab-separated file yields a column named id<TAB>name, so an agent looking for the literal id;name may miss the tab case. Naming the example as the ; case keeps the check exact.
There was a problem hiding this comment.
Docs-only change. Verified against the code: the two local json refusals match src/commands/json_rows.rs:121 and src/commands/databases.rs:1351, the reshape is CLI-side in json_rows.rs, and databases tables load exposes no delimiter option. The .tsv 500 and the server's single-column csv behavior are server-side claims that the repo cannot confirm. One super nit inline.
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
1 participant
Three things an agent can't infer from the load's own output: a
;-separated csv loads with no error into one column (checkdatabases tables show), "json in any shape" is the CLI's local reshape and not an API feature, and the two local json refusals are not retryable unchanged.