# motherduck-duckdb-sql
> Look up or repair DuckDB SQL syntax and verify MotherDuck-specific command and feature support.
Look up or repair DuckDB SQL syntax and verify MotherDuck-specific command and feature support.

[Utility skill](/sql-reference/agent-skills/#utility-skills) · [View source on GitHub](https://github.com/motherduckdb/agent-skills/tree/v3.0.0/skills/motherduck-duckdb-sql)

:::info

This page shows the skill's `SKILL.md`: the instructions a coding agent loads when a task matches the description above. To install every MotherDuck skill in Claude Code, Codex, Cursor, or Gemini CLI, see [Install MotherDuck Skills](/key-tasks/ai-and-motherduck/agent-skills/). To install only this skill with the [Skills CLI](https://github.com/vercel-labs/skills), run:

```bash
npx -y skills add motherduckdb/agent-skills --skill motherduck-duckdb-sql --yes --global
```

:::

## Source of truth

- Prefer current DuckDB SQL docs for language features and function semantics.
- Use current MotherDuck SQL docs for MotherDuck-only commands such as shares, secrets, snapshots, and Dive operations.
- MotherDuck can lag upstream DuckDB releases for client compatibility; check MotherDuck version-lifecycle docs before promising newly released DuckDB syntax or types are available.
- If the connection path matters, verify behavior against the current Postgres-endpoint docs before promising server-mode support.

## Default posture

- Write DuckDB SQL, not PostgreSQL SQL, even when the client connects through the Postgres endpoint.
- Prefer fully qualified `"database"."schema"."table"` names; they are required once more than one database or share is attached.
- Prefer DuckDB-native constructs when they simplify the query: `GROUP BY ALL`, `QUALIFY`, `UNION BY NAME`, `arg_max`, `EXCLUDE`, and `REPLACE`.
- When porting SQL from another engine, translate functions, date arithmetic, identifier quoting, and type casts explicitly instead of assuming compatibility.
- Verify current MotherDuck support before relying on recently released upstream DuckDB features such as `VARIANT`, native `GEOMETRY`, `MERGE INTO`, or `date_trunc` return-type changes.
- Check whether the statement depends on local files, extension install/load, temporary-table behavior, or other client-only features before claiming it will work in MotherDuck.
- Treat snapshot, restore, and `UNDROP DATABASE` statements as operational SQL with plan-specific retention behavior, not ordinary analytical syntax.
- Treat `INCLUDE_PATTERN` as whole-table/view filtering on a Share. Row filters, hidden columns, and masking use share secure views (`WITH SECURE VIEW ... REPLACES <table> AS (SELECT ...)`, `ALTER SHARE ... ADD|DROP SECURE VIEW`), which are unrelated to DuckDB's `CREATE SECURE VIEW` optimizer barrier.
- Distinguish physical import (`CREATE DATABASE ... FROM '<file-url>'`, including a DuckDB file in cloud storage such as `'s3://bucket/app.db'`) from zero-copy clone sources. Reject filtered shares and shares with secure views as clone sources; use `COPY FROM DATABASE` instead.
- Use role/grant SQL for governed access and audit it with `SHOW ...` statements; do not preserve `ACCESS ORGANIZATION` as the preferred RBAC pattern.
- Treat MotherDuck SQL as an additional surface on top of DuckDB SQL, not a replacement for it.
- MotherDuck adds SQL AI functions: `prompt()` for generated or structured text, `embedding()` for vectors, and `prompt_jev()` for typed classification, scoring, yes/no probabilities, and image bounding boxes. See [`motherduck-query`](/sql-reference/agent-skills/motherduck-query/) for usage and cost rules.

## Workflow

1. Confirm the connection path and whether the question is about syntax, feature support, or a specific error.
2. Write or repair the statement in DuckDB SQL first.
3. Verify any MotherDuck-only command or server-mode limitation against the current docs.
4. If the user needs exact syntax or function details, open [`references/SYNTAX_REFERENCE.md`](https://github.com/motherduckdb/agent-skills/blob/v3.0.0/skills/motherduck-duckdb-sql/references/SYNTAX_REFERENCE.md).

## References

Read only the reference sections needed for the current task.

- Read [`references/SYNTAX_REFERENCE.md`](https://github.com/motherduckdb/agent-skills/blob/v3.0.0/skills/motherduck-duckdb-sql/references/SYNTAX_REFERENCE.md) for DuckDB data types, friendly SQL features, functions, complex types, and common MotherDuck-specific gotchas.

## Related skills

Load related skills only for missing capabilities; reuse established context.

- [`motherduck-query`](/sql-reference/agent-skills/motherduck-query/) for writing and validating analytical SQL against live MotherDuck data
- [`motherduck-connect`](/sql-reference/agent-skills/motherduck-connect/) when syntax support depends on PG endpoint versus native DuckDB behavior
- [`motherduck-explore`](/sql-reference/agent-skills/motherduck-explore/) when the problem is really missing schema context rather than missing syntax knowledge

## Files in this skill

The agent reads these files when the instructions above point to them.

- [`references/SYNTAX_REFERENCE.md`](https://github.com/motherduckdb/agent-skills/blob/v3.0.0/skills/motherduck-duckdb-sql/references/SYNTAX_REFERENCE.md)

## Docs this skill draws on

- [duckdb.org/docs](https://duckdb.org/docs/)
- [DuckDB SQL](https://motherduck.com/docs/sql-reference/duckdb-sql-reference/)
- [MotherDuck SQL](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/)
- [SHUTDOWN](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/shutdown-terminate/)
- [Data Recovery](https://motherduck.com/docs/concepts/database-and-storage/data-recovery/)
- [MotherDuck version lifecycle schedules](https://motherduck.com/docs/troubleshooting/version-lifecycle-schedules/)


---

## Docs feedback

MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`.
For agents and automated tools, feedback submission should be user-confirmed before sending.

URL-encode query parameter values and send a GET request:

```text
GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fsql-reference%2Fagent-skills%2Fmotherduck-duckdb-sql%2F&page_title=motherduck-duckdb-sql&text=<url-encoded user feedback, max 2000 characters>
```

Optionally append `&source=<url-encoded interface identifier>` such as `claude.ai` or `chatgpt`.

`page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": "<uuid>"}`, `400` for malformed query parameters, and `429` when rate-limited.
