Agent Skills

View as Markdown

Coding agents like Claude Code, Codex, Cursor, and others can work with Materialize using the open-source Materialize agent skills. These skills follow the Agent Skills Open Standard and work with any coding agent that supports the standard. Once installed, these skills give your coding agent access to Materialize documentation and reference material so it can provide more accurate assistance when writing queries, setting up sources, creating materialized views, and more.

Skills

Skill	Description
`mcp-developer-analysis`	Use for operational introspection and troubleshooting via the `materialize-developer` server. Covers exact catalog schemas, diagnostic workflows, remediation runbooks, and guardrails for known pitfalls (cluster-scoped queries, uint8 ID mismatches, etc.). Examples: “why is my materialized view stale?”, “what can I optimize to save costs?”, “is my source healthy?”
`materialize-docs`	Use for authoring view definitions, learning concepts, and looking up patterns; useful with either MCP server. Covers comprehensive Materialize documentation, including SQL syntax, idiomatic patterns, data ingestion, concepts, and best practices (400+ reference files). Examples: “show me how to deduplicate a stream”, “what’s the idiomatic top-K pattern?”, “how do I create a Kafka source?”
`materialize-dbt`	Use for managing Materialize pipelines with dbt. Covers dbt-materialize adapter usage: materializations, profile configuration, index creation, blue/green deployments, and testing. Examples: “write a dbt model for a materialized view”, “how do I do a blue/green deployment with dbt?”
`materialize-terraform-provider`	Use for managing Materialize resources declaratively with Terraform. Covers provider configuration for Cloud and self-managed, navigation into the provider’s auto-generated resource reference, cross-resource patterns, import workflows, and gotchas. Examples: “create a Kafka source with Terraform”, “import my existing clusters into Terraform state”, “set up RBAC grants in Terraform”
`materialize-terraform-self-managed`	Use for deploying or operating self-managed Materialize infrastructure with Terraform. Covers module layout and variables for deploying on AWS, Azure, and GCP: networking, Kubernetes, backend URL formats, instance sizing, upgrades, and gotchas. Examples: “deploy Materialize on EKS”, “what instance types should Materialize nodes use?”, “upgrade my self-managed Materialize”
`mz-deploy`	Use for managing a declarative SQL project and deploying changes to Materialize safely. Covers project layout, the compile → test → apply → stage → wait → promote lifecycle, hash-based change detection, atomic `ALTER ... SWAP` promotion, conflict detection, stable API schemas and replacement materialized views, offline type checking with `types.lock`, per-profile suffixes, variables, and file overrides, and the `EXECUTE UNIT TEST` syntax. Examples: “how do I deploy my sql changes safely?”, “what does mz-deploy stage do?”, “why did my promote fail with a conflict?”

Prerequisites

Node.js (v16 or later) must be installed.

Installation

Install the Materialize agent skills with a single command:

npx skills add MaterializeInc/agent-skills

Once installed, you can update installed skills by running npx skills update.

Claude Code plugins

The same repository also serves as a Claude Code plugin marketplace named materialize. Its mz-sql-lsp plugin registers the mz-deploy language server for .sql files, so Claude Code navigates your project instead of grepping it. See AI agent setup for installation and configuration.

Reduce permission prompts (Claude Code)

Claude Code prompts before reading files outside your project. Since globally installed skills live under ~/.claude/skills/, if you installed the materialize-docs skill globally, Claude Code may ask to approve reads each time the skill opens a new documentation subdirectory.

To stop these prompts, grant read access to the materialize-docs skill in ~/.claude/settings.json:

{
  "permissions": {
    "additionalDirectories": ["~/.claude/skills/materialize-docs"]
  }
}

This grants access to just that one skill’s directory. If you have multiple skills installed and want to cover them all at once, you can broaden the path to ~/.claude/skills, though scoping to a single skill is the safer default.

Claude Code’s auto permission mode also removes the prompts, but applies to all tools rather than just this directory.