query
by duckdbThe query skill runs DuckDB queries against an attached database or directly against files. It accepts SQL or natural-language questions, supports session and ad-hoc modes, and is useful for Data Analysis, quick checks, and iterative query work with DuckDB Friendly SQL.
This skill scores 71/100, which means it is listable for directory users who want a DuckDB query helper with real operational value, but they should expect some adoption friction and incomplete onboarding clarity. The repository shows a concrete workflow for routing between session and ad-hoc querying, so it is more than a placeholder; however, the install decision is less straightforward because the file offers little high-level guidance outside the step-by-step execution logic.
- Explicit trigger and scope: it is clearly for running SQL queries against an attached DuckDB database or ad-hoc against files, including natural-language questions.
- Concrete operational workflow: the skill defines state detection, session vs. ad-hoc mode, DuckDB availability checks, and fallback behavior.
- Implementation detail is substantial: the SKILL.md body is long, uses code fences, and includes repo/file references rather than only generic instructions.
- Sparse top-level description and no supporting files make it harder to quickly assess fit before install.
- No install command or companion resources are provided, so users may need to infer setup and edge-case behavior from the body alone.
Overview of query skill
What query skill does
The query skill helps you run DuckDB queries against either an attached working database or files you point to directly. It is built for people who want the fastest path from question to result: ad-hoc SQL, natural-language data questions, or simple file-based analysis with DuckDB Friendly SQL.
Who it fits best
Use the query skill for Data Analysis when you already have data in DuckDB, a project state file, or a local file like CSV/Parquet and want immediate answers without setting up a full pipeline. It is especially useful for analysts, engineers, and AI agents that need to inspect data quickly and iteratively.
Why this skill is different
The key differentiator in query is its mode selection. It can work in session mode when prior DuckDB state exists, or in ad-hoc mode when the input references files or when no state is available. That reduces guesswork and makes the query skill useful in both persistent and one-off workflows.
How to Use query skill
Install and basic invocation
Install the query skill with npx skills add duckdb/duckdb-skills --skill query. Then call it with either SQL or a question, for example: query "show daily revenue by country" or query "select count(*) from 'events.csv'". The query usage pattern works best when the request is specific enough to become one clear query.
How the skill chooses session or ad-hoc mode
The query skill first checks for an existing DuckDB state file in .duckdb-skills/state.sql or ~/.duckdb-skills/<project-id>/state.sql. If it finds one and the attached databases still work, it uses session mode. If you pass --file, reference file paths, or have no usable state, it switches to ad-hoc mode and queries files directly, or :memory: when needed. This is the most important part of the query guide, because your input should match the mode you actually want.
What to read first in the repo
Start with SKILL.md, since it contains the execution flow, mode rules, and fallback behavior. For install decisions, that is usually enough. If you are adapting the skill for your own workflow, also inspect any referenced files in the repository tree, especially anything that defines state handling or prompt constraints. In this repo there are no extra rules/, resources/, or helper scripts to learn.
Write better prompts for better queries
Give the skill the minimum context it needs to build the right query: target file or table, metric, grain, filters, and time range. Strong input looks like query "For orders.csv, show revenue by month for 2024 and exclude refunds"; weak input looks like query "analyze the sales data". The first tells the skill whether to use file-based access, what to aggregate, and which edge cases matter.
query skill FAQ
Is query skill only for SQL experts?
No. The query skill accepts raw SQL or natural language questions, so beginners can use it for straightforward analysis. SQL still helps when you need exact joins, filters, or aggregation rules.
When should I not use query skill?
Do not use it if your task needs multi-step transformation logic that belongs in a notebook, ETL job, or application code. It is optimized for asking and answering data questions, not for building a full data product.
How does it compare with a generic prompt?
A generic prompt may produce a plausible query, but the query skill adds operational rules: it checks for DuckDB state, chooses session vs ad-hoc mode, verifies DuckDB is available, and falls back safely when attachments fail. That makes it more reliable for install-time evaluation and repeated query usage.
Is it a good fit for files and local analysis?
Yes. If you want query for Data Analysis on local CSV, Parquet, or other DuckDB-readable files, this skill is a strong fit because it is designed to query files directly when session state is absent or inappropriate.
How to Improve query skill
Provide the exact data shape
The strongest improvements come from naming the source and the output shape. Include table names, file names, the columns you care about, and the grain you want back. For example: query "from sessions.parquet, group by user_id and return avg session length for paid users only" gives the skill enough structure to avoid broad or ambiguous results.
Remove ambiguity before the first run
Common failure mode: asking for “insights” without saying what should be counted, compared, or filtered. If you know the metric, the date window, or the segmentation rule, include it up front. That reduces back-and-forth and makes the first answer more useful.
Check mode-specific constraints early
If you expect session mode, make sure the project state is present and its attached databases still open. If you expect file mode, reference the file directly in the prompt or pass --file. This matters because the query skill behaves differently depending on whether it can reuse existing state or must work ad hoc.
Iterate by tightening the query goal
After the first result, improve the next prompt by adding one constraint at a time: a narrower time range, a better join key, a different grouping level, or a required exclusion. That keeps the query skill moving toward a decision-ready result instead of a vague summary.