Using datamodel-code-generator with coding agents¶

This repository includes an experimental Agent Skill for skills-compatible coding agents. The skill teaches an agent to run datamodel-codegen when a user asks for Python models from OpenAPI, AsyncAPI, JSON Schema, GraphQL, JSON/YAML/CSV sample data, MCP tool schemas, Protocol Buffers, XML Schema, Apache Avro, or existing Python model objects.

The skill is a directory with a SKILL.md entrypoint and supporting files under references/. It is bundled with the CLI and can be installed without checking out this repository.

Treat this skill as experimental. The workflow, trigger wording, and client-specific install guidance can change as Codex, Claude Code, and other skills-compatible agents evolve.

Why agents should run the CLI¶

Agents should run datamodel-codegen instead of hand-writing generated models when a usable input artifact exists.

The CLI handles refs, enums, nested models, unions, allOf, oneOf, anyOf, and model reuse. It also produces output that can be imported and checked after generation.

Agents should also use the CLI for option discovery. datamodel-codegen --help links to this skill documentation, and --generate-prompt can produce either Markdown guidance or structured JSON for tool-aware agents.

datamodel-codegen [known options] --generate-prompt "Find the minimal options for this schema."
datamodel-codegen [known options] --generate-prompt "Find the minimal options for this schema." --output-format json
datamodel-codegen --output-format-json-schema structured-output

Use the generated prompt output before recommending a final command when the correct input type, output model type, strictness, aliasing, module layout, or verification flags are not obvious.

Install for Claude Code¶

Claude Code project skills load from .claude/skills/ in the starting directory and parent directories up to the repository root. Personal skills can be placed under ~/.claude/skills/.

For a project skill, run:

datamodel-codegen --install-skill claude-code

For a personal skill, run:

datamodel-codegen --install-skill claude-code --skill-scope user

Claude Code can invoke a skill directly with /datamodel-code-generator, or load it automatically when the description matches the task. Existing top-level skill directories are watched for changes. If the top-level skills directory did not exist when the session started, restart Claude Code.

Install for Codex¶

Codex reads project skills from .agents/skills in the current directory, parent directories, and the repository root. It reads personal skills from $HOME/.agents/skills.

For a project skill, run:

datamodel-codegen --install-skill codex

For a personal skill, run:

datamodel-codegen --install-skill codex --skill-scope user

Codex can invoke skills explicitly through /skills or $ mention, or load them automatically when the description matches the task.

The installer preserves an existing skill directory by default. Use --overwrite-skill only when you want to replace it; symlinks and non-directory targets are never overwritten.

Other agents¶

Other skills-compatible agents may support this directory format. Check the client documentation for its skill search path.

Distribution paths¶

Start with the repository skill. Consider Codex or Claude plugin packaging only as a separate distribution task.

Example prompt¶

Create Pydantic v2 models from openapi.yaml.

Expected agent behavior:

1. Runs datamodel-codegen.
2. Writes the generated file.
3. Imports the generated file.
4. Summarizes generated classes.

Troubleshooting¶

• The CLI command is datamodel-codegen.
• The package name is datamodel-code-generator.
• Use extras for HTTP, GraphQL, and protobuf when needed. Install msgspec separately when targeting msgspec.Struct.
• If a JSON or YAML file is a schema, choose openapi, asyncapi, or jsonschema input type instead of raw sample data mode.

References¶

• Agent Skills specification
• Codex Agent Skills
• Claude Code skills