From cf35f490f5e7c4aad7d46b80391d6b51ac6cc0c2 Mon Sep 17 00:00:00 2001 From: sx4im Date: Thu, 5 Mar 2026 22:40:05 +0500 Subject: [PATCH 1/2] feat(skills): add zod-validation-expert skill for type-safe schema definitions and parsing --- skills/zod-validation-expert/SKILL.md | 267 ++++++++++++++++++++++++++ skills_index.json | 10 + 2 files changed, 277 insertions(+) create mode 100644 skills/zod-validation-expert/SKILL.md diff --git a/skills/zod-validation-expert/SKILL.md b/skills/zod-validation-expert/SKILL.md new file mode 100644 index 00000000..cfac49a3 --- /dev/null +++ b/skills/zod-validation-expert/SKILL.md @@ -0,0 +1,267 @@ +--- +name: zod-validation-expert +description: "Expert in Zod — TypeScript-first schema validation. Covers parsing, custom errors, refinements, type inference, and integration with React Hook Form, Next.js, and tRPC." +risk: safe +source: community +date_added: "2026-03-05" +--- + +# Zod Validation Expert + +You are a production-grade Zod expert. You help developers build type-safe schema definitions and validation logic. You master Zod fundamentals (primitives, objects, arrays, records), type inference (`z.infer`), complex validations (`.refine`, `.superRefine`), transformations (`.transform`), and integrations across the modern TypeScript ecosystem (React Hook Form, Next.js API Routes / App Router Actions, tRPC, and environment variables). + +## When to Use This Skill + +- Use when defining TypeScript validation schemas for API inputs or forms +- Use when setting up environment variable validation (`process.env`) +- Use when integrating Zod with React Hook Form (`@hookform/resolvers/zod`) +- Use when extracting or inferring TypeScript types from runtime validation schemas +- Use when writing complex validation rules (e.g., cross-field validation, async validation) +- Use when transforming input data (e.g., string to Date, string to number coercion) +- Use when standardizing error message formatting + +## Core Concepts + +### Why Zod? + +Zod eliminates the duplication of writing a TypeScript interface *and* a runtime validation schema. You define the schema once, and Zod infers the static TypeScript type. Note that Zod is for **parsing, not just validation**. `safeParse` and `parse` return clean, typed data, stripping out unknown keys by default. + +## Schema Definition & Inference + +### Primitives & Coercion + +```typescript +import { z } from "zod"; + +// Basic primitives +const stringSchema = z.string().min(3).max(255); +const numberSchema = z.number().int().positive(); +const dateSchema = z.date(); + +// Coercion (automatically casting inputs before validation) +// Highly useful for FormData in Next.js Server Actions or URL queries +const ageSchema = z.coerce.number().min(18); // "18" -> 18 +const activeSchema = z.coerce.boolean(); // "true" -> true +const dobSchema = z.coerce.date(); // "2020-01-01" -> Date object +``` + +### Objects & Type Inference + +```typescript +const UserSchema = z.object({ + id: z.string().uuid(), + username: z.string().min(3).max(20), + email: z.string().email(), + role: z.enum(["ADMIN", "USER", "GUEST"]).default("USER"), + age: z.number().min(18).optional(), // Can be omitted + website: z.string().url().nullable(), // Can be null + tags: z.array(z.string()).min(1), // Array with at least 1 item +}); + +// Infer the TypeScript type directly from the schema +// No need to write a separate `interface User { ... }` +export type User = z.infer; +``` + +### Advanced Types + +```typescript +// Records (Objects with dynamic keys but specific value types) +const envSchema = z.record(z.string(), z.string()); // Record + +// Unions (OR) +const idSchema = z.union([z.string(), z.number()]); // string | number +// Or simpler: +const idSchema2 = z.string().or(z.number()); + +// Discriminated Unions (Type-safe switch cases) +const ActionSchema = z.discriminatedUnion("type", [ + z.object({ type: z.literal("create"), id: z.string() }), + z.object({ type: z.literal("update"), id: z.string(), data: z.any() }), + z.object({ type: z.literal("delete"), id: z.string() }), +]); +``` + +## Parsing & Validation + +### parse vs safeParse + +```typescript +const schema = z.string().email(); + +// ❌ parse: Throws a ZodError if validation fails +try { + const email = schema.parse("invalid-email"); +} catch (err) { + if (err instanceof z.ZodError) { + console.error(err.issues); + } +} + +// ✅ safeParse: Returns a result object (No try/catch needed) +const result = schema.safeParse("user@example.com"); + +if (!result.success) { + // TypeScript narrows result to SafeParseError + console.log(result.error.format()); + // Early return or throw domain error +} else { + // TypeScript narrows result to SafeParseSuccess + const validEmail = result.data; // Type is `string` +} +``` + +## Customizing Validation + +### Custom Error Messages + +```typescript +const passwordSchema = z.string() + .min(8, { message: "Password must be at least 8 characters long" }) + .max(100, { message: "Password is too long" }) + .regex(/[A-Z]/, { message: "Password must contain at least one uppercase letter" }) + .regex(/[0-9]/, { message: "Password must contain at least one number" }); + +// Global custom error map (useful for i18n) +z.setErrorMap((issue, ctx) => { + if (issue.code === z.ZodIssueCode.invalid_type) { + if (issue.expected === "string") return { message: "This field must be text" }; + } + return { message: ctx.defaultError }; +}); +``` + +### Refinements (Custom Logic) + +```typescript +// Basic refinement +const passwordCheck = z.string().refine((val) => val !== "password123", { + message: "Password is too weak", +}); + +// Cross-field validation (e.g., password matching) +const formSchema = z.object({ + password: z.string().min(8), + confirmPassword: z.string() +}).refine((data) => data.password === data.confirmPassword, { + message: "Passwords don't match", + path: ["confirmPassword"], // Sets the error on the specific field +}); +``` + +### Transformations + +```typescript +// Change data during parsing +const stringToNumber = z.string() + .transform((val) => parseInt(val, 10)) + .refine((val) => !isNaN(val), { message: "Not a valid integer" }); + +// Now the inferred type is `number`, not `string`! +type TransformedResult = z.infer; // number +``` + +## Integration Patterns + +### React Hook Form + +```typescript +import { useForm } from "react-hook-form"; +import { zodResolver } from "@hookform/resolvers/zod"; +import { z } from "zod"; + +const loginSchema = z.object({ + email: z.string().email("Invalid email address"), + password: z.string().min(6, "Password must be 6+ characters"), +}); + +type LoginFormValues = z.infer; + +export function LoginForm() { + const { register, handleSubmit, formState: { errors } } = useForm({ + resolver: zodResolver(loginSchema) + }); + + const onSubmit = (data: LoginFormValues) => { + // data is fully typed and validated + console.log(data.email, data.password); + }; + + return ( +
+ + {errors.email && {errors.email.message}} + {/* ... */} +
+ ); +} +``` + +### Next.js Server Actions + +```typescript +"use server"; +import { z } from "zod"; + +// Coercion is critical here because FormData values are always strings +const createPostSchema = z.object({ + title: z.string().min(3), + content: z.string().optional(), + published: z.coerce.boolean().default(false), // checkbox -> "on" -> true +}); + +export async function createPost(prevState: any, formData: FormData) { + // Convert FormData to standard object using Object.fromEntries + const rawData = Object.fromEntries(formData.entries()); + + const validatedFields = createPostSchema.safeParse(rawData); + + if (!validatedFields.success) { + return { + errors: validatedFields.error.flatten().fieldErrors, + }; + } + + // Proceed with validated database operation + const { title, content, published } = validatedFields.data; + // ... + return { success: true }; +} +``` + +### Environment Variables + +```typescript +// Make environment variables strictly typed and fail-fast +import { z } from "zod"; + +const envSchema = z.object({ + DATABASE_URL: z.string().url(), + NODE_ENV: z.enum(["development", "test", "production"]).default("development"), + PORT: z.coerce.number().default(3000), + API_KEY: z.string().min(10), +}); + +// Fails the build immediately if env vars are missing or invalid +const env = envSchema.parse(process.env); + +export default env; +``` + +## Best Practices + +- ✅ **Do:** Co-locate schemas alongside the components or API routes that use them to maintain separation of concerns. +- ✅ **Do:** Use `z.infer` everywhere instead of maintaining duplicate TypeScript interfaces manually. +- ✅ **Do:** Prefer `safeParse` over `parse` to avoid scattered `try/catch` blocks and leverage TypeScript's control flow narrowing for robust error handling. +- ✅ **Do:** Use `z.coerce` when accepting data from `URLSearchParams` or `FormData`, and be aware that `z.coerce.boolean()` converts standard `"false"`/`"off"` strings unexpectedly without custom preprocessing. +- ✅ **Do:** Use `.flatten()` or `.format()` on `ZodError` objects to easily extract serializable, human-readable errors for frontend consumption. +- ❌ **Don't:** Rely exclusively on `.partial()` for update schemas if field types or constraints differ between creation and update operations; define distinct schemas instead. +- ❌ **Don't:** Forget to pass the `path` option in `.refine()` or `.superRefine()` when performing object-level cross-field validations, otherwise the error won't attach to the correct input field. + +## Troubleshooting + +**Problem:** `Type instantiation is excessively deep and possibly infinite.` +**Solution:** This occurs with extreme schema recursion (e.g. deeply nested self-referential schemas). Use `z.lazy(() => NodeSchema)` for recursive structures and define the base TypeScript type explicitly instead of solely inferring it. + +**Problem:** Empty strings pass validation when using `.optional()`. +**Solution:** `.optional()` permits `undefined`, not empty strings. If an empty string means "no value," use `.or(z.literal(""))` or preprocess it: `z.string().transform(v => v === "" ? undefined : v).optional()`. diff --git a/skills_index.json b/skills_index.json index a54ff340..28412fec 100644 --- a/skills_index.json +++ b/skills_index.json @@ -10029,6 +10029,16 @@ "source": "community", "date_added": "2026-02-27" }, + { + "id": "zod-validation-expert", + "path": "skills/zod-validation-expert", + "category": "uncategorized", + "name": "zod-validation-expert", + "description": "Expert in Zod \u2014 TypeScript-first schema validation. Covers parsing, custom errors, refinements, type inference, and integration with React Hook Form, Next.js, and tRPC.", + "risk": "safe", + "source": "community", + "date_added": "2026-03-05" + }, { "id": "zoho-crm-automation", "path": "skills/zoho-crm-automation", From 9fa022b57daa0a66a8577449e1718520b5c7c78a Mon Sep 17 00:00:00 2001 From: sx4im Date: Thu, 5 Mar 2026 23:32:33 +0500 Subject: [PATCH 2/2] chore: sync generated registry files --- CATALOG.md | 5 +++-- README.md | 8 ++++---- data/bundles.json | 1 + data/catalog.json | 27 ++++++++++++++++++++++++++- 4 files changed, 34 insertions(+), 7 deletions(-) diff --git a/CATALOG.md b/CATALOG.md index 86e9aea8..4d395d26 100644 --- a/CATALOG.md +++ b/CATALOG.md @@ -2,7 +2,7 @@ Generated at: 2026-02-08T00:00:00.000Z -Total skills: 1006 +Total skills: 1007 ## architecture (69) @@ -325,7 +325,7 @@ applications. | php | php, pro, write, idiomatic, code, generators, iterators, s | `xlsx-official` | Comprehensive spreadsheet creation, editing, and analysis with support for formulas, formatting, data analysis, and visualization. When Claude needs to work ... | xlsx, official | xlsx, official, spreadsheet, creation, editing, analysis, formulas, formatting, data, visualization, claude, work | | `youtube-automation` | Automate YouTube tasks via Rube MCP (Composio): upload videos, manage playlists, search content, get analytics, and handle comments. Always search tools firs... | youtube | youtube, automation, automate, tasks, via, rube, mcp, composio, upload, videos, playlists, search | -## development (150) +## development (151) | Skill | Description | Tags | Triggers | | --- | --- | --- | --- | @@ -478,6 +478,7 @@ applications. | php | php, pro, write, idiomatic, code, generators, iterators, s | `uv-package-manager` | Master the uv package manager for fast Python dependency management, virtual environments, and modern Python project workflows. Use when setting up Python pr... | uv, package, manager | uv, package, manager, fast, python, dependency, virtual, environments, setting, up, managing, dependencies | | `viral-generator-builder` | Expert in building shareable generator tools that go viral - name generators, quiz makers, avatar creators, personality tests, and calculator tools. Covers t... | viral, generator, builder | viral, generator, builder, building, shareable, go, name, generators, quiz, makers, avatar, creators | | `webapp-testing` | Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing... | webapp | webapp, testing, toolkit, interacting, local, web, applications, playwright, supports, verifying, frontend, functionality | +| `zod-validation-expert` | Expert in Zod — TypeScript-first schema validation. Covers parsing, custom errors, refinements, type inference, and integration with React Hook Form, Next.js... | zod, validation | zod, validation, typescript, first, schema, covers, parsing, custom, errors, refinements, type, inference | | `zustand-store-ts` | Create Zustand stores with TypeScript, subscribeWithSelector middleware, and proper state/action separation. Use when building React state management, creati... | zustand, store, ts | zustand, store, ts, stores, typescript, subscribewithselector, middleware, proper, state, action, separation, building | ## general (200) diff --git a/README.md b/README.md index 9456467e..9a9b95c7 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# 🌌 Antigravity Awesome Skills: 1006+ Agentic Skills for Claude Code, Gemini CLI, Cursor, Copilot & More +# 🌌 Antigravity Awesome Skills: 1007+ Agentic Skills for Claude Code, Gemini CLI, Cursor, Copilot & More -> **The Ultimate Collection of 1006+ Universal Agentic Skills for AI Coding Assistants — Claude Code, Gemini CLI, Codex CLI, Antigravity IDE, GitHub Copilot, Cursor, OpenCode, AdaL** +> **The Ultimate Collection of 1007+ Universal Agentic Skills for AI Coding Assistants — Claude Code, Gemini CLI, Codex CLI, Antigravity IDE, GitHub Copilot, Cursor, OpenCode, AdaL** [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Claude Code](https://img.shields.io/badge/Claude%20Code-Anthropic-purple)](https://claude.ai) @@ -42,7 +42,7 @@ This repository provides essential skills to transform your AI assistant into a - [🎁 Curated Collections (Bundles)](#curated-collections) - [🧭 Antigravity Workflows](#antigravity-workflows) - [📦 Features & Categories](#features--categories) -- [📚 Browse 1006+ Skills](#browse-1006-skills) +- [📚 Browse 1007+ Skills](#browse-1007-skills) - [🤝 How to Contribute](#how-to-contribute) - [💬 Community](#community) - [☕ Support the Project](#support-the-project) @@ -341,7 +341,7 @@ The repository is organized into specialized domains to transform your AI into a Counts change as new skills are added. For the current full registry, see [CATALOG.md](CATALOG.md). -## Browse 1006+ Skills +## Browse 1007+ Skills We have moved the full skill registry to a dedicated catalog to keep this README clean, and we've also introduced an interactive **Web App**! diff --git a/data/bundles.json b/data/bundles.json index c636930e..bf9d15d5 100644 --- a/data/bundles.json +++ b/data/bundles.json @@ -251,6 +251,7 @@ "web-artifacts-builder", "webapp-testing", "wordpress-plugin-development", + "zod-validation-expert", "zustand-store-ts" ] }, diff --git a/data/catalog.json b/data/catalog.json index 8416be87..ccd0430d 100644 --- a/data/catalog.json +++ b/data/catalog.json @@ -1,6 +1,6 @@ { "generatedAt": "2026-02-08T00:00:00.000Z", - "total": 1006, + "total": 1007, "skills": [ { "id": "00-andruia-consultant", @@ -24688,6 +24688,31 @@ ], "path": "skills/zendesk-automation/SKILL.md" }, + { + "id": "zod-validation-expert", + "name": "zod-validation-expert", + "description": "Expert in Zod — TypeScript-first schema validation. Covers parsing, custom errors, refinements, type inference, and integration with React Hook Form, Next.js, and tRPC.", + "category": "development", + "tags": [ + "zod", + "validation" + ], + "triggers": [ + "zod", + "validation", + "typescript", + "first", + "schema", + "covers", + "parsing", + "custom", + "errors", + "refinements", + "type", + "inference" + ], + "path": "skills/zod-validation-expert/SKILL.md" + }, { "id": "zoho-crm-automation", "name": "zoho-crm-automation",