MotherDuck Skills is an installable skill catalog that teaches coding agents to work with MotherDuck: choose the right connection path, inspect the live workspace, write DuckDB SQL instead of PostgreSQL-shaped SQL, use Dives and shares, and keep production analytics patterns safe.
20 skills in three layers: utility (connect, explore, query, SQL syntax, REST API), workflow (load, model, share, Dives, Flights, DuckLake, security, pricing), and use-case (apps, dashboards, pipelines, migrations, rollouts). See the full catalog.
Quick Install
Pick your harness and paste:
| Harness | Install |
|---|
Claude Code | /plugin marketplace add motherduckdb/agent-skills then /plugin install motherduck-skills@motherduck-skills |
GitHub Copilot CLI | /plugin marketplace add motherduckdb/agent-skills then /plugin install motherduck-skills@motherduck-skills |
Codex | codex plugin marketplace add motherduckdb/agent-skills, then install MotherDuck Skills from /plugins |
Cursor | npx -y skills add motherduckdb/agent-skills --agent cursor --skill '*' --yes --global |
Gemini CLI | gemini extensions install https://github.com/motherduckdb/agent-skills --consent |
| Anything else | npx -y skills add motherduckdb/agent-skills --skill '*' --yes --global |
Requirements: Git on your PATH, and Node.js 18+ for the Skills CLI route. For live MotherDuck work, authenticate through your normal path (MOTHERDUCK_TOKEN, Postgres endpoint credentials, a native md: DuckDB connection, or MotherDuck MCP) — never paste tokens into prompts or skill files.
Done? Jump to Verify the Installation. Per-harness details and alternatives are below.
Install Details by Harness
Skills CLI
The most portable path for Cursor, VS Code/GitHub Copilot, Codex, Claude Code, custom agents, and project-level installs:
npx -y skills add motherduckdb/agent-skills --skill '*' --yes --global
Default to a global (--global) install so the skills are available across all projects; drop the flag for a project-scoped install.
Check what got installed:
npx -y skills ls -g
npx -y skills ls -g -a cursor
npx -y skills ls -g -a github-copilot
GitHub Copilot CLI
Use the plugin path when you want the full MotherDuck bundle available inside Copilot CLI.
Inside a Copilot CLI session, add the marketplace the first time:
/plugin marketplace add motherduckdb/agent-skills
Install the plugin:
/plugin install motherduck-skills@motherduck-skills
Update later:
/plugin update motherduck-skills@motherduck-skills
This repository exposes the Copilot-compatible marketplace through .claude-plugin/marketplace.json; Copilot CLI also looks in .claude-plugin/ for plugin marketplaces.
For VS Code agent mode or Copilot cloud agent skills, use a skills install rather than the Copilot CLI plugin install:
npx -y skills add motherduckdb/agent-skills --agent github-copilot --skill '*' --yes --global
GitHub CLI also has a native gh skill flow. It is useful when you want to inspect and install one skill at a time:
gh skill preview motherduckdb/agent-skills motherduck-connect
gh skill install motherduckdb/agent-skills motherduck-connect --agent github-copilot --scope user
To browse the catalog interactively:
gh skill install motherduckdb/agent-skills
GitHub's gh skill support is in public preview, so prefer the Skills CLI for a repeatable "install everything" command.
Copilot skill locations to know:
| Scope | Common locations |
|---|
| Project skills | .github/skills, .claude/skills, .agents/skills |
| Personal skills | ~/.copilot/skills, ~/.agents/skills |
Claude Code
Add the marketplace the first time:
/plugin marketplace add motherduckdb/agent-skills
Install the plugin:
/plugin install motherduck-skills@motherduck-skills
Update later:
/plugin update motherduck-skills@motherduck-skills
For local plugin development and validation:
claude --plugin-dir ./plugins/motherduck-skills-claude
Codex
Add the marketplace:
codex plugin marketplace add motherduckdb/agent-skills
Then open /plugins in Codex and install MotherDuck Skills from the repo marketplace.
Enable or disable individual skills from /skills after the plugin is installed.
Cursor
Cursor supports plugins that can bundle skills, and this repo ships Cursor manifests at .cursor-plugin/plugin.json and .cursor-plugin/marketplace.json.
Until MotherDuck Skills has a published Cursor Marketplace listing, use the Skills CLI for local installs:
npx -y skills add motherduckdb/agent-skills --agent cursor --skill '*' --yes --global
For project-scoped installs, run the same command without --global from the repository where you want Cursor to use the skills:
npx -y skills add motherduckdb/agent-skills --agent cursor --skill '*' --yes
Check the install:
npx -y skills ls -g -a cursor
Restart Cursor or reload the window so it re-indexes installed skills. Then prompt with:
Use MotherDuck Skills to inspect my schema and recommend a dashboard starting point.
For plugin development or marketplace submission, keep .cursor-plugin/plugin.json, .cursor-plugin/marketplace.json, skills/, and assets/duck_skills.png together at the plugin root.
Gemini CLI
Install the extension from GitHub:
gemini extensions install https://github.com/motherduckdb/agent-skills --consent
For local development from a checkout:
gemini extensions link .
Manual Per-Skill Install
Copy the full skill directory, not only SKILL.md, so referenced references/, scripts/, and artifacts/ stay available.
mkdir -p ~/.agents/skills
cp -R skills/motherduck-connect ~/.agents/skills/motherduck-connect
Verify the Installation
After install, try three checks.
1. Verify Skill Routing
Ask:
Use MotherDuck Skills to choose the best connection path for this project.
You should get MotherDuck-specific connection guidance, including the Postgres endpoint and native DuckDB tradeoffs.
2. Verify SQL Defaults
Ask:
Write a MotherDuck query that joins two analytics tables and explain any DuckDB syntax assumptions.
You should see DuckDB SQL guidance, not PostgreSQL-only syntax.
3. Verify Live Discovery
If MotherDuck MCP or another live connection is available, ask:
Explore my MotherDuck workspace and summarize the databases, schemas, and likely dashboard starting points.
The agent should inspect real metadata before inventing examples.
Prompts to Try
Use MotherDuck Skills to connect this app to MotherDuck.Explore my MotherDuck workspace and identify the best table for a dashboard.Write a DuckDB SQL query for this KPI and validate the syntax.Design a Dive-backed dashboard from these tables.Plan a Snowflake-to-MotherDuck migration with validation and rollback steps.Design a customer-facing analytics architecture on MotherDuck.Decide whether this workload needs DuckLake or native MotherDuck storage.Use the MotherDuck REST API guidance to manage service accounts and tokens safely.
Start Here by Task
For narrow technical work, start with motherduck-connect, then motherduck-explore, then motherduck-query. For end-to-end product work, start with the matching use-case skill and let it orchestrate the lower layers.
| If you need to... | Start with... |
|---|
| Connect an app or service to MotherDuck | motherduck-connect |
| Inspect a live workspace or schema | motherduck-explore |
| Write or debug analytics SQL | motherduck-query |
| Check exact DuckDB syntax | motherduck-duckdb-sql |
| Use the REST API for service accounts, tokens, Duckling config, active accounts, or Dive embed sessions | motherduck-rest-api |
| Load files, cloud objects, HTTPS data, dataframes, or upstream systems | motherduck-load-data |
| Model schemas, tables, views, or transformation layers | motherduck-model-data |
| Publish, consume, or govern shares | motherduck-share-data |
| Build, theme, preview, save, update, or embed a Dive | motherduck-create-dive |
| Design a responsive, reusable Dive with filters and light/dark themes | motherduck-design-dive |
| Schedule a Python job (Flight) for ingestion or transformation | motherduck-create-flight |
| Evaluate DuckLake | motherduck-ducklake |
| Plan security, access, governance, or residency | motherduck-security-governance |
| Frame workload cost drivers or ROI | motherduck-pricing-roi |
| Build customer-facing analytics | motherduck-build-cfa-app |
| Build a dashboard | motherduck-build-dashboard |
| Design a data pipeline | motherduck-build-data-pipeline |
| Plan a migration | motherduck-migrate-to-motherduck |
| Roll out self-serve analytics | motherduck-enable-self-serve-analytics |
| Deliver repeatable partner implementations | motherduck-partner-delivery |
Skills Overview
The catalog has three layers: utility skills cover exact MotherDuck mechanics, workflow skills cover multi-step work with MotherDuck-specific tradeoffs, and use-case skills orchestrate the lower layers for product surfaces, rollouts, migrations, and partner implementations.
| Skill | Layer | Use it when |
|---|
motherduck-connect | Utility | you need to choose the right connection path before writing code or SQL |
motherduck-explore | Utility | you need to inspect real databases, schemas, tables, columns, views, or shares |
motherduck-query | Utility | you need to write, validate, or optimize DuckDB SQL against MotherDuck |
motherduck-duckdb-sql | Utility | you need DuckDB SQL syntax or MotherDuck-specific SQL constraints quickly |
motherduck-rest-api | Utility | you need the REST API for service accounts, tokens, Duckling config, active accounts, or Dive embed sessions |
motherduck-load-data | Workflow | you need to ingest files, cloud objects, HTTP data, dataframes, or upstream systems into MotherDuck |
motherduck-model-data | Workflow | you need to design analytical schemas, tables, views, or transformation layers |
motherduck-share-data | Workflow | you need to publish, consume, or govern MotherDuck shares safely |
motherduck-create-dive | Workflow | you need to build, theme, preview, save, update, or embed a Dive |
motherduck-create-flight | Workflow | you need a scheduled or on-demand Python job (Flight) on MotherDuck for ingestion, transformation, or automation |
motherduck-design-dive | Workflow | you need a mobile-first, filter-ready Dive design that works in light and dark modes across customers |
motherduck-ducklake | Workflow | you need to decide whether DuckLake is appropriate and how to apply it safely |
motherduck-security-governance | Workflow | you need MotherDuck-specific guidance on security, access, governance, or residency |
motherduck-pricing-roi | Workflow | you need to frame workload cost drivers, pricing posture, or ROI tradeoffs |
motherduck-build-cfa-app | Use-case |
Repository Layout
| Path | Purpose |
|---|
skills/*/SKILL.md | Source skill content and frontmatter |
skills/*/references/ | Longer playbooks and implementation guidance |
skills/*/artifacts/ | Small runnable examples |
skills/catalog.json | Machine-readable skill index and source-doc map |
.claude-plugin/marketplace.json | Claude Code and Copilot-compatible marketplace manifest |
.codex-plugin/plugin.json | Codex plugin manifest |
.cursor-plugin/plugin.json | Cursor plugin manifest |
.cursor-plugin/marketplace.json | Cursor marketplace manifest |
gemini-extension.json | Gemini CLI extension manifest |
plugins/ | Packaged plugin copies for supported hosts |
Troubleshooting
The agent is not using MotherDuck skills
- Confirm the skill or plugin installed in the host you are using.
- Restart or reload the host so it re-indexes skills.
- Mention MotherDuck explicitly in the prompt once:
Use MotherDuck Skills....
Live workspace exploration does not work
- Confirm your MotherDuck MCP server or database connection is configured.
- Check that
MOTHERDUCK_TOKEN or your Postgres endpoint credentials are available to the agent process.
- Ask the agent to list its available MCP tools before starting live discovery.
The agent writes PostgreSQL-specific SQL
- Ask it to use
motherduck-duckdb-sql.
- Prefer fully qualified names like
"database"."schema"."table".
- Keep PostgreSQL-driver guidance limited to connection interoperability; query syntax should stay DuckDB SQL.
Maintainer Checks
Run these after changing skills, catalogs, manifests, or README examples:
uv run scripts/validate_skills.py
claude plugin validate ./.claude-plugin/marketplace.json
claude plugin validate ./plugins/motherduck-skills-claude
uv run scripts/check_claude_plugin_sync.py
uv run scripts/check_codex_plugin_sync.py
uv run --with duckdb --with pyyaml python tests/validate_snippets.py
To cut a release, see docs/release-process.md; never hand-edit version numbers, use scripts/bump_version.py.
Links
License
This project is licensed under the MIT License.
