duckdb-sql_skill

Overview

This skill helps you generate, review, and improve DuckDB SQL queries for .ddb, CSV, and Parquet sources. It prioritizes existing project documentation in duckdb_sql_assets/ and is display-only by default, producing ready-to-run queries and guidance for in-memory DuckDB sessions.

How this skill works

On every request the skill first checks duckdb_sql_assets/ for tables_inventory.json, schema_*.sql, and data_dictionary.md and uses those files as the single source of truth. It produces DuckDB-compliant SQL (including ATTACH preambles for .ddb files) and never runs queries unless you explicitly request execution. For new projects it guides you through a controlled initialization flow to generate assets and schema files.

When to use it

• You need a DuckDB SQL query written for .ddb, .csv, or .parquet data.
• You want to explore or document what tables and fields exist in a project.
• You need an existing SQL reviewed or optimized for DuckDB.
• You want safe, copy-paste-ready queries with proper ATTACH and path conventions.
• You want to initialize duckdb assets (use initialization trigger phrases).

Best practices

• Always let the skill read duckdb_sql_assets/ first — those files are the source of truth.
• Default behavior is to display SQL only; explicitly request 'run', 'execute', or 'show results' to run queries.
• Use relative paths by default; only use absolute paths when you explicitly provide them.
• Include ATTACH statements for .ddb files using the _db_<slug> alias convention.
• Cross-reference data_dictionary.md and schema_*.sql when writing joins, enums, and filters.

Example use cases

• Generate a query that joins a table inside sales.ddb with a transactions CSV and filters by recent dates.
• Review and optimize a provided SELECT with joins and GROUP BY for DuckDB performance.
• Explain which tables and key fields exist using tables_inventory.json and data_dictionary.md.
• Initialize duckdb_sql_assets/ for a new project by providing file paths or glob patterns.
• Detect likely enum columns during initial asset creation and add them to the data dictionary.