# Create Atomic Schema

Design and write a `BaseIOSchema` input/output pair for an Atomic Agents agent or tool...

- Repository: https://github.com/Eigenwise/atomic-agents (6314 stars)
- Category: Design
- License: MIT
- Last updated: 2026-10-29
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add Eigenwise/atomic-agents --skill create-atomic-schema -g -a claude-code -y`
Codex: `npx skills add Eigenwise/atomic-agents --skill create-atomic-schema -g -a codex -y`
Cursor: `npx skills add Eigenwise/atomic-agents --skill create-atomic-schema -g -a cursor -y`
Gemini CLI: `npx skills add Eigenwise/atomic-agents --skill create-atomic-schema -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add Eigenwise/atomic-agents`

## Description

Design and write a `BaseIOSchema` input/output pair for an Atomic Agents agent or tool, docstrings, field descriptions, validators, error variants. Use when the user asks to "create a schema", "design the input/output schema", "define an `IOSchema`", "write a `BaseIOSchema`", "model the agent's output", or runs `/atomic-agents:create-atomic-schema`.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Create an Atomic Agents Schema

Author a `BaseIOSchema` pair (input and/or output) that becomes the contract between an agent or tool and its caller. The framework enforces docstrings on every subclass, and Instructor flows field descriptions into the LLM prompt, so the schema **is** part of the prompt, not just typing.

For deep material (validators, discriminated unions, error envelopes), the authority is `../framework/references/schemas.md`. This skill is the action-oriented path: clarify → write → validate.

## When this fires vs the umbrella `framework` skill

- **This skill**: the user is creating or modifying a specific schema, e.g. "design the output schema for the planner agent", "add a field to `WeatherInput`", "split the result into success and failure variants".
- **`framework` skill**: the user is asking about Atomic Agents in general or doing something other than authoring schemas.

## Phase 1, Clarify

Ask only what is not already obvious from context. Bundle into one message; do not interrogate one-at-a-time.

1. **Caller**, is this for an `AtomicAgent`, a `BaseTool`, both (an agent that emits a tool-input schema), or a nested sub-schema?
2. **Direction**, input only, output only, or a paired Input/Output?
3. **Fields**, what fields does the caller need, with which types? (Required vs optional, defaults, constraints.)
4. **Failure modes**, can this legitimately fail? If yes, plan a typed error variant rather than raising. See `../framework/references/schemas.md` → "Error-schema pattern".

If the user is mid-conversation about an existing schema, skip questions answered in context.

## Phase 2, Write

Place schema(s) where they will be imported from. Conventional locations:

- `<project>/agents/<agent_name>/schemas.py`, agent-owned schemas
- `<project>/tools/<tool_name>_tool.py`, tool I/O lives next to the tool
- `<project>/schemas/<topic>.py`, schemas shared across multiple components

### Required ingredients on every schema

The rest: https://github.com/Eigenwise/atomic-agents/blob/HEAD/claude-plugin/atomic-agents/skills/create-atomic-schema/SKILL.md