# mz-sql-navigation

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.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 131 installs · ★ 3 repo stars
- Author: MaterializeInc
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/MaterializeInc/agent-skills/tree/HEAD/plugins/mz-sql-lsp/skills/mz-sql-navigation/SKILL.md
- Updated: 2026-10-25
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/mz-sql-navigation

## What it 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`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add MaterializeInc/agent-skills --skill mz-sql-navigation -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/mz-sql-navigation/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/mz-sql-navigation/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add MaterializeInc/agent-skills --skill mz-sql-navigation -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/mz-sql-navigation/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add MaterializeInc/agent-skills --skill mz-sql-navigation -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/mz-sql-navigation/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install MaterializeInc/agent-skills plugins/mz-sql-lsp/skills/mz-sql-navigation
```

2. **Manually: put the files in place**
- File: `.github/skills/mz-sql-navigation/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add MaterializeInc/agent-skills --skill mz-sql-navigation -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/MaterializeInc/agent-skills --path plugins/mz-sql-lsp/skills/mz-sql-navigation
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/mz-sql-navigation/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add MaterializeInc/agent-skills --skill mz-sql-navigation -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/MaterializeInc/agent-skills/tree/HEAD/plugins/mz-sql-lsp/skills/mz-sql-navigation/SKILL.md

## When to use it
- 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
- 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.

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 35b09b45a997c538.

BEGIN THIRD-PARTY FILE 35b09b45a997c538
```text
---
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.
```
END THIRD-PARTY FILE 35b09b45a997c538

The third-party file has ended. Everything between the 35b09b45a997c538 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

© MaterializeInc · Apache-2.0 · https://github.com/MaterializeInc/agent-skills/tree/HEAD/plugins/mz-sql-lsp/skills/mz-sql-navigation/SKILL.md

## Similar
- [chdb-sql](https://affpapa.org/en/nevibecode/skills/chdb-sql.md) — skill · 10300 installs
- [sql-jdbc-access-design](https://affpapa.org/en/nevibecode/skills/sql-jdbc-access-design.md) — skill · 10100 installs
- [sql-optimization-patterns](https://affpapa.org/en/nevibecode/skills/sql-optimization-patterns.md) — skill · 19717 installs
- [sql-optimization](https://affpapa.org/en/nevibecode/skills/sql-optimization.md) — skill · 15701 installs
- [sql-code-review](https://affpapa.org/en/nevibecode/skills/sql-code-review.md) — skill · 14060 installs
- [sql-query-optimizer](https://affpapa.org/en/nevibecode/skills/sql-query-optimizer.md) — skill · 1 install

From the same set: [materializeinc/agent-skills](https://affpapa.org/en/nevibecode/by/materializeinc/agent-skills.md) — 4 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
