# zenstack-plugin-dev

The zenstack-plugin-dev Claude Code skill guides development of ZenStack V3 plugins. It applies to ZModel extensions, CLI code generation, and ORM client plugins.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 521 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-plugin-dev/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-plugin-dev

## What it does

The skill covers ZenStack V3 plugin work across the schema, CLI, and ORM layers. It explains custom ZModel attributes and functions, generators for `zen generate`, and runtime hooks for ORM queries and entity mutations.

It also describes adding client methods, accepting extra query arguments, and computing virtual result fields. A CLI plugin must be an ESM module with a default `CliPlugin` export; install the SDK with `npm install -D @zenstackhq/sdk`. Runtime plugin types come from `@zenstackhq/orm`.

ZenStack V3 plugins are a preview feature and may change in later releases. Mutation hooks miss changes caused by database cascades, and loading rows for bulk mutations can be expensive.

## Install

### Claude Code (native platform)

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

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

### Codex

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

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

### Cursor

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

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

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install zenstackhq/skills skills/zenstack-plugin-dev
```

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

### Gemini CLI

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

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

### Windsurf (Devin Desktop)

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

### OpenCode

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

## When to use it
- add custom attributes and functions to ZModel
- generate artifacts from a schema with `zen generate`
- intercept ORM calls or transform SQL
- extend the client with custom methods and properties
- compute virtual fields from query results

## Example prompts
- Add an `onQuery` hook to a ZenStack runtime plugin to intercept ORM operations.
- Create a CLI plugin for `zen generate` that produces a report from ZModel models.
- Extend the ZenStack client with a custom method and a computed result field.

## 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: ba8ed56126bf6ae6.

BEGIN THIRD-PARTY FILE ba8ed56126bf6ae6
````text
---
name: zenstack-plugin-dev
description: Develop ZenStack V3 plugins. Use when building or declaring a plugin — custom ZModel attributes/functions, CLI code generators (CliPlugin with a generate callback for `zen generate`), or runtime plugins installed via $use/definePlugin (onQuery, onKyselyQuery, onEntityMutation hooks, extending the client, custom query args, computed result fields).
---

# ZenStack V3 — Plugin Development

> Plugins are a **preview** feature and may change in future releases.

A ZenStack plugin can extend the toolkit at **three levels**, independently or together:

1. **Schema (ZModel)** — contribute custom attributes (e.g. `@password`) and functions to the
   schema language.
2. **CLI (code generation)** — participate in `zen generate` to emit artifacts from the schema.
3. **Runtime (ORM)** — install on the client to intercept queries, hook CRUD lifecycle events,
   transform SQL, add custom methods, or compute fields.

ZenStack's `plugin` replaces Prisma's `generator`. To declare/consume plugins in a schema see
`zenstack-schema-modeling`; this skill is about *authoring* them.

Packages: `@zenstackhq/orm` (runtime plugin types), `@zenstackhq/sdk` (CLI plugin types + ZModel
AST). Install the SDK as a dev dependency: `npm install -D @zenstackhq/sdk`.

## Declaring a plugin in ZModel

```zmodel
plugin myPlugin {
    provider = './my-plugin'   // local .ts/.js/.mts/.mjs file, a folder with an index, or an npm package
    output   = './generated'   // arbitrary key=value options, readable by the plugin
}
```

`provider` resolution order: local file path → folder with an index → npm package. CLI plugins must
be **ESM**; TypeScript providers are loaded via [jiti](https://github.com/unjs/jiti). The built-in
`@core/typescript` plugin runs automatically; `@core/prisma` emits a Prisma schema.

## Runtime plugins

A runtime plugin is an object implementing `RuntimePlugin` from `@zenstackhq/orm`. Define it three
ways; `definePlugin` gives the best type inference:

```ts
import { definePlugin, type RuntimePlugin } from '@zenstackhq/orm';

// plain object / definePlugin (recommended)
const plugin = definePlugin({ id: 'my-plugin', /* hooks… */ });

// or a class
class MyPlugin implements RuntimePlugin<typeof schema> {
    id = 'my-plugin';
    /* hooks… */
}
```

Install on the client (immutable — returns a new client, original unchanged); remove with
`$unuse(id)` / `$unuseAll()`. You can also pass `plugins: [...]` to the `ZenStackClient` constructor.

```ts
const db = new ZenStackClient(schema, { dialect });
const withPlugin = db.$use(plugin);              // new client
const plain = withPlugin.$unuse('my-plugin');    // remove by id
// or: new ZenStackClient(schema, { dialect, plugins: [plugin] });
```
````
END THIRD-PARTY FILE ba8ed56126bf6ae6

The third-party file has ended. Everything between the ba8ed56126bf6ae6 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 2783 of 9895 bytes. © zenstackhq · MIT · https://github.com/zenstackhq/skills/tree/HEAD/skills/zenstack-plugin-dev/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
