motherduck-skills

MotherDuck Skills for AI Agents

MotherDuck Skills is the public skill catalog for agents building on MotherDuck.

It gives agents practical guidance for the most common work on the platform: connecting to MotherDuck, exploring live data, writing DuckDB SQL, modeling tables, building Dives, and shipping larger workflows like dashboards, migrations, and data pipelines.

The lower-level skills are intentionally not generic data-engineering tutorials. They exist to encode MotherDuck-specific defaults, gotchas, and opinionated workflow choices:

• when to prefer the PG endpoint versus a native DuckDB client
• when DuckDB SQL differs from PostgreSQL habits that would break on MotherDuck
• when native MotherDuck storage should stay the default over DuckLake
• how shares, Dives, read scaling, and customer-facing isolation actually work on MotherDuck

The repo is intentionally opinionated and agent-oriented:

• prefer live schema discovery over invented schemas
• keep utility and workflow SKILL.md files short and router-like
• keep deeper guidance in references/
• ship runnable examples inside the skill folders
• validate important artifacts against temporary real MotherDuck databases

Install

Choose one install path per agent.

• want the packaged experience: use the Claude Code, Codex, or Gemini CLI install
• want only a few skills or a cross-agent install: use the Skills CLI
• want full manual control: copy a skill directory directly

Avoid mixing packaged installs and raw skill installs for the same agent unless you are testing packaging behavior.

Choose an install path

Goal	Recommended path
Use the packaged Claude Code plugin from the repo marketplace	Claude Code plugin install
Use the packaged Codex plugin from the repo marketplace	Codex plugin install
Install the whole MotherDuck catalog in Gemini CLI	Gemini CLI extension install
Install one or two skills in Gemini CLI without the packaged extension	Gemini CLI skills install
Install the whole MotherDuck catalog quickly	Skills CLI
Vendor one skill directly into a repo or agent home without plugin tooling	Manual per-skill install

Claude Code plugin install

/plugin marketplace add motherduckdb/agent-skills
/plugin install motherduck-skills@motherduck-agent-skills

After install, restart Claude Code if it was already running. The skills load automatically and should trigger when relevant.

This plugin packages the whole MotherDuck catalog. You do not need to install each skill separately.

Codex plugin install

1. Clone or open this repo in Codex.
2. Restart Codex if it was already running for the repo.
3. Open /plugins.
4. Install MotherDuck Skills from the repo marketplace.

This path installs the packaged repo-local Codex plugin. After installation, the skills are available automatically when relevant.

Gemini CLI extension install

Install from GitHub:

gemini extensions install https://github.com/motherduckdb/agent-skills --consent

For local development from a checkout:

gemini extensions link .

After installation, restart Gemini CLI or reload your session. gemini extensions list and gemini skills list can help confirm the install.

Gemini CLI skills install

If you want only one specific MotherDuck skill in Gemini CLI, install it directly as an Agent Skill instead of installing the full extension:

gemini skills install https://github.com/motherduckdb/agent-skills.git --path skills/connect

You can also link the repo's skills locally:

gemini skills link skills

Skills CLI: install all skills

npx skills add motherduckdb/agent-skills

The skills package is interactive, so use the repo-level install and follow the prompts.

Best practices:

• the default install scope is project-local; use that when the skills should travel with the repo
• add -g when you want a personal cross-project install
• use manual per-skill install when you want only one skill from this repo without the full catalog

Manual per-skill install

Copy the whole skill directory, not just SKILL.md, so any bundled references/, scripts/, and artifacts/ remain available.

Project-local manual install:

mkdir -p .agents/skills
cp -R skills/connect .agents/skills/connect

Global manual install for a specific agent:

mkdir -p ~/.claude/skills ~/.codex/skills
cp -R skills/connect ~/.claude/skills/connect
cp -R skills/connect ~/.codex/skills/connect

For manual installs, prefer .agents/skills/<name> when the skill should be shared with the project. Use ~/.claude/skills/<name> or ~/.codex/skills/<name> only for personal cross-project defaults.

After installation