# zenstack-schema-modeling

The zenstack-schema-modeling Claude Code skill helps write and revise ZModel schemas for ZenStack V3. It activates for work on models, fields, relations, enums, and typed JSON fields.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 470 installs · ★ 3 repo stars
- Author: zenstackhq
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/zenstackhq/skills/tree/HEAD/skills/zenstack-schema-modeling/SKILL.md
- Updated: 2026-10-28
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/zenstack-schema-modeling

## What it does

The skill guides agents through ZModel schema design, from model and field declarations to attributes and relations. It covers one-to-one, one-to-many, many-to-many, and self-relations, along with enums, custom types, and mixins.

Its scope also includes polymorphism with `@@delegate`, computed fields, and typed JSON fields. The default schema path is `zenstack/schema.zmodel`. After editing, `zen check` validates the schema; `zen generate` validates it while generating the database client. Both commands require the ZenStack CLI.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add zenstackhq/skills --skill zenstack-schema-modeling -a claude-code
```

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

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add zenstackhq/skills --skill zenstack-schema-modeling -a codex
```

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

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add zenstackhq/skills --skill zenstack-schema-modeling -a cursor
```

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

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install zenstackhq/skills skills/zenstack-schema-modeling
```

2. **Manually: put the files in place**
- File: `.github/skills/zenstack-schema-modeling/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add zenstackhq/skills --skill zenstack-schema-modeling -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/zenstackhq/skills --path skills/zenstack-schema-modeling
```

### Windsurf (Devin Desktop)

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

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add zenstackhq/skills --skill zenstack-schema-modeling -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/zenstackhq/skills/tree/HEAD/skills/zenstack-schema-modeling/SKILL.md

## When to use it
- define models and field types in ZModel
- connect models with foreign-key relations
- add enums and reusable field mixins
- represent polymorphic models with `@@delegate`
- validate a schema and regenerate the database client

## Example prompts
- Add User and Post models to `zenstack/schema.zmodel` with a one-to-many relation.
- Define a typed JSON field and a mixin for shared model fields.
- Validate the edited schema, then regenerate the database client.

## Source text · SKILL.md · MIT

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: 0ae3d9f80c973739.

BEGIN THIRD-PARTY FILE 0ae3d9f80c973739
````text
---
name: zenstack-schema-modeling
description: Author ZModel (.zmodel) data schemas for ZenStack V3. Use when defining models, fields, field/model attributes, relations (1-1, 1-many, many-many, self), enums, custom types & mixins, polymorphic models (@@delegate), strongly-typed JSON fields, or computed fields.
---

# ZenStack — Schema Modeling (ZModel)

ZModel is ZenStack's schema language — a superset of Prisma's schema. The schema lives at
`zenstack/schema.zmodel` by default. For access policies/validation use `zenstack-access-control`;
for queries use `zenstack-querying`.

After editing the schema:

```bash
zen check      # only validate the schema for syntax/semantic errors (use --schema <file> for a non-default path)
zen generate   # regenerate the database client — also validates the schema as it compiles
```

Run `zen check` when you just want to confirm the schema is valid; run `zen generate` when you want
to regenerate the client (the normal step after a schema change).

Strings accept both single and double quotes. **Every valid Prisma schema is valid ZModel**, so
existing Prisma knowledge transfers directly — the sections below cover both the basics and the
additions ZModel layers on top.

## Datasource

Exactly one `datasource` block per schema. The ORM runtime doesn't use `url` (the driver carries
the connection); the migration engine does.

```zmodel
datasource db {
    provider = 'postgresql'        // 'postgresql' | 'mysql' | 'sqlite'
    url      = env('DATABASE_URL') // or 'file:./dev.db' for SQLite
}
```

> ZModel has **no `generator` block**. Code generation is driven by `zen generate`; optional behavior
> is configured with `plugin` blocks (e.g. `plugin policy`, `plugin prisma`).

## Models & fields

```zmodel
model User {
    id        Int      @id @default(autoincrement())
    email     String   @unique
    name      String?              // optional
    role      Role     @default(USER)
    tags      String[]             // list
    createdAt DateTime @default(now())
    updatedAt DateTime @updatedAt
}
```

**Scalar types**: `String`, `Boolean`, `Int`, `BigInt`, `Float`, `Decimal`, `DateTime`, `Json`,
`Bytes`, `Unsupported("...")`.

**Modifiers**: `?` optional, `[]` list. A field cannot be both optional *and* a list.

### Field attributes (`@`)

`@id`, `@unique`, `@default(...)`, `@updatedAt`, `@map('col')`, `@relation(...)`, `@db.*` (native
type, e.g. `@db.VarChar(64)`), `@json` (typed-JSON field), `@computed` (virtual field).

### Model attributes (`@@`)

`@@id([a, b])` (composite PK), `@@unique([a, b])`, `@@index([a, b])`, `@@map('table')`,
`@@delegate(field)` (polymorphism), plus `@@allow` / `@@deny` / `@@validate` (see
`zenstack-access-control`).

```zmodel
model City {
    country String
    name    String
    @@id([country, name])     // composite primary key
    @@map('cities')
}
```
````
END THIRD-PARTY FILE 0ae3d9f80c973739

The third-party file has ended. Everything between the 0ae3d9f80c973739 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 2875 of 9296 bytes. © zenstackhq · MIT · https://github.com/zenstackhq/skills/tree/HEAD/skills/zenstack-schema-modeling/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
