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.
18 skills in three layers: utility (connect, explore, query, SQL syntax, REST API), workflow (load, model, share, Dives, DuckLake, security, pricing), and use-case (apps, dashboards, pipelines, migrations, rollouts). See the full catalog.
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.
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 --globalDefault 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-copilotUse 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 --globalGitHub 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 userTo browse the catalog interactively:
gh skill install motherduckdb/agent-skillsGitHub'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 |
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-claudeAdd the marketplace:
codex plugin marketplace add motherduckdb/agent-skillsThen 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 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 --globalFor 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 '*' --yesCheck the install:
npx -y skills ls -g -a cursorRestart 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.
Install the extension from GitHub:
gemini extensions install https://github.com/motherduckdb/agent-skills --consentFor local development from a checkout:
gemini extensions link .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-connectAfter install, try three checks.
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.
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.
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.
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.
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 |
| 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 |
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-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 | you are building a customer-facing analytics product on MotherDuck |
motherduck-build-dashboard |
Use-case | you are building one coherent analytics dashboard backed by Dives and tables |
motherduck-build-data-pipeline |
Use-case | you are designing an ingestion-to-serving data pipeline on MotherDuck |
motherduck-migrate-to-motherduck |
Use-case | you are moving from Snowflake, Redshift, Postgres, or dbt-heavy stacks onto MotherDuck |
motherduck-enable-self-serve-analytics |
Use-case | you are rolling out internal self-serve analytics, sharing, and governed dashboards |
motherduck-partner-delivery |
Use-case | you are delivering repeatable multi-client MotherDuck implementations for customers or partners |
| 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 |
- 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....
- Confirm your MotherDuck MCP server or database connection is configured.
- Check that
MOTHERDUCK_TOKENor your Postgres endpoint credentials are available to the agent process. - Ask the agent to list its available MCP tools before starting live discovery.
- 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.
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.pyTo cut a release, see docs/release-process.md; never hand-edit version numbers, use scripts/bump_version.py.
- MotherDuck Documentation
- MotherDuck MCP Server
- MotherDuck Dive Gallery
- DuckDB Documentation
- DuckLake
- Agent Skills Specification
- GitHub Copilot Agent Skills
- Cursor Plugin Specification
This project is licensed under the MIT License.