motherduckdb/motherduck-query
plugins/motherduck-skills/skills/motherduck-query/SKILL.md
Execute DuckDB SQL queries against MotherDuck databases. Use when running analytics, aggregations, transformations, or any SQL operation. Covers query best practices, CTEs, window functions, QUALIFY, and performance optimization.
$ install --global
skillsauthnpx skillsauth add motherduckdb/agent-skills motherduck-queryInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: May 7, 2026, 2:26 AM351.9s2 files scanned
SKILL.md
- name:
- motherduck-query
- description:
- Execute DuckDB SQL queries against MotherDuck databases. Use when running analytics, aggregations, transformations, or any SQL operation. Covers query best practices, CTEs, window functions, QUALIFY, and performance optimization.
- license:
- MIT
Query MotherDuck
Use this skill when executing SQL queries for analytics, aggregations, transformations, or data exploration against MotherDuck databases.
Prerequisites
- MotherDuck connection established via
motherduck-connect - Target database and tables identified via
motherduck-explore
Default Posture
- Write DuckDB SQL, not PostgreSQL SQL, even when using the PG endpoint.
- Always use fully qualified
"database"."schema"."table"names. - Preserve the intended grain of every result set; state the grain before optimizing or materializing a query.
- Filter early, aggregate early, and prefer serving tables or summaries for repeated reads.
- Keep SQL obvious, multi-line, and explicit about grain, filters, and output shape.
- Treat DDL, DML,
ATTACH,DETACH, recovery commands such asCREATE SNAPSHOT,ALTER DATABASE ... SET SNAPSHOT,UNDROP DATABASE, and lifecycle commands such asSHUTDOWNas writes. Use MCPquery_rwonly when the user explicitly asks for the change and confirms it. - Tag long-lived integrations with
custom_user_agentwhen the connection path supports it.
Workflow
- Confirm the actual tables, columns, and grain before writing SQL.
- Write the query in SQL first, then wrap it in Python or TypeScript only if needed.
- Use CTEs and DuckDB-native patterns such as
GROUP BY ALL,QUALIFY, andarg_max. - Check the plan, row count, and shape for pushdown, unnecessary sorts, or repeated raw rescans.
- Materialize expensive repeated queries into serving tables or light views when warranted.
Open Next
references/QUERY_PLAYBOOK.mdfor DuckDB query patterns, exploration SQL, performance rules, common analytical shapes, and common mistakes
Related Skills
motherduck-connectfor session setupmotherduck-duckdb-sqlfor syntax and function referencemotherduck-explorefor understanding the source schema before writing queries
Related Skills
motherduckdb/motherduck-connect
development
VerifiedTrustedCommunity
Connect to MotherDuck from any application. Use when setting up database connectivity via the Postgres endpoint (recommended), pg_duckdb, native DuckDB API, or JDBC. Covers connection strings, authentication, SSL, and environment variable configuration.
19SKILL.mdUpdated Apr 25, 2026
motherduckdb/motherduck-connect
development
VerifiedTrustedCommunity
Connect to MotherDuck from any application. Use when setting up database connectivity via the Postgres endpoint (recommended), pg_duckdb, native DuckDB API, or JDBC. Covers connection strings, authentication, SSL, and environment variable configuration.
19SKILL.mdUpdated Apr 25, 2026
motherduckdb/motherduck-connect
development
VerifiedTrustedCommunity
Connect to MotherDuck from any application. Use when setting up database connectivity via the Postgres endpoint (recommended), pg_duckdb, native DuckDB API, or JDBC. Covers connection strings, authentication, SSL, and environment variable configuration.
19SKILL.mdUpdated Apr 25, 2026
motherduckdb/motherduck-share-data
data-ai
VerifiedTrustedCommunity
Create and manage MotherDuck data shares for zero-copy data distribution. Use when sharing databases with team members, other organizations, or making data publicly available.
17SKILL.mdUpdated May 7, 2026