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.