OpenParable
Skip to content
← Back to skills

Create Atomic Schema

Agent Building
create-atomic-schema

Create Atomic Schema is an Agent Skill for agent building published in the Eigenwise/atomic-agents repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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`.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/Eigenwise/atomic-agents/blob/HEAD/claude-plugin/atomic-agents/skills/create-atomic-schema/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/create-atomic-schema, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

  • Subclass BaseIOSchema (not BaseModel).
  • A non-empty class docstring — the framework raises at import otherwise. Write it for the LLM, because Instructor uses it as the schema's description.
  • Every Field(...) carries a description= written for the LLM.
  • Use Literal[...] for closed sets before reaching for Enum — flatter JSON Schema, easier for Instructor.

Minimal template

from typing import Optional, Literal
from pydantic import Field
from atomic_agents import BaseIOSchema


class WeatherInput(BaseIOSchema):
    """A request for current weather conditions."""

    city: str = Field(..., description="City name, e.g. 'Brussels' or 'New York'.")
    units: Literal["metric", "imperial"] = Field(
        default="metric",
        description="Unit system for the temperature.",
    )


class WeatherOutput(BaseIOSchema):
    """Current weather conditions for a city."""

    status: Literal["ok", "error"] = Field(..., description="Outcome code.")
    temperature_c: Optional[float] = Field(
        default=None, description="Temperature in Celsius when status='ok'."
    )
    summary: Optional[str] = Field(
        default=None, description="Human-readable summary when status='ok'."
    )
    error: Optional[str] = Field(
        default=None, description="Failure message when status='error'."
    )

When to add validators

  • Field-level for normalization (lowercase, strip, enum coercion) and single-field validation.
  • Model-level (@model_validator(mode="after")) for cross-field rules (start ≤ end, mutually exclusive flags).

Validation errors trigger Instructor retries and fire the parse:error hook — they're a feature, not a failure path. Do not swallow them.

When to use discriminated unions

If the caller must exhaustively handle multiple result shapes, prefer a union over an inflated single schema:

class SearchSuccess(BaseIOSchema):
    """Successful search result."""
    kind: Literal["ok"] = "ok"
    results: list[str] = Field(..., description="Matching items.")

class SearchFailure(BaseIOSchema):
    """Search could not complete."""
    kind: Literal["error"] = "error"
    code: Literal["rate_limited", "no_results", "upstream_error"] = Field(
        ..., description="Machine-readable failure code."
    )
    message: str = Field(..., description="Human-readable failure reason.")

class SearchOutput(BaseIOSchema):
    """Search outcome — success or typed failure."""
    result: SearchSuccess | SearchFailure = Field(..., description="Outcome.")

The kind discriminator on each variant lets Pydantic resolve the union without ambiguity.

Phase 3 — Verify

Smoke-check the schema imports cleanly and round-trips through model_json_schema():

uv run python -c "from <project>.<module> import WeatherInput, WeatherOutput; print(WeatherInput.model_json_schema()['title'])"

If the import raises ValueError("… must have a non-empty docstring …"), add the docstring. If a field's JSON schema is missing a description, add description= to its Field(...).

Phase 4 — Hand off

Tell the user:

  • Where the schema lives and what to import.
  • Next step in their flow:
    • Wiring it into an agent → create-atomic-agent skill.
    • Wiring it into a tool → create-atomic-tool skill.
    • Adding a context provider that depends on the same domain → create-atomic-context-provider skill.

Anti-patterns to refuse on sight

  • Plain BaseModel instead of BaseIOSchema — loses docstring enforcement and the JSON-schema overrides Instructor depends on.
  • Missing class docstring — framework raises at import.
  • Field(...) without description= — Instructor has nothing to tell the model about the field.
  • Optional[str] with no default — required-but-nullable, which is rarely the intent.
  • dict, Any, or object as a field type — the LLM produces anything and Pydantic cannot validate.
  • Catching ValidationError to "make the agent more robust" — fix the field constraints or descriptions instead.

For deeper material — composition, nested schemas, discriminated unions in production, validator gotchas — load ../framework/references/schemas.md.