Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add MaterializeInc/agent-skills --skill mz-sql-navigation -a claude-code
Open on GitHub

What 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 .sql file 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-code

2Manually: put the files in place

~/.claude/skills/mz-sql-navigation/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/mz-sql-navigation/

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

Similar skills

All skills for Data and databases →

From the same set4

Project sponsors

Companies that keep this analytics open