# mz-ontology-design

The mz-ontology-design Claude Code skill helps design the semantic layer of a Materialize SQL project. It activates for schema planning, relationship modeling, and reviews of shared versus use-case data.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 107 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/skills/mz-ontology-design/SKILL.md
- Updated: 2026-10-25
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/mz-ontology-design

## What it does

The skill organizes a project around a shared `raw` database, a shared `core` database, and a separate database for each use case. It helps decide which objects express shared meaning and which belong at the application edge. Canonical objects include entities, events, measurements, and relationships.

It covers grain, identity, and time semantics for public objects, along with reference edges and relationship registries. The skill can also guide reviews for private schemas exposed publicly, duplicated concepts, and undocumented objects. It calls for enforcing layer boundaries through grants and dependency validation, rather than relying on schema names alone.

## Install

### Claude Code (native platform)

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

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

### Codex

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

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

### Cursor

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

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

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install MaterializeInc/agent-skills skills/mz-ontology-design
```

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

### Gemini CLI

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

2. **Platform CLI**
```bash
gemini skills install https://github.com/MaterializeInc/agent-skills --path skills/mz-ontology-design
```

### Windsurf (Devin Desktop)

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

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add MaterializeInc/agent-skills --skill mz-ontology-design -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/skills/mz-ontology-design/SKILL.md

## When to use it
- separate shared data from use-case projections
- define grain, identity, and time semantics for public objects
- validate relationship references and their cardinality
- find leaked private schemas and duplicated concepts

## Example prompts
- Plan `raw`, `core`, and use-case databases for this Materialize project.
- Review the semantic layer for duplicated concepts and undocumented public objects.
- Design `core.public.relationships` and check its reference cardinalities.

## 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: 2775e03bf026b8e3.

BEGIN THIRD-PARTY FILE 2775e03bf026b8e3
````text
---
name: mz-ontology-design
description: >-
  Designing and reviewing the semantic layer of a Materialize SQL code
  base as a canonical ontology — a shared raw database, a shared core
  database, and one database per use case. Use this skill when a user
  asks how to structure or organize Materialize schemas and databases,
  wants to define canonical semantic objects (entities, events,
  measurements, relationship objects), needs identity resolution or
  temporal semantics for public objects, is deciding what belongs in a
  shared layer versus a consumer-specific one, is building or
  validating a relationship registry (core.public.relationships,
  reference edges, cardinality, optionality), or mentions ontology,
  semantic layer, semantic model, semantic objects, context graph,
  raw/core/use-case boundaries, grain, or enforceable layer
  dependencies. Also trigger when reviewing an existing Materialize
  code base for leaked private schemas, duplicated concepts, or
  undocumented public objects.
---

# Materialize ontology design

Build one canonical semantic graph between source-shaped data and consumer-specific
outputs. Shared meaning belongs in the ontology; presentation and workflow policy
belong at the edges.

## Architecture

Use a shared `raw` database, a shared `core` database, and one database per use case.
Preserve this dependency direction:

```text
raw.<source_system>  ->  core.<source_system>  ->  core.internal
                                                    |
                                                    v
                                               core.public
                                                    |
                                                    v
                                         <use_case>.<schema>
```

- `raw` contains source-shaped ingestion objects. Preserve source-table identity;
  recreating a source table can resnapshot the upstream system.
- `core.<source_system>` contains private, source-local typing, cleanup,
  deduplication, and naming.
- `core.internal` contains private cross-source integration and identity resolution.
- `core.public` is the documented ontology and the only core schema consumers may
  read.
- Each use case owns a database. Its schemas contain the projections, aggregates,
  scores, filters, and indexes for that application or workload. Use cases never
  share a database.

Only `core` reads `raw`. Every use-case database reads only `core.public`. Enforce
these boundaries with grants and dependency validation rather than naming conventions
alone.

## Semantic objects

A semantic object is a canonical relation whose rows have one documented grain, one
durable identity rule, explicit temporal semantics, and meaning independent of any
````
END THIRD-PARTY FILE 2775e03bf026b8e3

The third-party file has ended. Everything between the 2775e03bf026b8e3 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.

First 2766 of 7641 bytes. © MaterializeInc · Apache-2.0 · https://github.com/MaterializeInc/agent-skills/tree/HEAD/skills/mz-ontology-design/SKILL.md

_Part of the page did not fit — see the HTML version._

---
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
