Agent skill

atomic-schemas

This skill should be used when the user asks to "create a schema", "define input/output", "add fields", "validate data", "Pydantic schema", "BaseIOSchema", or needs guidance on schema design patterns, field definitions, validators, and type constraints for Atomic Agents applications.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/atomic-schemas

SKILL.md

Atomic Agents Schema Design

Schemas are the foundation of Atomic Agents applications. They define the contracts between agents, tools, and external systems using Pydantic models.

Core Principle: Always Use BaseIOSchema

python
from atomic_agents.lib.base.base_io_schema import BaseIOSchema
from pydantic import Field

class MySchema(BaseIOSchema):
    """Schema description."""
    field: str = Field(..., description="Field description")

Never use plain BaseModel - BaseIOSchema provides Atomic Agents integration features.

Field Definitions

Required Fields

python
name: str = Field(..., description="The user's full name")

Optional Fields

python
from typing import Optional
nickname: Optional[str] = Field(default=None, description="Optional nickname")

Fields with Defaults

python
count: int = Field(default=10, description="Number of items to return")

Constrained Fields

python
# Numeric constraints
age: int = Field(..., ge=0, le=150, description="Age in years")
score: float = Field(..., ge=0.0, le=1.0, description="Score between 0 and 1")

# String constraints
name: str = Field(..., min_length=1, max_length=100, description="Name")

# List constraints
tags: List[str] = Field(default_factory=list, max_length=10, description="Tags")

Literal Types (Fixed Options)

python
from typing import Literal
status: Literal["pending", "approved", "rejected"] = Field(..., description="Status")

Enums

python
from enum import Enum

class Priority(str, Enum):
    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"

priority: Priority = Field(default=Priority.MEDIUM, description="Priority level")

Validators

Field Validators

python
from pydantic import field_validator

class EmailSchema(BaseIOSchema):
    email: str = Field(..., description="Email address")

    @field_validator("email")
    @classmethod
    def validate_email(cls, v: str) -> str:
        if "@" not in v:
            raise ValueError("Invalid email format")
        return v.lower()

Model Validators

python
from pydantic import model_validator

class DateRangeSchema(BaseIOSchema):
    start: str = Field(..., description="Start date")
    end: str = Field(..., description="End date")

    @model_validator(mode="after")
    def validate_range(self) -> "DateRangeSchema":
        if self.end < self.start:
            raise ValueError("end must be after start")
        return self

Common Patterns

Chat Input/Output

python
class ChatInputSchema(BaseIOSchema):
    """User message input."""
    message: str = Field(..., min_length=1, description="User's message")

class ChatOutputSchema(BaseIOSchema):
    """Agent response output."""
    response: str = Field(..., description="Agent's response")

Structured Analysis Output

python
class AnalysisOutputSchema(BaseIOSchema):
    """Structured analysis result."""
    summary: str = Field(..., description="Brief summary")
    findings: List[str] = Field(default_factory=list, description="Key findings")
    confidence: float = Field(..., ge=0, le=1, description="Confidence score")
    recommendations: List[str] = Field(default_factory=list, description="Recommendations")

Tool Schemas

python
class ToolInputSchema(BaseIOSchema):
    """Tool input parameters."""
    query: str = Field(..., description="Search query")

class ToolOutputSchema(BaseIOSchema):
    """Successful tool result."""
    result: str = Field(..., description="Tool result")

class ToolErrorSchema(BaseIOSchema):
    """Tool error result."""
    error: str = Field(..., description="Error message")
    code: Optional[str] = Field(default=None, description="Error code")

Nested Schemas

python
class AddressSchema(BaseIOSchema):
    """Mailing address."""
    street: str = Field(..., description="Street address")
    city: str = Field(..., description="City")
    country: str = Field(..., description="Country code")

class PersonSchema(BaseIOSchema):
    """Person with address."""
    name: str = Field(..., description="Full name")
    address: AddressSchema = Field(..., description="Mailing address")

Union Types

python
from typing import Union

class TextContent(BaseIOSchema):
    type: Literal["text"] = "text"
    text: str = Field(..., description="Text content")

class ImageContent(BaseIOSchema):
    type: Literal["image"] = "image"
    url: str = Field(..., description="Image URL")

class MessageSchema(BaseIOSchema):
    content: Union[TextContent, ImageContent] = Field(..., description="Content")

Best Practices

  1. Always provide descriptions - LLMs use them to understand field purpose
  2. Constrain appropriately - Use ge, le, min_length, max_length, Literal
  3. Validate business rules - Use field_validator and model_validator
  4. Use Optional sparingly - Only when truly optional
  5. Provide sensible defaults - When there's a clear default value
  6. Document with docstrings - Explain the schema's purpose
  7. Compose for complexity - Nest schemas for structured data

References

See references/ for:

  • advanced-patterns.md - Complex schema patterns
  • validation-patterns.md - Advanced validator examples

See examples/ for:

  • common-schemas.py - Ready-to-use schema templates

Didn't find tool you were looking for?

Be as detailed as possible for better results