mz-sql-navigation — Claude Code skill: SQL navigation, install
The mz-sql-navigation skill uses the mz-deploy LSP to inspect Materialize SQL. Use it when object references cross files in an mz-deploy project.
Apache-2.0 131 installs ★ 3 updated 2026-10-25
npx skills add MaterializeInc/agent-skills --skill mz-sql-navigation -a claude-codeWhat mz-sql-navigation does
The skill tells the agent to use the mz-deploy language server instead of text search. It can jump to definitions for views, tables, sources, and indexes, inspect columns and types through hover, and list symbols from one file or the whole workspace.
Before an edit, the agent can trace objects that depend on the target. A Materialize view can constrain downstream definitions, so a change that parses alone may still break them. Syntax diagnostics appear after each edit. mz-deploy must be on PATH, and the server’s project directory must be the folder containing project.toml.
What it helps with
- locate a Materialize object across SQL files
- inspect columns and types without opening a definition
- list objects declared by one SQL file
- find an object by name across the workspace
- trace dependents before changing a view
Example prompts for the agent
- Use the LSP to find the definitions referenced by this
.sqlfile instead of searching text. - Show the columns and types for the object used by this query through hover information.
- Before editing this view, find its downstream dependents and check the syntax diagnostics after the change.
How to install mz-sql-navigation
1Skills CLI (Vercel)
npx skills add MaterializeInc/agent-skills --skill mz-sql-navigation -a claude-code2Manually: put the files in place
~/.claude/skills/mz-sql-navigation/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/mz-sql-navigation/
1Skills CLI (Vercel)
npx skills add MaterializeInc/agent-skills --skill mz-sql-navigation -a codex2Manually: put the files in place
.agents/skills/mz-sql-navigation/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add MaterializeInc/agent-skills --skill mz-sql-navigation -a cursor2Manually: put the files in place
.cursor/skills/mz-sql-navigation/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install MaterializeInc/agent-skills plugins/mz-sql-lsp/skills/mz-sql-navigation2Manually: put the files in place
.github/skills/mz-sql-navigation/SKILL.md1Skills CLI (Vercel)
npx skills add MaterializeInc/agent-skills --skill mz-sql-navigation -a gemini-cli2Platform CLI
gemini skills install https://github.com/MaterializeInc/agent-skills --path plugins/mz-sql-lsp/skills/mz-sql-navigationManually: put the files in place
.devin/skills/mz-sql-navigation/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add MaterializeInc/agent-skills --skill mz-sql-navigation -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about mz-sql-navigation
How do I install mz-sql-navigation in Claude Code?
Run npx skills add MaterializeInc/agent-skills --skill mz-sql-navigation -a claude-code, then check ~/.claude/skills/mz-sql-navigation/SKILL.md.
What does mz-sql-navigation do?
It uses the mz-deploy LSP to jump to object definitions, inspect columns and types, and find symbols in a SQL file or workspace.
What does the skill require?
mz-deploy must be available on PATH. The language server’s project directory must point to the folder with project.toml, or navigation requests can return empty results.
Source text
SKILL.md · Apache-2.0
--- name: mz-sql-navigation description: Use when reading or editing .sql files in an mz-deploy project (a directory with project.toml) — resolve object references, columns, and types with the LSP tool instead of grepping. Covers go-to-definition, hover, and document/workspace symbols for Materialize SQL. --- # Navigating Materialize SQL The `mz-deploy` language server answers questions about an mz-deploy project's object graph. Use the LSP tool for these instead of text search — grep finds strings that look like an object name, the language server finds the object. ## What to use it for - **Go to definition** — resolve where a referenced view, table, source, or index is defined, including across schemas. - **Hover** — inspect an object's columns and their types without opening its definition. - **Document symbols** — list the objects a single `.sql` file defines. - **Workspace symbols** — locate an object by name when you don't know its file. Before changing an object, use these to find what depends on it. In Materialize a view's definition constrains everything downstream of it, so an edit that type-checks in isolation can still break dependents. ## Diagnostics Parse errors surface automatically after each edit. Treat them as authoritative for syntax; they come from the same parser `mz-deploy` uses to build the project. ## Requirements `mz-deploy` must be on `PATH` (`which mz-deploy`). If every navigation request comes back empty while the server looks healthy, the plugin's **mz-deploy project directory** setting is pointing somewhere other than the directory holding `project.toml`. The server takes that directory as its project root, and a project nested in a subdirectory needs the setting to name that subdirectory. Report this rather than falling back to grep — a stale setting is worth fixing once.
© MaterializeInc · Apache-2.0 · MaterializeInc/agent-skills