A coding agent that needs to answer a question about a Parquet file usually reaches for the most general tool it has. It writes a short Python script, runs it, and reads the output. The DuckDB team described this pattern in their September 2026 post introducing duckdb-skills, a Claude Code plugin, and their complaint is specific: the script route is slow, and the agent guesses column names and types without checking them. Their answer was to give the agent the DuckDB CLI through a set of skills, so a question about a file becomes a SQL query against it.
The plugin is a good motivating example. The more durable lesson is how you decide which surface to expose to an agent at all. Here is the framework I would use, with the DuckDB case as the worked example.
1. Prefer tools whose failures carry the next step
The example interaction in the DuckDB post is worth reading for the error, not the answer. The agent runs SELECT count(*) FROM 'trips.parquet' WHERE distance > 10. DuckDB replies with a Binder Error: column “distance” not found, candidate bindings: “trip_distance”. The agent reads that, fixes the column name, and gets a count.
That loop works because the error names the fix. A script that prints a traceback gives the agent a symptom; a binder error with candidate bindings gives it a correction. When you evaluate a tool for agent use, look at what it says when the call is wrong, because a wrong call is the normal case on the first attempt.
2. Prefer tools that replace a guess with an observation
“Guesses column names and types” is the real cost of the script approach. The script still runs; it just runs on assumptions. The plugin includes a read-file skill that reads and profiles a data file (CSV, JSON, Parquet, Avro, Excel, spatial, SQLite, Jupyter) on local disk or in S3, GCS, Azure or over HTTPS. Profiling is a call the agent can make before it forms a query, so the schema is observed rather than assumed.
The general rule: for each step where the agent currently infers something, ask whether a tool could return that fact exactly. If it can, replace the inference with a call.
3. Keep session state in a file you can read
The skills share a per-project state.sql file, described as a plain SQL script of ATTACH, USE and LOAD statements, secrets and macros, so a session can be restored with duckdb -init state.sql. Two things follow.
First, the agent’s working context is inspectable. You can open the file and see what it attached and loaded, which is better than context that exists only inside a conversation transcript.
Second, if secrets go into that file, it is a credential file and should be treated like one: outside version control, with the same access rules as any stored key. The post says the file holds secrets; I have not checked how the plugin handles them beyond that description, so verify before committing anything from a project directory that has been used with the skills.
4. Sort the tools by what they can change
Not every skill is a read. query and read-file read. convert-file writes new files. install-duckdb installs or updates extensions, including community extensions. The post also notes that you do not need to type the slash command: each skill carries a description that tells Claude Code when it applies, so the agent picks the skill from a plain-language request.
That convenience is the point of the plugin, and it is also the thing to think about. An agent that selects install-duckdb on its own because a request implied it is doing something with a different blast radius than counting rows. Your agent harness, not the skill, decides what requires confirmation, so check that boundary instead of assuming the skill set is read-only. None of this replaces database or bucket permissions either: an agent driving DuckDB inherits whatever credentials DuckDB can see.
5. The same move works on metadata
Once a tool returns exact answers, questions that used to need a script become queries. DuckDB’s post on dbt v2 (also September 2026) applies the same idea to project metadata: dbt parse --generate-info-schema writes the manifest as Parquet files under target/info_schema/v1/, and DuckDB can query those to list models, their materialization and target schema, or find models missing tests, without standing up dbt or the warehouse. That is the right shape for a CI convention check, and it is the same principle as the skills plugin: pick a representation the tool can answer exactly.
Where this stops
An exact answer to the wrong query looks authoritative. The retry loop fixed a column that did not exist; it would not catch a column that exists and means something different from what the user intended. The tool removes guesses about the data’s shape, not about the question. Keep the agent’s SQL visible in the conversation so a human reads the query and not only the number.
The DuckDB post also publishes no timings. “Slow” is the team’s characterization of the script route, and nothing here claims a measured speedup.
Next step
If you use Claude Code on data files, the DuckDB post has the install command and the skill list. If you use another agent, the transferable exercise is: take the last three data questions your agent answered by writing a script, and check which ones a CLI you already trust could have answered with one call and a useful error. If you know a data tool whose error messages are unusually good or bad for agents, I would like to hear which one.