zod
Zod v4 TypeScript schema validation patterns and best practices. Use when writing or modifying Zod schemas, adding schema annotations/metadata, or validating data with Zod.
Best use case
zod is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Zod v4 TypeScript schema validation patterns and best practices. Use when writing or modifying Zod schemas, adding schema annotations/metadata, or validating data with Zod.
Teams using zod should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/zod/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How zod Compares
| Feature / Agent | zod | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Zod v4 TypeScript schema validation patterns and best practices. Use when writing or modifying Zod schemas, adding schema annotations/metadata, or validating data with Zod.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Zod v4 Schema Validation
TypeScript-first schema validation library with static type inference. This skill covers v4 patterns including the metadata registry system.
## Schema Annotations
Zod v4 stores metadata in registries (primarily `z.globalRegistry`). Use `.meta()` as the primary API and `.describe()` as shorthand for description-only cases.
**IMPORTANT**: Always call `.meta()`/`.describe()` **last** in the method chain. Methods like `.min()`, `.optional()`, `.extend()` return new schema instances, so metadata must be attached at the end.
```typescript
// ✅ Correct - .meta() at end of chain
z.string().min(1).max(100).meta({ description: "User's full name", label: "Name" })
// ✅ Correct - .describe() shorthand for description only
z.string().email().describe("Primary email address")
// ❌ Wrong - metadata lost because .optional() creates new instance
z.string().meta({ description: "Lost!" }).optional()
```
**Annotating object properties:**
```typescript
const userSchema = z.object({
email: z.string().email().meta({
description: "Used for login",
label: "Email Address",
placeholder: "you@example.com"
}),
age: z.number().min(0).describe("User's age in years"),
});
```
**API guidance:**
- Use `.meta(obj)` for structured metadata (title, description, examples, UI hints)
- Use `.describe(text)` as shorthand when only a description string is needed
- Read `.description` for backwards compatibility with v3 tooling
- Never mutate `.description` directly—always use `.meta()`/`.describe()` to set
## Gotchas
- **Metadata chain order**: `.meta()`/`.describe()` MUST be called last—schema methods return new instances
- **Don't mutate .description**: Read `.description` for v3 compatibility, but always set via `.meta()` or `.describe()`
- **.email(), .uuid(), etc. are top-level**: Use `z.email()` not `z.string().email()` (latter deprecated)
- **z.object() strips unknown keys**: Use `z.strictObject()` to reject unknown keys
- **.merge() deprecated**: Use `.extend()` instead
## References
- Complete API reference: https://zod.dev/llms.txt
- Schema types: https://zod.dev/api
- Metadata/registries: https://zod.dev/metadata
- JSON Schema conversion: https://zod.dev/json-schema
- v3 → v4 migration: https://zod.dev/v4/changelogRelated Skills
writing-hashql-jexpr
HashQL J-Expr syntax for writing queries. Use when writing J-Expr code, using #literal/#struct/#list constructs, understanding function call syntax, or working with HashQL query files (.jsonc).
writing-hashql-diagnostics
HashQL diagnostic writing patterns using hashql-diagnostics crate. Use when creating error messages, warnings, Labels, Messages, Severity levels, Patches, Suggestions, or improving diagnostic quality in HashQL code.
testing-hashql
HashQL testing strategies including compiletest (UI tests), unit tests, and snapshot tests. Use when writing tests for HashQL code, using //~ annotations, running --bless, debugging test failures, or choosing the right testing approach.
skill-creator
Guide for creating effective Agent Skills. Use when users want to create a new skill (or update an existing skill) that extends an AI agent's capabilities with specialized knowledge, workflows, or tool integrations. Covers skill structure, YAML frontmatter, trigger configuration, and the 500-line rule.
panda-css
Panda CSS styling framework guidance. Use when working with @pandacss packages, styled components, design tokens, or responsive/conditional styles.
mastra
Mastra TypeScript framework for AI agents with memory, tools, workflows, and RAG. Use when working with @mastra/* packages or building AI agents.
managing-git-workflow
Git workflow for HASH including branch naming, PR creation, and PR reviews. Use when creating branches, making commits, opening pull requests, or reviewing PRs.
managing-cargo-dependencies
Cargo.toml dependency management patterns for HASH workspace. Use when adding, updating, or removing dependencies, organizing Cargo.toml sections, configuring version pinning and default features, or managing public dependencies.
handling-rust-errors
HASH error handling patterns using error-stack crate. Use when working with Result types, Report types, defining custom errors, propagating errors with change_context, adding context with attach, implementing Error trait, or documenting error conditions in Rust code.
exploring-rust-crates
Generate Rust documentation to understand crate APIs, structure, and usage. Use when exploring Rust code, understanding crate organization, finding functions/types/traits, or needing context about a Rust package in the HASH workspace.
documenting-rust-code
Rust documentation practices for HASH codebase. Use when writing doc comments, documenting functions/types/traits/modules, creating error sections, using intra-doc links, or following rustdoc conventions.
ark-ui
Headless component library for React. Use when building UI components with @ark-ui/react, implementing accessible form inputs, overlays, navigation patterns, or needing guidance on Ark UI's data attributes, composition (asChild), and state management patterns.