GLM-Tools-Skills-Agents/skills/zai-tooling-reference/SKILL.md

name, description, priority, autoTrigger, triggers

name	description	priority	autoTrigger	triggers
zai-tooling-reference	Complete z.ai tooling reference - Next.js 15/16, React 19, shadcn/ui, Prisma, WebSocket. AUTO-TRIGGERS when: Next.js setup, shadcn/ui components, Prisma schema, SQLite, WebSocket/Socket.io, Zustand state, TanStack Query, NextAuth, Tailwind CSS 4, Bun, full-stack development.	100	true	Next.js nextjs shadcn shadcn/ui Prisma SQLite WebSocket socket.io real-time Zustand TanStack Query react-query NextAuth authentication Tailwind Tailwind CSS 4 Bun React 19 full-stack frontend component UI component database schema

Z.AI Tooling Reference

Complete technical reference for the z.ai tooling codebase - a production-ready Next.js 15 application with AI capabilities.

Codebase Location: ~/reference-codebases/z-ai-tooling/

---

Tech Stack

Category	Technology	Version
Framework	Next.js	16.1.1
React	React	19.0.0
Language	TypeScript	5.x
Styling	Tailwind CSS	4.x
UI Components	shadcn/ui (Radix)	Latest
Database	Prisma + SQLite	6.11.1
State	Zustand	5.0.6
Data Fetching	TanStack Query	5.82.0
AI SDK	z-ai-web-dev-sdk	0.0.16
Auth	NextAuth	4.24.11
Package Manager	Bun	1.3.4+

---

Project Structure

z-ai-tooling/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── api/route.ts        # API endpoints
│   │   ├── page.tsx            # Main page
│   │   ├── layout.tsx          # Root layout
│   │   └── globals.css         # Global styles
│   ├── components/
│   │   └── ui/                 # shadcn/ui components (50+)
│   ├── hooks/
│   │   ├── use-mobile.ts       # Mobile detection
│   │   └── use-toast.ts        # Toast notifications
│   └── lib/
│       ├── db.ts               # Prisma client singleton
│       └── utils.ts            # Utility functions (cn, etc.)
├── prisma/
│   └── schema.prisma           # Database schema
├── examples/
│   └── websocket/              # WebSocket implementation
├── db/
│   └── custom.db               # SQLite database
├── download/                   # Output directory for generated files
└── .zscripts/                  # Build and start scripts

---

Database Patterns

Prisma Schema

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "sqlite"
  url      = env("DATABASE_URL")
}

model User {
  id        String   @id @default(cuid())
  email     String   @unique
  name      String?
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

model Post {
  id        String   @id @default(cuid())
  title     String
  content   String?
  published Boolean  @default(false)
  authorId  String
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

Database Client Singleton

// src/lib/db.ts
import { PrismaClient } from '@prisma/client'

const globalForPrisma = globalThis as unknown as {
  prisma: PrismaClient | undefined
}

export const db =
  globalForPrisma.prisma ??
  new PrismaClient({
    log: ['query'],
  })

if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = db

Database Commands

bun run db:push      # Push schema changes
bun run db:generate  # Generate Prisma client
bun run db:migrate   # Create migration
bun run db:reset     # Reset database

---

WebSocket Integration

Server (Socket.io)

// examples/websocket/server.ts
import { createServer } from 'http'
import { Server } from 'socket.io'

const httpServer = createServer()
const io = new Server(httpServer, {
  path: '/',
  cors: { origin: "*", methods: ["GET", "POST"] },
  pingTimeout: 60000,
  pingInterval: 25000,
})

interface User { id: string; username: string }
interface Message {
  id: string
  username: string
  content: string
  timestamp: Date
  type: 'user' | 'system'
}

const users = new Map<string, User>()

io.on('connection', (socket) => {
  socket.on('join', (data: { username: string }) => {
    const user: User = { id: socket.id, username: data.username }
    users.set(socket.id, user)
    io.emit('user-joined', { user, message: createSystemMessage(`${data.username} joined`) })
    socket.emit('users-list', { users: Array.from(users.values()) })
  })

  socket.on('message', (data: { content: string; username: string }) => {
    const message = createUserMessage(data.username, data.content)
    io.emit('message', message)
  })

  socket.on('disconnect', () => {
    const user = users.get(socket.id)
    if (user) {
      users.delete(socket.id)
      io.emit('user-left', { user, message: createSystemMessage(`${user.username} left`) })
    }
  })
})

httpServer.listen(3003)

Client (React)

// examples/websocket/frontend.tsx
'use client';

import { useEffect, useState } from 'react';
import { io } from 'socket.io-client';

export default function SocketDemo() {
  const [socket, setSocket] = useState<any>(null);
  const [isConnected, setIsConnected] = useState(false);

  useEffect(() => {
    // Use XTransformPort instead of direct port
    const socketInstance = io('/?XTransformPort=3003', {
      transports: ['websocket', 'polling'],
      reconnection: true,
      reconnectionAttempts: 5,
      reconnectionDelay: 1000,
    });

    setSocket(socketInstance);

    socketInstance.on('connect', () => setIsConnected(true));
    socketInstance.on('disconnect', () => setIsConnected(false));
    socketInstance.on('message', (msg) => { /* handle message */ });

    return () => socketInstance.disconnect();
  }, []);

  return ( /* JSX */ );
}

---

Available UI Components (shadcn/ui)

50+ components available in src/components/ui/:

Component	File	Purpose
Button	button.tsx	Primary actions
Input	input.tsx	Text input
Card	card.tsx	Container
Dialog	dialog.tsx	Modal
Sheet	sheet.tsx	Side panel
Toast	toast.tsx	Notifications
Select	select.tsx	Dropdown
Table	table.tsx	Data tables
Tabs	tabs.tsx	Tab navigation
Form	form.tsx	Form handling
Chart	chart.tsx	Charts (Recharts)
Calendar	calendar.tsx	Date picker
Command	command.tsx	Command palette
Drawer	drawer.tsx	Mobile drawer
Sidebar	sidebar.tsx	Navigation sidebar
Carousel	carousel.tsx	Image carousel
Accordion	accordion.tsx	Collapsible content
Avatar	avatar.tsx	User avatars
Badge	badge.tsx	Status indicators
Checkbox	checkbox.tsx	Boolean input
Slider	slider.tsx	Range input
Switch	switch.tsx	Toggle
Tooltip	tooltip.tsx	Hover info
Progress	progress.tsx	Loading indicator
Skeleton	skeleton.tsx	Loading placeholder
ScrollArea	scroll-area.tsx	Scrollable container

---

Dependencies Overview

Core Dependencies

{
  "next": "^16.1.1",
  "react": "^19.0.0",
  "react-dom": "^19.0.0",
  "z-ai-web-dev-sdk": "^0.0.16",
  "prisma": "^6.11.1",
  "@prisma/client": "^6.11.1"
}

UI Dependencies

{
  "@radix-ui/react-*": "latest",  // All Radix primitives
  "lucide-react": "^0.525.0",     // Icons
  "framer-motion": "^12.23.2",    // Animations
  "class-variance-authority": "^0.7.1",
  "clsx": "^2.1.1",
  "tailwind-merge": "^3.3.1"
}

State & Data

{
  "zustand": "^5.0.6",
  "@tanstack/react-query": "^5.82.0",
  "@tanstack/react-table": "^8.21.3",
  "zod": "^4.0.2",
  "react-hook-form": "^7.60.0"
}

Special Features

{
  "next-auth": "^4.24.11",       // Authentication
  "next-intl": "^4.3.4",         // Internationalization
  "next-themes": "^0.4.6",       // Dark mode
  "recharts": "^2.15.4",         // Charts
  "@mdxeditor/editor": "^3.39.1", // MDX editing
  "sharp": "^0.34.3"             // Image optimization
}

---

Scripts

# Development
bun run dev       # Start on port 3000 with logging

# Production
bun run build     # Build with standalone output
bun run start     # Run production server

# Database
bun run db:push      # Push schema
bun run db:generate  # Generate client
bun run db:migrate   # Create migration
bun run db:reset     # Reset database

# Quality
bun run lint      # ESLint check

---

File Output Pattern

Generated files are saved to:

/home/z/my-project/download/

Or in this reference codebase:

~/reference-codebases/z-ai-tooling/download/

---

Key Patterns

1. Prisma Singleton

Prevents multiple PrismaClient instances in development.

2. WebSocket Port Transformation

Use XTransformPort query param instead of direct port numbers.

3. Component Structure

All UI components use:

• cva (class-variance-authority) for variants
• cn utility for class merging
• Radix primitives for accessibility

4. API Routes

// src/app/api/route.ts
import { NextResponse } from "next/server";

export async function GET() {
  return NextResponse.json({ message: "Hello, world!" });
}

5. Backend-Only SDK Usage

z-ai-web-dev-sdk MUST only be used in:

• API routes (src/app/api/)
• Server components
• Server actions

---

When to Use This Reference

1. Building Next.js 15 apps: Project structure and patterns
2. shadcn/ui implementation: Component usage examples
3. WebSocket integration: Real-time features
4. Prisma + SQLite: Database patterns
5. AI SDK integration: z-ai-web-dev-sdk patterns
6. Production deployment: Build and start scripts

---

Quick Commands

# Navigate to reference codebase
cd ~/reference-codebases/z-ai-tooling

# Install dependencies
bun install

# Start development
bun run dev

# Check components
ls src/components/ui/

---

Reference codebase copied from: C:\Users\admin\Documents\trae_projects\Skills and Agents\z.ai tooling