---
title: "DuckDB read file: review, setup & limitations · Undominated.ai"
canonical: https://undominated.ai/skills/duckdb-read-file/
description: "DuckDB's read-file skill: one DuckDB CLI command that picks a reader by file extension and returns a file's schema, row count and first 20 rows, for local paths or HTTPS, S3, GCS and Azure URLs."
---

# DuckDB read file: review, setup & limitations · Undominated.ai

> DuckDB's read-file skill: one DuckDB CLI command that picks a reader by file extension and returns a file's schema, row count and first 20 rows, for local paths or HTTPS, S3, GCS and Azure URLs.

[← Explore all skills](/skills/)

DATABASES / DuckDB

# DuckDB read file

DuckDB's read-file skill: one DuckDB CLI command that picks a reader by file extension and returns a file's schema, row count and first 20 rows, for local paths or HTTPS, S3, GCS and Azure URLs.

 [See setup guidance ↓](#setup)[Original source ↗](https://duckdb.org)

SOURCE REVIEW

 Reviewed 2026-10-21
 Evidence 5 linked sources
 Publisher DuckDB
 Licence [MIT ↗](https://github.com/duckdb/duckdb-skills/blob/7feda8e01e22bc0886c86123f3884947e36d8c69/LICENSE)
 Revision 7feda8e01e22
 [Read what was—and wasn’t—checked ↓](#review)

“Read any data file (CSV, JSON, Parquet, Avro, Excel, spatial, SQLite) or remote URL (S3, HTTPS). Use when user references a data file, asks "what's in this file", or wants to preview/profile a dataset. Not for source code.”

 [DuckDB · upstream description ↗](https://github.com/duckdb/duckdb-skills/blob/7feda8e01e22bc0886c86123f3884947e36d8c69/skills/read-file/SKILL.md) Our analysis follows below.

01 / THE REASONING

## Why this made the selection.

 - DuckDB publishes it in duckdb/duckdb-skills as one skill of the duckdb-skills Claude Code plugin (plugin.json version 0.2.4, license MIT); LICENSE is the MIT text with "Copyright 2018-2025 Stichting DuckDB Foundation".
- A single `duckdb -csv -c` command defines a read_any table macro that chooses a reader by file extension (.json, .jsonl, .ndjson, .geojson, .geojsonl and .har; .csv, .tsv, .tab and .txt; .parquet and .pq; .avro; .xlsx and .xls; .shp, .gpkg, .fgb and .kml; .ipynb; .db, .sqlite and .sqlite3; read_blob otherwise), then runs DESCRIBE, a row count and a 20-row sample.
- It gives a prefix table for remote paths (https/http, s3, gs/gcs, az/azure/abfss) and three named failure branches: DuckDB CLI not found, missing extension, and wrong reader or parse error.

### A good fit for

 - Show the column types, row count and first 20 rows of a local CSV, Parquet, JSON, Avro, Excel or SQLite file
- Read a remote file over HTTPS, S3, GCS or Azure without writing the DuckDB query by hand
- List a Jupyter notebook's cells with their type, source and execution count
- Answer a question about a data file from its schema, row count and sample rows

### Weigh up before choosing

 - The skills/read-file directory last changed in a commit dated 2026-03-30; the pinned revision 7feda8e0 is dated 2026-04-14.
- The README says the skills were tested on macOS and Linux and that Windows is not yet fully supported: some shell commands and path handling may not work as expected.
- Needs the DuckDB CLI installed first. On `duckdb: command not found` the skill invokes `/duckdb-skills:install-duckdb`, but that skill does not install the CLI: it prints `brew install duckdb` (macOS), `curl -fsSL https://install.duckdb.org | sh` (Linux, an unpinned remote script piped to a shell) or `winget install DuckDB.cli` (Windows), and stops if DuckDB is not found.
- Spatial, xlsx and sqlite files can need `INSTALL spatial; LOAD spatial;` or `INSTALL sqlite_scanner; LOAD sqlite_scanner;` prepended; on a wrong reader or parse error the skill calls the matching read_* function instead of read_any.
- Extensions outside the macro's list fall through to read_blob, and the SQLite branch reads only the first table name that sqlite_master returns (LIMIT 1).
- For s3, gs/gcs and az/azure/abfss paths the skill prepends LOAD httpfs (plus LOAD azure for Azure) and a CREATE SECRET with PROVIDER credential_chain; it names no other way to pass cloud credentials.
- Every install route the README prints loads the whole duckdb-skills plugin: the marketplace commands, and `claude --plugin-dir .` from a clone for local testing. The README says a listing in the Discover tab is coming soon.
- Licence: MIT in LICENSE, "Copyright 2018-2025 Stichting DuckDB Foundation"; .claude-plugin/plugin.json also says MIT.

02 / THE REVIEW RECORD

## What we actually inspected.

Source review has boundaries. A clear record is more useful than a “safe” badge.

### Material inspected

 - skills/read-file/SKILL.md: frontmatter, the read_any command, the remote prefix table and the failure branches
- README.md: installation, the read-file entry, prerequisites, how the skills work together, platform support
- LICENSE
- .claude-plugin/plugin.json
- skills/install-duckdb/SKILL.md: frontmatter and Step 1 (locate DuckDB)
- Repository tree at 7feda8e0: nine skills/*/SKILL.md files

### Our findings

 - The frontmatter declares `allowed-tools: Bash` and the argument hint `<filename or URL> [question about the data]`.
- A bare filename (no /) is resolved to a full path with `find` before the duckdb command runs.
- The README says secrets and macros set up by read-file are reused by query through the shared state.sql, and that read-file uses duckdb-docs to troubleshoot errors. The read-file SKILL.md at this revision defines read_any inside each command, does not mention state.sql, and names install-duckdb, not duckdb-docs, in its failure branches.
- The README says the skills offer to install the DuckDB CLI via /duckdb-skills:install-duckdb; that skill's Step 1 only tells the user how to install it and stops if DuckDB is not found.
- The plugin install brings nine skills at this revision (attach-db, convert-file, duckdb-docs, install-duckdb, query, read-file, read-memories, s3-explore, spatial); the README describes six of them.

### Not established by this review

 - Not executed: it was not installed or run.
- No DuckDB command was run and no local or remote file was read.
- No extension was installed and no cloud secret was created.
- Behaviour on Windows was not checked.

The review applies to the material and revision named here. A newer upstream release can change its behavior.

03 / PUT IT TO WORK

## Add a skill to your workflow.

[Upstream setup instructions ↗](https://github.com/duckdb/duckdb-skills/blob/7feda8e01e22bc0886c86123f3884947e36d8c69/README.md)
 - The README's "From GitHub (available now)" section prints `/plugin marketplace add duckdb/duckdb-skills` and `/plugin install duckdb-skills@duckdb-skills` for Claude Code. They install the whole duckdb-skills plugin, which has nine skills/*/SKILL.md files at this revision, not read-file alone.
- Skills are then available as `/duckdb-skills:<skill-name>`; this one runs as `/duckdb-skills:read-file` with a filename or URL and an optional question about the data.
- For local testing, the README prints `claude --plugin-dir .` from a clone of the repository; that also loads the whole plugin from disk.

### Before you start

 - The DuckDB CLI, installed beforehand. The README says the skills offer to install it via `/duckdb-skills:install-duckdb`; that skill prints `brew install duckdb`, `curl -fsSL https://install.duckdb.org | sh` or `winget install DuckDB.cli` and stops if DuckDB is not found.
- macOS or Linux, the platforms the README says were tested.
- For s3, gs/gcs or az/azure/abfss paths only: cloud credentials for the credential_chain secret the skill creates.

### Compatibility

Claude Code

### Implementation

SQL

### Runs the DuckDB CLI through Bash on a named file or URL

 - Frontmatter allowed-tools: Bash.
- Runs `find` to resolve a bare filename, then one `duckdb -csv -c` command that defines read_any and runs DESCRIBE, a row count and LIMIT 20 on the file.
- Reads local files by path; https/http URLs after LOAD httpfs; s3, gs/gcs and az/azure/abfss URLs after LOAD httpfs (plus LOAD azure for Azure) and a CREATE SECRET with PROVIDER credential_chain.
- On failure, retries with INSTALL and LOAD of the spatial or sqlite_scanner extension, or invokes `/duckdb-skills:install-duckdb`, which only prints CLI install commands when DuckDB is missing.
- Answers from the schema, row count and up to 20 sample rows the command prints.

### Cost model

MIT skill text. The files read state no fee for the skill or for DuckDB, and do not address charges for reading from S3, GCS, Azure or HTTPS hosts.

04 / FOLLOW THE EVIDENCE

## The source trail.

Our notes are separate from the original resource. Check upstream before adopting a new version.

 - [read-file SKILL.md at 7feda8e0 ↗](https://github.com/duckdb/duckdb-skills/blob/7feda8e01e22bc0886c86123f3884947e36d8c69/skills/read-file/SKILL.md) Checked 2026-10-21 https://github.com/duckdb/duckdb-skills/blob/7feda8e01e22bc0886c86123f3884947e36d8c69/skills/read-file/SKILL.md Supports: upstreamDescription, whySelected[1], whySelected[2], bestFor, language, access.permissions, install.steps[1], limitations[2], limitations[3], limitations[4], limitations[5], review.findings
- [README.md at 7feda8e0 ↗](https://github.com/duckdb/duckdb-skills/blob/7feda8e01e22bc0886c86123f3884947e36d8c69/README.md) Checked 2026-10-21 https://github.com/duckdb/duckdb-skills/blob/7feda8e01e22bc0886c86123f3884947e36d8c69/README.md Supports: install, compatibility, whySelected[0], limitations[1], limitations[6], review.findings
- [MIT LICENSE at 7feda8e0 ↗](https://github.com/duckdb/duckdb-skills/blob/7feda8e01e22bc0886c86123f3884947e36d8c69/LICENSE) Checked 2026-10-21 https://github.com/duckdb/duckdb-skills/blob/7feda8e01e22bc0886c86123f3884947e36d8c69/LICENSE Supports: license, whySelected[0], limitations[7]
- [.claude-plugin/plugin.json at 7feda8e0 ↗](https://github.com/duckdb/duckdb-skills/blob/7feda8e01e22bc0886c86123f3884947e36d8c69/.claude-plugin/plugin.json) Checked 2026-10-21 https://github.com/duckdb/duckdb-skills/blob/7feda8e01e22bc0886c86123f3884947e36d8c69/.claude-plugin/plugin.json Supports: homepage, license, whySelected[0], limitations[7]
- [install-duckdb SKILL.md at 7feda8e0 ↗](https://github.com/duckdb/duckdb-skills/blob/7feda8e01e22bc0886c86123f3884947e36d8c69/skills/install-duckdb/SKILL.md) Checked 2026-10-21 https://github.com/duckdb/duckdb-skills/blob/7feda8e01e22bc0886c86123f3884947e36d8c69/skills/install-duckdb/SKILL.md Supports: install.prerequisites, access.permissions, limitations[2], review.findings

KEEP COMPARING

## Other approaches to consider.

Related by category or shared topics. These are alternatives to inspect, not a measured quality order.

 [### Turso Database ↗ Turso's skill for its in-process SQLite-compatible engine: hard constraints first, then decision trees to feature and SDK reference files, plus CLI, SQL and MCP quick references.](/skills/tursodatabase-turso-db/)[### CockroachDB SQL ↗ Cockroach Labs skill that turns a natural-language request into CockroachDB SQL, applies the relevant rule files with 00-fundamental-principles.md first, and tells the agent to run EXPLAIN on every generated query when a cluster connection is available.](/skills/cockroachlabs-cockroachdb-sql/)[### dbt Documentation Maintenance ↗ Audits descriptions in a dbt manifest and drafts missing model or column documentation in the project’s existing style.](/skills/dbt-labs-maintaining-dbt-documentation/)

 [AI Tools ↗](/tools/)[Skills ↗](/skills/)[Agents ↗](/agents/)[MCP Servers ↗](/mcp-servers/)[Workflows ↗](/workflows/)

## Continue your investigation

 - [Choose a toolkit](/tools/)
- [Inspect execution hosts](/agents/)
- [Check tool access](/mcp-servers/)
- [Check project dependencies](/check-repo/)
