Most Claude Code (which I’m using as a brand placeholder for “any coding agent”) plugins require you to trust a custom binary or a background process you can’t easily inspect. duckdb-skills, the official DuckDB plugin for Claude Code, is built on a different premise: each skill is a markdown file containing structured bash instructions that Claude executes using the DuckDB CLI you already have installed. No daemon, no SDK dependency, no custom runtime. The whole thing is just prompt templates and shell commands, which makes it surprisingly transparent for a tool this capable.
Installation right now means going through GitHub directly – Anthropic marketplace listing is pending, but /plugin marketplace add duckdb/duckdb-skills and /plugin install duckdb-skills@duckdb-skills gets you there. Folks using OpenCode or other agent frameworks can generally just copy the skills (or symbolic link them) into the agen’ts “skills/ directory. Once installed, six skills drop into your sessions after that.
For each “query project”, state lives in a state.sql file: a plain SQL file holding ATTACH, USE, LOAD, and secret statements that any skill can replay with duckdb -init state.sql. You choose at setup whether that file goes into the project directory (.duckdb-skills/state.sql) or your home directory (~/.duckdb-skills/<project>/state.sql). The second option is useful when you don’t want the state mixed into the repo. Either way, the file is readable, editable, and version-controllable without any special tooling – which turns out to matter when you need to debug why a session isn’t restoring correctly.
The six skills divide into roughly two groups. The data access skills – attach-db, query, and read-file – form a chain: attach a database or point at a file, query it in SQL or natural language, and iterate. read-file supports CSV, JSON, Parquet, Avro, Excel, SQLite, spatial formats, Jupyter notebooks (interesting inclusion), and remote storage across S3, GCS, Azure, and HTTPS, with format detection keyed to file extension through a read_any macro. query handles both raw SQL and natural language questions, uses DuckDB’s Friendly SQL dialect, estimates result sizes before running queries against large data, and has a layered error recovery chain that corrects syntax, installs missing extensions, and checks the schema against missing table references.
The utility skills – duckdb-docs, read-memories, and install-duckdb – are where things get more interesting. install-duckdb is fairly self-explanatory: it installs extensions, supports community extensions via name@repo syntax, and can check your CLI version. read-memories searches past Claude Code session logs using DuckDB’s FTS extension to recover context from previous work – earlier decisions, open threads, established patterns.
duckdb-docs is the one worth spending a moment on. It queries a pre-built documentation index hosted at duckdb.org/data/docs-search.duckdb using DuckDB’s full-text search extension – so you’re using DuckDB to search DuckDB’s own documentation, which is a pleasing kind of self-reference. The index is cached locally with a two-day TTL; updates are atomic (download to .tmp, then rename), so an interrupted fetch doesn’t corrupt your local copy. Version-aware search covers lts, current, and blog for DuckDB proper, plus stable and preview for DuckLake. Where it integrates most usefully is in error handling: query, read-file, and read-memories all fall through to duckdb-docs automatically when they encounter errors they can’t resolve. The LLM searches the documentation rather than guessing, which substantially narrows the gap between “Claude knows DuckDB” and “Claude has access to current DuckDB documentation.”
The query skill also includes a Friendly SQL reference appendix baked into its prompt – concrete DuckDB idioms like FROM-first syntax, GROUP BY ALL, COLUMNS(*), and SUMMARIZE – so the LLM has a precise vocabulary to draw from rather than falling back on generic SQL patterns that happen to be less idiomatic in DuckDB. It’s a small thing that compounds over a lot of queries.
Windows isn’t supported yet, which the README states plainly. The plugin would benefit from a CONTRIBUTING.md that explains the skill file format and the state.sql contract – right now you have to reverse-engineer that from the existing skill files, which is fine but slower than it needs to be. Neither of those is a reason to skip it.
The zero-infrastructure design means there’s nothing to maintain between sessions beyond the state file, and the transparency of the skill files means you can read exactly what Claude is doing when something doesn’t behave as expected. That combination – capable enough to actually use, simple enough to actually understand – is harder to achieve than it looks. The repo is at github.com/duckdb/duckdb-skills; issues and PRs are open if you run into something or want to contribute a skill.