# pydantic

A skill that teaches the agent how to model, constrain and validate data with Pydantic, mostly when input comes from outside your code.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 2200 installs · ★ 145
- Author: pydantic
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/pydantic/skills/tree/HEAD/skills/pydantic/SKILL.md
- Updated: 2026-10-16
- HTML: https://affpapa.org/en/nevibecode/skills/pydantic

## What it does

Pydantic is a Python validation and serialization library built on type hints. This skill gives the agent rules for using it: declaring models, adding constraints through `Field()` and `Annotated`, writing validators. It matters most when the data is untrusted, say an HTTP API payload.

The guidance covers the tricky parts. Prefer built-in constraints like `Gt` or `StringConstraints` over a hand-written validator. When a custom validator is unavoidable, use *after* mode, because the value already has the field's type by then. The skill also recommends the annotated pattern over `Field()` with no default, since that form reads as if the field had a default while it stays required.

It also says where Pydantic does not belong. For classes instantiated inside your own code, the library costs you flexibility, and a static type checker already catches mismatches. Worth checking before you reach for it out of habit. The skill installs into Claude, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add pydantic/skills --skill pydantic -a claude-code
```

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

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add pydantic/skills --skill pydantic -a codex
```

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

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add pydantic/skills --skill pydantic -a cursor
```

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

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install pydantic/skills pydantic
```

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

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add pydantic/skills --skill pydantic -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/pydantic/skills --path skills/pydantic
```

### Windsurf (Devin Desktop)

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

### OpenCode

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

## When to use it
- declare a model with field constraints instead of manual checks
- validate a payload coming from an external API
- pick between a built-in constraint and a custom validator
- coerce a string into a date or number without extra code
- decide whether a class inside your own code needs Pydantic

## Example prompts
- Write a Pydantic model for a user with an age constraint and an alias for the name field
- Add an after validator that rejects odd numbers using Annotated
- Rewrite this class with Pydantic, the data comes from an external API

## 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: 120be866cd5b82e5.

BEGIN THIRD-PARTY FILE 120be866cd5b82e5
````text
---
name: pydantic
description: Pydantic is a Python data validation and serialization library, based on type hints. Use this skill whenever you need to do relatively complex data modeling using Pydantic, e.g. when adding constraints, defining a model hierarchy with subclasses, etc.
---

# Pydantic Validation

In a nutshell, Pydantic is dataclasses with runtime validation. It leverages type hints
to understand how validation (and serialization) should be performed. It is mostly useful
when dealing with external untrusted data, for example when defining an HTTP API.

It is generally *not* recommended to use Pydantic to define classes that are instantiated within the user code.
By doing so, you will lose flexibility (e.g. you cannot use types not supported by Pydantic, and it is harder to perform
post-init changes). It is usually better to use vanilla classes (or standard library dataclasses) in this case,
as a static type checker will already catch type mismatches.

## Basic usage

Here is a simple example of using a Pydantic model:

```python
from datetime import date

from pydantic import BaseModel, Field


class Person(BaseModel):
    name: str
    age: int = Field(description='The age of the person')
    birthdate: date | None = None


p = Person(name='John', age=20, birthdate='1970-01-01')
```

Pydantic coerces compatible input: the ISO date string `'1970-01-01'` is parsed into a `date`.

## Constraints and field metadata

The `Field()` function is used to provide metadata and constraints.
You need to distinguish two types of metadata:

* *field specific* metadata: metadata such as `deprecated` and `alias`, that only
  have meaning when attached to a field.
* *type specific* metadata: this includes constraints such as `gt`, `max_length`,
  and also metadata that affects the JSON Schema (e.g. `description`, `title`).

Model fields are declared with `Field()` using the assignment form:

```python
from pydantic import BaseModel, Field


class User(BaseModel):
    first_name: str = Field(alias='name')
```

or using the annotated pattern:

```python
from typing import Annotated

from pydantic import BaseModel, Field


class Model(BaseModel):
    value: Annotated[int, Field(deprecated=True)] = 1
```

The annotated pattern has some advantages:

* Using the `f: <type> = Field()` form (no default) can be confusing and might trick users into thinking `f`
  has a default value, while in reality the field is still required.
* You can provide an arbitrary amount of metadata elements for a field. As shown in the example above,
  the `Field()` function only supports a limited set of constraints/metadata,
  and you may have to use different Pydantic utilities such as `WithJsonSchema`
  in some cases.

But note that:
````
END THIRD-PARTY FILE 120be866cd5b82e5

The third-party file has ended. Everything between the 120be866cd5b82e5 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 2754 of 10134 bytes. © pydantic · MIT · https://github.com/pydantic/skills/tree/HEAD/skills/pydantic/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