--- title: "Level Up Your Agent's SQL Ops With DuckDB Agent Skills" description: "DuckDB's official Claude Code plugin uses plain markdown skills and shell commands instead of daemons or SDKs — six skills that make SQL operations in agent sessions transparent, stateful, and self-correcting." pubDatetime: 2026-04-18T10:00:00Z author: hrbrmstr tags: ["duckdb", "claude-code", "ai-agent", "sql", "mcp", "developer-tools"] --- > Original: [Level Up Your Agent's SQL Ops With DuckDB Agent Skills](https://ai.rud.is/posts/2026-04-18-duckdb-agent-skills) 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](https://github.com/duckdb/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//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](https://github.com/duckdb/duckdb-skills); issues and PRs are open if you run into something or want to contribute a skill.