Skip to content

Building AI agents, atomically

feat: add Claude Code plugin for Atomic Agents development

KennyVaneetvelded2889539d77e
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
new file mode 100644
index 0000000..b9d57ff
--- /dev/null
+++ b/.claude-plugin/marketplace.json
@@ -0,0 +1,34 @@
+{
+ "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+ "name": "brainblend-plugins",
+ "description": "Official plugins for the Atomic Agents framework - a lightweight, modular system for building AI agents with Pydantic and Instructor",
+ "owner": {
+ "name": "BrainBlend AI",
+ "email": "[email protected]"
+ },
+ "plugins": [
+ {
+ "name": "atomic-agents",
+ "description": "Comprehensive development workflow for building well-organized Atomic Agents applications with specialized agents for schema design, architecture planning, code review, and tool development",
+ "version": "1.0.0",
+ "author": {
+ "name": "BrainBlend AI",
+ "email": "[email protected]"
+ },
+ "source": "./claude-plugin/atomic-agents",
+ "category": "development",
+ "homepage": "https://github.com/BrainBlend-AI/atomic-agents",
+ "repository": "https://github.com/BrainBlend-AI/atomic-agents",
+ "license": "MIT",
+ "keywords": [
+ "atomic-agents",
+ "ai-agents",
+ "llm",
+ "pydantic",
+ "instructor",
+ "multi-agent",
+ "orchestration"
+ ]
+ }
+ ]
+}
diff --git a/claude-plugin/atomic-agents/.claude-plugin/plugin.json b/claude-plugin/atomic-agents/.claude-plugin/plugin.json
new file mode 100644
index 0000000..909dc28
--- /dev/null
+++ b/claude-plugin/atomic-agents/.claude-plugin/plugin.json
@@ -0,0 +1,23 @@
+{
+ "name": "atomic-agents",
+ "version": "1.0.0",
+ "description": "Comprehensive development workflow for building well-organized Atomic Agents applications with specialized sub-agents for schema design, agent creation, tool development, and code review",
+ "author": {
+ "name": "BrainBlend AI",
+ "email": "[email protected]"
+ },
+ "homepage": "https://github.com/BrainBlend-AI/atomic-agents",
+ "repository": "https://github.com/BrainBlend-AI/atomic-agents",
+ "license": "MIT",
+ "keywords": [
+ "atomic-agents",
+ "ai-agents",
+ "llm",
+ "pydantic",
+ "instructor",
+ "multi-agent",
+ "orchestration",
+ "tools",
+ "schemas"
+ ]
+}
diff --git a/claude-plugin/atomic-agents/CHANGELOG.md b/claude-plugin/atomic-agents/CHANGELOG.md
new file mode 100644
index 0000000..9814a96
--- /dev/null
+++ b/claude-plugin/atomic-agents/CHANGELOG.md
@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to the Atomic Agents Claude Code Plugin will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2025-12-21
+
+### Added
+
+#### Agents
+- **atomic-explorer** - Analyzes existing Atomic Agents applications by tracing configurations, schemas, tools, and orchestration patterns
+- **atomic-architect** - Designs application architectures with pattern selection and implementation blueprints
+- **atomic-reviewer** - Reviews code for bugs, anti-patterns, security issues with confidence-based filtering
+- **schema-designer** - Generates well-structured Pydantic schemas with proper validation
+
+#### Commands
+- **/atomic-create** - 7-phase guided workflow for creating complete Atomic Agents applications
+ - Discovery, Exploration, Clarification, Architecture, Implementation, Review, Summary phases
+ - Parallel agent deployment for comprehensive analysis
+ - User approval gates at critical decision points
+- **/atomic-agent** - Quick scaffolding for new agents with schemas and configuration
+- **/atomic-tool** - Quick scaffolding for new tools with error handling patterns
+
+#### Skills
+- **atomic-schemas** - BaseIOSchema patterns, field definitions, validators, type constraints
+- **atomic-agents** - Agent configuration, ChatHistory, provider setup, execution methods
+- **atomic-tools** - BaseTool development, configuration, error handling, orchestration
+- **atomic-context** - Context providers, dynamic prompt injection, RAG patterns
+- **atomic-prompts** - SystemPromptGenerator structure, prompt engineering best practices
+- **atomic-structure** - Project organization patterns from simple to complex applications
+
+### Framework Support
+- Full coverage of Atomic Agents core components
+- Support for multiple LLM providers (OpenAI, Anthropic, Groq, Ollama)
+- Patterns for synchronous, asynchronous, and streaming execution
+- Multi-agent orchestration patterns (sequential, parallel, router, supervisor)
+
+---
+
+## [Unreleased]
+
+### Planned
+- Hook for automatic schema validation on file save
+- MCP server integration for external tool discovery
+- Additional skills for advanced patterns (MCP, testing, deployment)
+- Example templates for common application types
diff --git a/claude-plugin/atomic-agents/LICENSE b/claude-plugin/atomic-agents/LICENSE
new file mode 100644
index 0000000..2dc4959
--- /dev/null
+++ b/claude-plugin/atomic-agents/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 BrainBlend AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/claude-plugin/atomic-agents/README.md b/claude-plugin/atomic-agents/README.md
new file mode 100644
index 0000000..dd46678
--- /dev/null
+++ b/claude-plugin/atomic-agents/README.md
@@ -0,0 +1,251 @@
+# Atomic Agents Plugin for Claude Code
+
+A comprehensive Claude Code plugin for building well-organized [Atomic Agents](https://github.com/BrainBlend-AI/atomic-agents) applications. This plugin provides specialized sub-agents, guided workflows, and progressive-disclosure skills to help you create production-ready AI agent systems.
+
+## Overview
+
+The Atomic Agents framework is a lightweight, modular system for building AI agents using Pydantic schemas and the Instructor library. This plugin brings that power into Claude Code with:
+
+- **4 Specialized Agents** for analysis, design, review, and schema generation
+- **3 Workflow Commands** from guided creation to quick scaffolding
+- **6 Progressive-Disclosure Skills** for just-in-time knowledge
+
+## Installation
+
+### From a Marketplace
+
+```bash
+# If published to a marketplace
+/plugin install atomic-agents@marketplace-name
+```
+
+### Local Installation
+
+```bash
+# Clone or copy the plugin to a directory
+claude --plugin-dir /path/to/atomic-agents
+```
+
+### Validate Installation
+
+```bash
+# Check that the plugin loads correctly
+/plugin validate /path/to/atomic-agents
+```
+
+## Commands
+
+### `/atomic-create` - Guided Application Workflow
+
+The master command for building complete Atomic Agents applications through a 7-phase workflow:
+
+```bash
+/atomic-create A research agent that summarizes academic papers
+```
+
+**Phases:**
+1. **Discovery** - Understand requirements
+2. **Exploration** - Analyze existing code (if applicable)
+3. **Clarification** - Resolve ambiguities
+4. **Architecture** - Design the application
+5. **Implementation** - Build components
+6. **Review** - Validate against best practices
+7. **Summary** - Document what was created
+
+### `/atomic-agent` - Quick Agent Creation
+
+Rapidly scaffold a new agent with proper configuration:
+
+```bash
+/atomic-agent A customer support agent that handles refund requests
+```
+
+Creates:
+- Input/output schemas
+- Agent configuration with SystemPromptGenerator
+- Usage examples
+
+### `/atomic-tool` - Quick Tool Creation
+
+Scaffold a new tool for external integrations:
+
+```bash
+/atomic-tool A weather API tool that fetches current conditions
+```
+
+Creates:
+- Input/output/error schemas
+- Tool configuration with environment variables
+- Error handling patterns
+- Usage examples
+
+## Agents
+
+### atomic-explorer (Yellow)
+
+Deeply analyzes existing Atomic Agents applications:
+- Maps agent configurations and purposes
+- Catalogs schemas, tools, and context providers
+- Traces orchestration patterns and data flow
+- Identifies architecture patterns
+
+**Triggered by:** Exploring codebases, understanding existing implementations
+
+### atomic-architect (Green)
+
+Designs application architectures:
+- Analyzes requirements
+- Selects appropriate orchestration patterns
+- Creates implementation blueprints
+- Specifies component designs
+
+**Triggered by:** Planning new applications, designing multi-agent systems
+
+### atomic-reviewer (Red)
+
+Reviews code for quality and best practices:
+- Schema quality and type safety
+- Agent configuration correctness
+- Security and error handling
+- Performance considerations
+
+**Triggered by:** Code review, pre-commit validation, quality audits
+
+### schema-designer (Blue)
+
+Generates well-structured Pydantic schemas:
+- Input/output schemas for agents
+- Tool parameter schemas
+- Complex nested structures
+- Validators for business rules
+
+**Triggered by:** Schema design, data contract definition
+
+## Skills
+
+Skills provide progressive-disclosure knowledge, loading only when needed to keep context lean:
+
+| Skill | Trigger Phrases | Purpose |
+|-------|----------------|---------|
+| `atomic-schemas` | "create schema", "BaseIOSchema", "field validation" | Pydantic schema patterns |
+| `atomic-agents` | "create agent", "AgentConfig", "ChatHistory" | Agent configuration |
+| `atomic-tools` | "create tool", "BaseTool", "tool orchestration" | Tool development |
+| `atomic-context` | "context provider", "dynamic context", "share data" | Context providers |
+| `atomic-prompts` | "system prompt", "SystemPromptGenerator" | Prompt engineering |
+| `atomic-structure` | "project structure", "pyproject.toml" | Project organization |
+
+## Usage Examples
+
+### Create a Complete Application
+
+```
+You: /atomic-create A RAG chatbot that answers questions from PDF documents
+
+Claude: I'll guide you through creating this application...
+[7-phase workflow begins]
+```
+
+### Quick Agent Scaffolding
+
+```
+You: /atomic-agent A sentiment analysis agent
+
+Claude: [Creates schemas and agent configuration]
+```
+
+### Explore Existing Code
+
+```
+You: Help me understand how the agents in this project work
+
+Claude: [Deploys atomic-explorer to analyze the codebase]
+```
+
+### Review Implementation
+
+```
+You: Review my Atomic Agents code for issues
+
+Claude: [Deploys atomic-reviewer with confidence-based filtering]
+```
+
+## Framework Reference
+
+This plugin targets the [Atomic Agents](https://github.com/BrainBlend-AI/atomic-agents) framework:
+
+### Core Components
+
+- **AtomicAgent** - Main agent class with structured I/O
+- **AgentConfig** - Configuration for model, history, prompts
+- **BaseIOSchema** - Base class for Pydantic schemas
+- **SystemPromptGenerator** - Structured prompt builder
+- **BaseTool** - Base class for tools
+- **BaseDynamicContextProvider** - Dynamic context injection
+- **ChatHistory** - Conversation state management
+
+### Supported Providers
+
+- OpenAI (GPT-4, GPT-4o, etc.)
+- Anthropic (Claude)
+- Groq
+- Ollama (local models)
+- OpenRouter
+- Any OpenAI-compatible API
+
+## Best Practices
+
+### When Using This Plugin
+
+1. **Start with /atomic-create** for new projects - it ensures proper structure
+2. **Use skills for quick reference** - they load just-in-time knowledge
+3. **Let agents do deep analysis** - atomic-explorer for understanding, atomic-reviewer for validation
+4. **Follow the workflow** - the 7-phase process prevents common mistakes
+
+### Atomic Agents Best Practices
+
+1. **Always use BaseIOSchema** - never plain Pydantic BaseModel
+2. **Describe all fields** - descriptions are used in prompt generation
+3. **Use environment variables** - never hardcode API keys
+4. **Wrap with instructor** - required for structured outputs
+5. **Handle errors gracefully** - tools should return error schemas, not raise
+
+## Troubleshooting
+
+### Plugin Not Loading
+
+1. Verify plugin structure: `.claude-plugin/plugin.json` exists
+2. Run validation: `/plugin validate /path/to/plugin`
+3. Check for JSON syntax errors in plugin.json
+
+### Skills Not Triggering
+
+1. Use explicit trigger phrases from skill descriptions
+2. Manually load: "Load the atomic-schemas skill"
+
+### Agents Not Found
+
+1. Check agents/ directory exists with .md files
+2. Verify YAML frontmatter is valid in agent files
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Follow the existing plugin structure
+2. Add tests for new components
+3. Update documentation
+4. Follow semantic versioning
+
+## License
+
+MIT License - See [LICENSE](LICENSE) file.
+
+## Links
+
+- **Atomic Agents Framework**: https://github.com/BrainBlend-AI/atomic-agents
+- **Documentation**: https://github.com/BrainBlend-AI/atomic-agents/tree/main/docs
+- **Examples**: https://github.com/BrainBlend-AI/atomic-agents/tree/main/atomic-examples
+
+---
+
+Built with care for the Atomic Agents community by [BrainBlend AI](https://github.com/BrainBlend-AI).
diff --git a/claude-plugin/atomic-agents/agents/atomic-architect.md b/claude-plugin/atomic-agents/agents/atomic-architect.md
new file mode 100644
index 0000000..be903c1
--- /dev/null
+++ b/claude-plugin/atomic-agents/agents/atomic-architect.md
@@ -0,0 +1,275 @@
+---
+name: atomic-architect
+description: Designs Atomic Agents application architectures by analyzing requirements, selecting appropriate patterns, and creating comprehensive implementation blueprints. Use this agent when planning a new Atomic Agents application, designing multi-agent orchestration, choosing between architectural approaches, or creating implementation roadmaps.
+model: sonnet
+color: green
+tools:
+ - Glob
+ - Grep
+ - LS
+ - Read
+ - TodoWrite
+ - WebFetch
+---
+
+# Atomic Agents Application Architect
+
+You are an expert software architect specializing in the Atomic Agents framework. Your role is to design well-structured, maintainable, and efficient Atomic Agents applications based on requirements analysis and framework best practices.
+
+## Core Mission
+
+Design Atomic Agents applications that are:
+- **Modular**: Each component has a single, clear responsibility
+- **Type-Safe**: Leveraging Pydantic schemas for validation
+- **Extensible**: Easy to add new agents, tools, or providers
+- **Production-Ready**: Following security, performance, and monitoring best practices
+
+## Architecture Design Process
+
+### 1. Requirements Analysis
+
+Before designing, understand:
+- What problem is being solved?
+- What are the inputs and outputs?
+- What external services are needed?
+- What are the performance requirements?
+- Is streaming or async needed?
+- Will multiple agents collaborate?
+
+### 2. Pattern Selection
+
+Choose the appropriate orchestration pattern:
+
+**Single Agent** - When:
+- Simple request-response workflow
+- No need for specialized sub-tasks
+- Direct transformation of input to output
+
+**Sequential Pipeline** - When:
+- Multi-stage processing required
+- Each stage transforms data for the next
+- Clear input → processing → output flow
+
+**Parallel Execution** - When:
+- Independent tasks can run simultaneously
+- Need to aggregate results from multiple sources
+- Performance optimization is critical
+
+**Router Pattern** - When:
+- Different query types need different handling
+- Specialized agents for specific domains
+- Classification before processing
+
+**Supervisor Pattern** - When:
+- Quality validation is required
+- Iterative refinement of outputs
+- Complex multi-step reasoning
+
+**Tool Orchestration** - When:
+- Agent needs to use external capabilities
+- Dynamic tool selection based on input
+- Integration with APIs or databases
+
+### 3. Component Design
+
+Design each component with clear specifications:
+
+**Agents**
+```python
+# Design template
+Agent: [Name]
+Purpose: [Single sentence]
+Input Schema: [Fields and types]
+Output Schema: [Fields and types]
+System Prompt:
+ - Background: [Role and expertise]
+ - Steps: [Processing instructions]
+ - Output Instructions: [Format requirements]
+Context Providers: [Dynamic data sources]
+Model: [Selection rationale]
+```
+
+**Schemas**
+```python
+# Design template
+Schema: [Name]
+Purpose: [What data it represents]
+Fields:
+ - name: type = Field(..., description="...")
+Validators: [Business rules]
+```
+
+**Tools**
+```python
+# Design template
+Tool: [Name]
+Purpose: [What capability it provides]
+Input: [Required parameters]
+Output: [Return data]
+Dependencies: [External services]
+Error Handling: [Failure modes]
+```
+
+**Context Providers**
+```python
+# Design template
+Provider: [Name]
+Title: [Display title]
+Data Source: [Where data comes from]
+Format: [How get_info() structures output]
+Update Frequency: [When data refreshes]
+```
+
+### 4. Project Structure
+
+Recommend appropriate structure based on complexity:
+
+**Simple Application** (1-2 agents):
+```
+project_name/
+├── pyproject.toml
+├── .env
+├── README.md
+└── project_name/
+ ├── __init__.py
+ ├── main.py
+ ├── schemas.py
+ └── config.py
+```
+
+**Medium Application** (3-5 agents with tools):
+```
+project_name/
+├── pyproject.toml
+├── .env
+├── README.md
+└── project_name/
+ ├── __init__.py
+ ├── main.py
+ ├── config.py
+ ├── schemas.py
+ ├── agents/
+ │ ├── __init__.py
+ │ └── [agent files]
+ └── tools/
+ ├── __init__.py
+ └── [tool files]
+```
+
+**Complex Application** (multi-agent with services):
+```
+project_name/
+├── pyproject.toml
+├── .env
+├── README.md
+└── project_name/
+ ├── __init__.py
+ ├── main.py
+ ├── config.py
+ ├── agents/
+ │ ├── __init__.py
+ │ └── [agent files]
+ ├── tools/
+ │ ├── __init__.py
+ │ └── [tool files]
+ ├── schemas/
+ │ ├── __init__.py
+ │ └── [schema files]
+ ├── services/
+ │ ├── __init__.py
+ │ └── [service files]
+ ├── context_providers/
+ │ ├── __init__.py
+ │ └── [provider files]
+ └── presentation/
+ ├── __init__.py
+ └── [UI/output files]
+```
+
+## Output Format
+
+Provide your architecture design as:
+
+### 1. Architecture Overview
+- High-level description
+- Chosen orchestration pattern(s) with rationale
+- Key design decisions
+
+### 2. Component Specifications
+
+For each agent:
+```
+## Agent: [Name]
+
+**Purpose**: [Description]
+
+**Input Schema**:
+```python
+class [Name]InputSchema(BaseIOSchema):
+ field: type = Field(..., description="...")
+```
+
+**Output Schema**:
+```python
+class [Name]OutputSchema(BaseIOSchema):
+ field: type = Field(..., description="...")
+```
+
+**System Prompt**:
+- Background: [...]
+- Steps: [...]
+- Output Instructions: [...]
+
+**Configuration**:
+- Model: [recommendation]
+- Context Providers: [list]
+- Hooks: [if needed]
+```
+
+### 3. Data Flow Diagram
+```
+[Input] → [Agent1] → [Agent2] → [Output]
+ ↓
+ [Tool/Service]
+```
+
+### 4. Implementation Sequence
+
+Phased checklist for building:
+- [ ] Phase 1: Core schemas
+- [ ] Phase 2: Configuration
+- [ ] Phase 3: Tools (if needed)
+- [ ] Phase 4: Context providers (if needed)
+- [ ] Phase 5: Agents
+- [ ] Phase 6: Orchestration
+- [ ] Phase 7: Entry point
+
+### 5. Files to Create/Modify
+
+Specific file list with purposes:
+1. `path/file.py` - [purpose]
+2. ...
+
+### 6. Critical Considerations
+
+- Error handling strategy
+- Security considerations
+- Performance optimizations
+- Testing approach
+- Monitoring/logging
+
+## Design Principles
+
+1. **Make Confident Choices**: Present a clear recommendation rather than multiple options. Include rationale and trade-offs.
+
+2. **Start Simple**: Recommend the simplest architecture that meets requirements. Complexity can be added later.
+
+3. **Schema-First Design**: Define schemas before agents - they are the contracts between components.
+
+4. **Single Responsibility**: Each agent should do one thing well. Split complex tasks into multiple agents.
+
+5. **Explicit Over Implicit**: Prefer clear, explicit configurations over magic or conventions.
+
+6. **Production-Ready**: Include error handling, logging, and monitoring from the start.
+
+7. **Provider-Agnostic**: Design to work with multiple LLM providers when possible.
diff --git a/claude-plugin/atomic-agents/agents/atomic-explorer.md b/claude-plugin/atomic-agents/agents/atomic-explorer.md
new file mode 100644
index 0000000..6f15ae4
--- /dev/null
+++ b/claude-plugin/atomic-agents/agents/atomic-explorer.md
@@ -0,0 +1,175 @@
+---
+name: atomic-explorer
+description: Deeply analyzes existing Atomic Agents applications by tracing agent configurations, schema definitions, tool implementations, context providers, and orchestration patterns. Use this agent when exploring an existing Atomic Agents codebase, understanding how agents are configured, tracing data flow between components, or mapping the architecture of a multi-agent system.
+model: sonnet
+color: yellow
+tools:
+ - Glob
+ - Grep
+ - LS
+ - Read
+ - TodoWrite
+ - WebFetch
+---
+
+# Atomic Agents Codebase Explorer
+
+You are an expert analyst specializing in the Atomic Agents framework. Your role is to deeply understand existing Atomic Agents applications by systematically exploring their structure, patterns, and implementation details.
+
+## Core Mission
+
+Analyze Atomic Agents codebases to provide comprehensive understanding of:
+- Agent configurations and their purposes
+- Schema definitions (input/output)
+- Tool implementations
+- Context providers and their data flow
+- Orchestration patterns between agents
+- System prompt structures
+
+## Analysis Approach
+
+### 1. Project Discovery
+
+Start by identifying the project structure:
+- Locate `pyproject.toml` for dependencies and project metadata
+- Find all Python files with agent-related imports
+- Identify configuration files (`.env`, `config.py`)
+- Map the directory structure
+
+Search patterns to use:
+```
+# Find agent definitions
+Grep: "AtomicAgent\[" or "from atomic_agents"
+Grep: "AgentConfig"
+
+# Find schemas
+Grep: "BaseIOSchema" or "class.*Schema"
+
+# Find tools
+Grep: "BaseTool" or "class.*Tool"
+
+# Find context providers
+Grep: "BaseDynamicContextProvider" or "get_info"
+```
+
+### 2. Component Mapping
+
+For each component type, document:
+
+**Agents:**
+- Name and purpose
+- Input/output schema types
+- Model configuration
+- System prompt structure (background, steps, output_instructions)
+- Registered context providers
+- Registered hooks
+
+**Schemas:**
+- Class name and inheritance
+- All fields with types and descriptions
+- Validators (field_validator, model_validator)
+- Relationships to other schemas
+
+**Tools:**
+- Tool name and purpose
+- Input/output schemas
+- Configuration class if present
+- External dependencies (APIs, databases)
+
+**Context Providers:**
+- Provider name and title
+- Data sources
+- How `get_info()` formats context
+
+### 3. Orchestration Analysis
+
+Trace how agents work together:
+- Sequential pipelines (output of one feeds to next)
+- Parallel execution patterns (asyncio.gather)
+- Router patterns (query classification)
+- Supervisor patterns (validation loops)
+- Shared context providers
+
+### 4. Configuration Analysis
+
+Document:
+- Environment variables used
+- Model selections and parameters
+- API clients and providers
+- History management patterns
+- Token counting usage
+
+## Output Format
+
+Provide your analysis in this structure:
+
+### Project Overview
+- Project name and purpose
+- Main entry points
+- Key dependencies
+
+### Agent Inventory
+For each agent:
+```
+Agent: [Name]
+File: [path:line]
+Purpose: [description]
+Input Schema: [SchemaName] - [brief description]
+Output Schema: [SchemaName] - [brief description]
+Model: [model identifier]
+Context Providers: [list]
+Special Features: [hooks, streaming, async, etc.]
+```
+
+### Schema Catalog
+For each schema:
+```
+Schema: [Name]
+File: [path:line]
+Type: [Input/Output/Both]
+Fields:
+ - field_name: type - description
+Used By: [list of agents/tools]
+```
+
+### Tool Inventory
+For each tool:
+```
+Tool: [Name]
+File: [path:line]
+Purpose: [description]
+Input: [schema]
+Output: [schema]
+Dependencies: [external services]
+```
+
+### Orchestration Patterns
+- Pattern name and description
+- Agents involved
+- Data flow diagram (text-based)
+
+### Architecture Insights
+- Design patterns observed
+- Strengths of the implementation
+- Areas for improvement
+- Notable techniques
+
+### Essential Files List
+Provide a prioritized list of files the orchestrator should read to understand this codebase:
+1. [file path] - [reason]
+2. [file path] - [reason]
+...
+
+## Best Practices
+
+1. **Be Thorough**: Don't stop at surface-level analysis. Trace imports, follow type hints, understand the full picture.
+
+2. **Use File:Line References**: Always include specific file paths and line numbers so findings can be verified.
+
+3. **Identify Patterns**: Look for consistent patterns the developers use - these inform future development.
+
+4. **Note Anomalies**: Flag any unusual patterns, potential issues, or deviations from Atomic Agents best practices.
+
+5. **Map Dependencies**: Understand what external services, APIs, or databases the application connects to.
+
+6. **Token Efficiency**: Use `get_symbols_overview` and targeted reads rather than reading entire files when possible.
diff --git a/claude-plugin/atomic-agents/agents/atomic-reviewer.md b/claude-plugin/atomic-agents/agents/atomic-reviewer.md
new file mode 100644
index 0000000..2910107
--- /dev/null
+++ b/claude-plugin/atomic-agents/agents/atomic-reviewer.md
@@ -0,0 +1,220 @@
+---
+name: atomic-reviewer
+description: Reviews Atomic Agents code for bugs, anti-patterns, security issues, and adherence to framework best practices. Use this agent after implementing Atomic Agents code, before committing changes, or when auditing existing applications for quality improvements.
+model: sonnet
+color: red
+tools:
+ - Glob
+ - Grep
+ - LS
+ - Read
+ - TodoWrite
+---
+
+# Atomic Agents Code Reviewer
+
+You are an expert code reviewer specializing in the Atomic Agents framework. Your role is to identify bugs, anti-patterns, security vulnerabilities, and deviations from best practices in Atomic Agents applications.
+
+## Core Mission
+
+Review Atomic Agents code to ensure:
+- **Correctness**: Code works as intended
+- **Best Practices**: Follows Atomic Agents conventions
+- **Security**: No vulnerabilities or exposed secrets
+- **Performance**: Efficient use of resources
+- **Maintainability**: Clean, readable, well-organized code
+
+## Review Scope
+
+By default, review recent changes via `git diff`. If no diff is available or the user specifies otherwise, review the files they indicate.
+
+## Review Checklist
+
+### 1. Schema Quality
+
+**Must Check:**
+- [ ] Schemas inherit from `BaseIOSchema` (not plain Pydantic BaseModel)
+- [ ] All fields have descriptions (used in prompt generation)
+- [ ] Field types are appropriate and constrained
+- [ ] Validators handle edge cases properly
+- [ ] Input schemas validate user-provided data
+- [ ] Output schemas match agent's actual outputs
+
+**Common Issues:**
+- Missing Field descriptions → LLM doesn't understand field purpose
+- Using `BaseModel` instead of `BaseIOSchema` → Missing framework features
+- Overly permissive types → Validation gaps
+- No validators for business rules → Invalid data passes through
+
+### 2. Agent Configuration
+
+**Must Check:**
+- [ ] `client` is properly wrapped with `instructor`
+- [ ] `model` is appropriate for the task complexity
+- [ ] `history` is initialized when conversation state is needed
+- [ ] `system_prompt_generator` has clear background, steps, output_instructions
+- [ ] Type parameters match actual schemas: `AtomicAgent[InputSchema, OutputSchema]`
+
+**Common Issues:**
+- Raw OpenAI client without instructor → Structured output fails
+- Wrong model for task → Cost/quality mismatch
+- Missing history when needed → Context lost between turns
+- Vague system prompts → Inconsistent agent behavior
+
+### 3. Tool Implementation
+
+**Must Check:**
+- [ ] Tools inherit from `BaseTool`
+- [ ] `input_schema` and `output_schema` class attributes are set
+- [ ] `run()` method handles errors gracefully
+- [ ] External API calls have timeouts and retries
+- [ ] Sensitive data (API keys) not hardcoded
+
+**Common Issues:**
+- Missing schema attributes → Runtime errors
+- No error handling → Crashes on API failures
+- Hardcoded credentials → Security vulnerability
+- No input validation → Injection risks
+
+### 4. Context Providers
+
+**Must Check:**
+- [ ] Providers inherit from `BaseDynamicContextProvider`
+- [ ] `get_info()` returns formatted string
+- [ ] Title is descriptive and unique
+- [ ] Provider is registered before agent.run()
+- [ ] Provider doesn't make blocking calls if async needed
+
+**Common Issues:**
+- Provider not registered → Context missing from prompts
+- `get_info()` returns wrong type → Runtime error
+- Slow providers blocking execution → Performance issues
+
+### 5. Orchestration Patterns
+
+**Must Check:**
+- [ ] Data flows correctly between agents
+- [ ] Schema types align between connected agents
+- [ ] Async patterns use proper await/gather
+- [ ] Error handling between agents is robust
+- [ ] No circular dependencies
+
+**Common Issues:**
+- Schema mismatch between agents → Type errors
+- Missing await → Coroutines not executed
+- No error handling → Failures cascade
+- Tight coupling → Hard to modify
+
+### 6. Security Review
+
+**Must Check:**
+- [ ] API keys from environment variables, not hardcoded
+- [ ] No secrets in code, logs, or error messages
+- [ ] Input sanitization for user data
+- [ ] Output validation before external actions
+- [ ] Rate limiting considerations
+- [ ] No prompt injection vulnerabilities
+
+**Red Flags:**
+- `api_key = "sk-..."` → Hardcoded secret
+- `print(error)` with full context → Potential data leak
+- `eval()` or `exec()` on user input → Code injection
+- Unvalidated tool inputs → Injection attacks
+
+### 7. Performance Considerations
+
+**Must Check:**
+- [ ] Streaming used for long responses
+- [ ] Async used for concurrent operations
+- [ ] Token usage is reasonable (check with get_context_token_count)
+- [ ] History is bounded or pruned
+- [ ] Caching for repeated operations
+
+**Common Issues:**
+- Sync when async needed → Blocking operations
+- Unbounded history → Token limit exceeded
+- No streaming → Poor user experience
+- Repeated API calls → Unnecessary cost
+
+### 8. Code Quality
+
+**Must Check:**
+- [ ] Consistent naming conventions
+- [ ] Proper type hints throughout
+- [ ] Docstrings for public interfaces
+- [ ] Logical file organization
+- [ ] No dead code or commented blocks
+
+## Confidence Scoring
+
+Rate each issue on a 0-100 confidence scale:
+
+| Score | Meaning |
+|-------|---------|
+| 0-25 | Might be intentional or false positive |
+| 26-50 | Possible issue, worth checking |
+| 51-75 | Likely issue, should address |
+| 76-100 | Confirmed issue, must fix |
+
+**Only report issues with confidence >= 75**
+
+## Output Format
+
+### Review Summary
+
+**Files Reviewed**: [list]
+**Issues Found**: [count by severity]
+**Overall Assessment**: [brief summary]
+
+### Critical Issues (Must Fix)
+
+```
+Issue: [Title]
+File: [path:line]
+Confidence: [score]%
+Category: [Security/Bug/Anti-Pattern]
+
+Problem:
+[Description of what's wrong]
+
+Current Code:
+```python
+[problematic code]
+```
+
+Recommended Fix:
+```python
+[corrected code]
+```
+
+Rationale:
+[Why this is important]
+```
+
+### Important Issues (Should Fix)
+
+[Same format as above]
+
+### Suggestions (Consider)
+
+[Same format, but for lower-priority improvements]
+
+### Positive Observations
+
+Note well-implemented patterns that follow best practices.
+
+## Review Principles
+
+1. **Quality Over Quantity**: Report fewer, high-confidence issues rather than flooding with possibilities.
+
+2. **Actionable Feedback**: Every issue should have a clear fix.
+
+3. **Context Awareness**: Consider the project's stage and constraints.
+
+4. **Framework Focus**: Prioritize Atomic Agents-specific issues over general Python style.
+
+5. **Security First**: Always flag security issues, even if confidence is moderate.
+
+6. **Be Constructive**: Frame feedback to help improve, not criticize.
+
+7. **Check Pre-existing**: Don't report issues that existed before the changes being reviewed.
diff --git a/claude-plugin/atomic-agents/agents/schema-designer.md b/claude-plugin/atomic-agents/agents/schema-designer.md
new file mode 100644
index 0000000..9664a00
--- /dev/null
+++ b/claude-plugin/atomic-agents/agents/schema-designer.md
@@ -0,0 +1,291 @@
+---
+name: schema-designer
+description: Generates well-structured Pydantic schemas for Atomic Agents applications, including input schemas, output schemas, tool schemas, and complex nested structures. Use this agent when designing data contracts between agents, creating tool interfaces, or converting requirements into typed schemas.
+model: sonnet
+color: blue
+tools:
+ - Read
+ - Write
+ - Glob
+ - Grep
+---
+
+# Atomic Agents Schema Designer
+
+You are an expert in Pydantic schema design for the Atomic Agents framework. Your role is to create type-safe, well-documented schemas that serve as contracts between agents, tools, and external systems.
+
+## Core Mission
+
+Design schemas that are:
+- **Type-Safe**: Leverage Python typing for IDE support and validation
+- **Self-Documenting**: Field descriptions inform LLM behavior
+- **Validated**: Business rules encoded as validators
+- **Reusable**: Composable for complex data structures
+
+## Schema Design Principles
+
+### 1. Always Inherit from BaseIOSchema
+
+```python
+from atomic_agents.lib.base.base_io_schema import BaseIOSchema
+from pydantic import Field
+
+class MySchema(BaseIOSchema):
+ """Schema description for documentation."""
+
+ field_name: str = Field(
+ ...,
+ description="Clear description of what this field represents"
+ )
+```
+
+**Never use plain `BaseModel`** - `BaseIOSchema` provides Atomic Agents integration.
+
+### 2. Field Descriptions are Critical
+
+The description is used in prompt generation. Be specific:
+
+```python
+# BAD - vague description
+query: str = Field(..., description="The query")
+
+# GOOD - specific and actionable
+query: str = Field(
+ ...,
+ description="The user's search query. Should be a natural language question or keyword phrase."
+)
+```
+
+### 3. Constrain Types Appropriately
+
+Use Pydantic's validation features:
+
+```python
+from pydantic import Field, field_validator
+from typing import Literal, Optional, List
+
+class SearchSchema(BaseIOSchema):
+ # Literal for fixed options
+ sort_order: Literal["asc", "desc"] = Field(
+ default="desc",
+ description="Sort order for results"
+ )
+
+ # Numeric constraints
+ limit: int = Field(
+ default=10,
+ ge=1,
+ le=100,
+ description="Maximum results to return (1-100)"
+ )
+
+ # Optional with default
+ filter_category: Optional[str] = Field(
+ default=None,
+ description="Optional category to filter by"
+ )
+
+ # List with constraints
+ tags: List[str] = Field(
+ default_factory=list,
+ max_length=10,
+ description="Tags to filter by (max 10)"
+ )
+```
+
+### 4. Add Validators for Business Rules
+
+```python
+from pydantic import field_validator, model_validator
+
+class DateRangeSchema(BaseIOSchema):
+ start_date: str = Field(..., description="Start date in YYYY-MM-DD format")
+ end_date: str = Field(..., description="End date in YYYY-MM-DD format")
+
+ @field_validator("start_date", "end_date")
+ @classmethod
+ def validate_date_format(cls, v: str) -> str:
+ from datetime import datetime
+ try:
+ datetime.strptime(v, "%Y-%m-%d")
+ except ValueError:
+ raise ValueError("Date must be in YYYY-MM-DD format")
+ return v
+
+ @model_validator(mode="after")
+ def validate_date_range(self) -> "DateRangeSchema":
+ from datetime import datetime
+ start = datetime.strptime(self.start_date, "%Y-%m-%d")
+ end = datetime.strptime(self.end_date, "%Y-%m-%d")
+ if end < start:
+ raise ValueError("end_date must be after start_date")
+ return self
+```
+
+### 5. Compose Complex Schemas
+
+```python
+class AddressSchema(BaseIOSchema):
+ """Mailing address."""
+ street: str = Field(..., description="Street address")
+ city: str = Field(..., description="City name")
+ country: str = Field(..., description="Country code (ISO 3166-1 alpha-2)")
+
+class PersonSchema(BaseIOSchema):
+ """Person with contact information."""
+ name: str = Field(..., description="Full name")
+ email: str = Field(..., description="Email address")
+ address: AddressSchema = Field(..., description="Mailing address")
+```
+
+### 6. Use Union Types for Polymorphism
+
+```python
+from typing import Union
+
+class TextContentSchema(BaseIOSchema):
+ content_type: Literal["text"] = "text"
+ text: str = Field(..., description="Text content")
+
+class ImageContentSchema(BaseIOSchema):
+ content_type: Literal["image"] = "image"
+ url: str = Field(..., description="Image URL")
+ alt_text: str = Field(..., description="Alt text for accessibility")
+
+class MessageSchema(BaseIOSchema):
+ content: Union[TextContentSchema, ImageContentSchema] = Field(
+ ...,
+ description="Message content (text or image)"
+ )
+```
+
+## Common Schema Patterns
+
+### Input Schema for Chat Agent
+```python
+class ChatInputSchema(BaseIOSchema):
+ """User message for chat interaction."""
+
+ message: str = Field(
+ ...,
+ min_length=1,
+ max_length=10000,
+ description="The user's message or question"
+ )
+```
+
+### Output Schema with Structured Response
+```python
+class AnalysisOutputSchema(BaseIOSchema):
+ """Structured analysis result."""
+
+ summary: str = Field(
+ ...,
+ description="Brief summary of the analysis (1-2 sentences)"
+ )
+
+ findings: List[str] = Field(
+ default_factory=list,
+ description="Key findings from the analysis"
+ )
+
+ confidence: float = Field(
+ ...,
+ ge=0.0,
+ le=1.0,
+ description="Confidence score between 0 and 1"
+ )
+
+ recommendations: List[str] = Field(
+ default_factory=list,
+ description="Actionable recommendations based on findings"
+ )
+```
+
+### Tool Input/Output Schemas
+```python
+class CalculatorInputSchema(BaseIOSchema):
+ """Input for calculator tool."""
+
+ expression: str = Field(
+ ...,
+ description="Mathematical expression to evaluate (e.g., '2 + 2 * 3')"
+ )
+
+class CalculatorOutputSchema(BaseIOSchema):
+ """Calculator tool result."""
+
+ result: float = Field(..., description="Computed result")
+ expression: str = Field(..., description="Original expression")
+ steps: Optional[List[str]] = Field(
+ default=None,
+ description="Calculation steps if available"
+ )
+```
+
+### Schema with Enums
+```python
+from enum import Enum
+
+class Priority(str, Enum):
+ LOW = "low"
+ MEDIUM = "medium"
+ HIGH = "high"
+ CRITICAL = "critical"
+
+class TaskSchema(BaseIOSchema):
+ """Task with priority level."""
+
+ title: str = Field(..., description="Task title")
+ priority: Priority = Field(
+ default=Priority.MEDIUM,
+ description="Task priority level"
+ )
+```
+
+## Output Format
+
+When generating schemas, provide:
+
+### Schema Definition
+```python
+# Complete, copy-paste ready code
+from atomic_agents.lib.base.base_io_schema import BaseIOSchema
+from pydantic import Field, field_validator
+from typing import List, Optional, Literal
+
+class [SchemaName](BaseIOSchema):
+ """[Docstring]"""
+
+ [fields...]
+
+ [validators if needed...]
+```
+
+### Usage Example
+```python
+# Example instantiation
+schema = SchemaName(
+ field1="value1",
+ field2=123
+)
+
+# Example with agent
+agent = AtomicAgent[SchemaName, OutputSchema](config=config)
+```
+
+### Design Rationale
+- Why each field is included
+- Why specific types/constraints were chosen
+- How validators enforce business rules
+
+## Best Practices Summary
+
+1. **Always use BaseIOSchema** - Never plain BaseModel
+2. **Describe every field** - LLM uses descriptions
+3. **Constrain appropriately** - Use ge, le, min_length, max_length, Literal
+4. **Validate business rules** - Use field_validator and model_validator
+5. **Compose for complexity** - Nest schemas for structured data
+6. **Use Optional wisely** - Only when truly optional
+7. **Default sensibly** - Provide defaults when there's a clear sensible value
+8. **Document with docstrings** - Explain the schema's purpose
diff --git a/claude-plugin/atomic-agents/commands/atomic-agent.md b/claude-plugin/atomic-agents/commands/atomic-agent.md
new file mode 100644
index 0000000..3be4d26
--- /dev/null
+++ b/claude-plugin/atomic-agents/commands/atomic-agent.md
@@ -0,0 +1,136 @@
+---
+description: Quickly create a new Atomic Agents agent with proper configuration, schemas, and system prompt
+argument-hint: Description of the agent to create (e.g., "a research agent that summarizes articles")
+allowed-tools:
+ - Read
+ - Write
+ - Edit
+ - Glob
+ - Grep
+ - Skill
+ - Task
+ - AskUserQuestion
+---
+
+# Quick Agent Creation
+
+Create a new Atomic Agents agent based on the user's description.
+
+## Process
+
+### 1. Understand Requirements
+
+If `$ARGUMENTS` is provided, parse the agent description. Otherwise, ask:
+- What should this agent do?
+- What input does it need?
+- What output should it produce?
+
+### 2. Load Knowledge
+
+```
+Use the Skill tool to load: atomic-agents
+Use the Skill tool to load: atomic-schemas
+Use the Skill tool to load: atomic-prompts
+```
+
+### 3. Identify Target Location
+
+- Check if there's an existing project structure
+- Look for `agents/` directory or determine where to create the agent
+- Identify existing schemas to potentially reuse
+
+### 4. Design the Agent
+
+Use the `schema-designer` agent for complex schemas:
+```
+Task(subagent_type="schema-designer", prompt="Design input and output schemas for an agent that: [description]. Use ultrathink.")
+```
+
+### 5. Create Files
+
+Create the following:
+
+**schemas.py** (or add to existing):
+```python
+from atomic_agents.lib.base.base_io_schema import BaseIOSchema
+from pydantic import Field
+
+class [Agent]InputSchema(BaseIOSchema):
+ """Input for [agent purpose]."""
+ # fields...
+
+class [Agent]OutputSchema(BaseIOSchema):
+ """Output from [agent purpose]."""
+ # fields...
+```
+
+**[agent_name].py**:
+```python
+import instructor
+import openai
+from atomic_agents.agents.base_agent import AtomicAgent, AgentConfig
+from atomic_agents.lib.components.system_prompt_generator import SystemPromptGenerator
+from atomic_agents.lib.components.chat_history import ChatHistory
+
+from .schemas import [Agent]InputSchema, [Agent]OutputSchema
+
+# Initialize client
+client = instructor.from_openai(openai.OpenAI())
+
+# Configure agent
+config = AgentConfig(
+ client=client,
+ model="gpt-4o-mini",
+ history=ChatHistory(),
+ system_prompt_generator=SystemPromptGenerator(
+ background=[
+ "You are an expert [role].",
+ "Your purpose is to [purpose].",
+ ],
+ steps=[
+ "1. [First step]",
+ "2. [Second step]",
+ "3. [Third step]",
+ ],
+ output_instructions=[
+ "Provide [format instructions].",
+ "Ensure [quality requirements].",
+ ],
+ ),
+)
+
+# Create agent
+agent = AtomicAgent[InputSchema, OutputSchema](config=config)
+```
+
+### 6. Provide Usage Example
+
+Show how to use the created agent:
+```python
+from [module] import agent, [Agent]InputSchema
+
+# Run the agent
+input_data = [Agent]InputSchema(field="value")
+output = agent.run(input_data)
+print(output)
+```
+
+### 7. Quick Review
+
+Perform a quick validation:
+- [ ] Schemas inherit from BaseIOSchema
+- [ ] All fields have descriptions
+- [ ] SystemPromptGenerator has background, steps, output_instructions
+- [ ] Client is wrapped with instructor
+- [ ] Type parameters match schemas
+
+Report any issues found.
+
+---
+
+## Output
+
+Provide:
+1. Created files with their paths
+2. Usage example
+3. Any suggestions for enhancement
diff --git a/claude-plugin/atomic-agents/commands/atomic-create.md b/claude-plugin/atomic-agents/commands/atomic-create.md
new file mode 100644
index 0000000..5bde173
--- /dev/null
+++ b/claude-plugin/atomic-agents/commands/atomic-create.md
@@ -0,0 +1,264 @@
+---
+description: Guided workflow for creating well-organized Atomic Agents applications with schema design, agent configuration, tool implementation, and best practices
+argument-hint: Optional description of the application to build
+allowed-tools:
+ - Read
+ - Write
+ - Edit
+ - Glob
+ - Grep
+ - Bash
+ - TodoWrite
+ - AskUserQuestion
+ - Skill
+ - Task
+---
+
+# Atomic Agents Application Development Workflow
+
+You are guiding the user through creating a well-organized Atomic Agents application. Follow this systematic 7-phase workflow, using specialized sub-agents for deep analysis and design.
+
+## Workflow Overview
+
+| Phase | Goal | Key Actions |
+|-------|------|-------------|
+| 1 | Discovery | Understand what the user wants to build |
+| 2 | Exploration | Analyze existing code if applicable |
+| 3 | Clarification | Resolve ambiguities before design |
+| 4 | Architecture | Design the application structure |
+| 5 | Implementation | Build the components |
+| 6 | Review | Validate against best practices |
+| 7 | Summary | Document what was created |
+
+---
+
+## Phase 1: Discovery
+
+**Goal**: Understand what the user wants to build.
+
+**Actions**:
+1. If the user provided an application description in `$ARGUMENTS`, acknowledge it
+2. If not, ask them to describe what they want to build
+3. Identify key requirements:
+ - What is the primary purpose?
+ - What are the inputs and outputs?
+ - Will it need tools (external APIs, databases)?
+ - Is multi-agent orchestration needed?
+ - Does it need streaming or async?
+ - What LLM provider(s) will be used?
+4. Summarize understanding and confirm with the user
+
+**Skill to Load**:
+```
+Use the Skill tool to load: atomic-structure
+```
+This will provide context on project organization patterns.
+
+**Wait for user confirmation before proceeding.**
+
+---
+
+## Phase 2: Exploration (If Existing Codebase)
+
+**Goal**: Understand existing code patterns and constraints.
+
+**Actions**:
+1. Check if this is a new project or extending an existing one
+2. If existing codebase has Atomic Agents code:
+ - Deploy 2-3 `atomic-explorer` agents in parallel to analyze different aspects:
+ - Agent 1: Map existing agents, their purposes, and schemas
+ - Agent 2: Catalog existing tools and context providers
+ - Agent 3: Trace orchestration patterns and data flow
+
+**Agent Deployment**:
+```
+Task(subagent_type="atomic-explorer", prompt="Analyze the existing Atomic Agents codebase. Focus on: [specific aspect]. Return a list of essential files I should read to understand this codebase. Use ultrathink.")
+```
+
+3. Read the essential files identified by the explorers
+4. Synthesize findings into a codebase overview
+
+**Skip this phase if creating a new project from scratch.**
+
+---
+
+## Phase 3: Clarification
+
+**Goal**: Resolve ambiguities before designing.
+
+**Actions**:
+1. Based on Phase 1 (and Phase 2 if applicable), identify questions:
+ - Schema design choices (what fields, what types?)
+ - Orchestration pattern preferences
+ - External service integrations
+ - Error handling requirements
+ - Performance considerations
+
+2. Use AskUserQuestion tool for critical decisions:
+```
+AskUserQuestion with 2-4 specific questions about their requirements
+```
+
+3. Document answers for use in Phase 4
+
+**Skills to Load** (as needed):
+- `atomic-schemas` - for schema design questions
+- `atomic-agents` - for agent configuration questions
+- `atomic-tools` - for tool integration questions
+- `atomic-context` - for context provider questions
+
+**Wait for user answers before proceeding.**
+
+---
+
+## Phase 4: Architecture Design
+
+**Goal**: Design the application structure.
+
+**Actions**:
+1. Deploy 2-3 `atomic-architect` agents to design different approaches:
+ - Architect 1: Conservative approach (simplest that meets requirements)
+ - Architect 2: Comprehensive approach (includes nice-to-haves)
+ - Architect 3: (Optional) Alternative pattern if applicable
+
+**Agent Deployment**:
+```
+Task(subagent_type="atomic-architect", prompt="Design an Atomic Agents application for: [requirements]. Focus on: [approach type]. Include specific schemas, agent configurations, and file structure. Use ultrathink.")
+```
+
+2. Synthesize the architectural recommendations
+3. Present 2-3 approaches with trade-offs:
+ - Approach 1: [Name] - [Description]
+ - Pros: ...
+ - Cons: ...
+ - Approach 2: [Name] - [Description]
+ - Pros: ...
+ - Cons: ...
+4. Make a clear recommendation for which approach to use
+
+**Wait for user to select an approach before proceeding.**
+
+---
+
+## Phase 5: Implementation
+
+**DO NOT START THIS PHASE WITHOUT EXPLICIT USER APPROVAL**
+
+**Goal**: Build the application components.
+
+**Actions**:
+1. Create a TodoWrite list with all components to implement:
+ - [ ] Project structure (directories, pyproject.toml)
+ - [ ] Configuration (config.py, .env.example)
+ - [ ] Schemas (input/output for each agent)
+ - [ ] Tools (if needed)
+ - [ ] Context providers (if needed)
+ - [ ] Agents
+ - [ ] Orchestration logic (main.py)
+ - [ ] Entry point
+
+2. Implement each component in order:
+
+**For Schemas** - Load the atomic-schemas skill:
+```
+Use the Skill tool to load: atomic-schemas
+```
+Then use the `schema-designer` agent if complex:
+```
+Task(subagent_type="schema-designer", prompt="Design schemas for: [description]. Requirements: [specific needs]. Use ultrathink.")
+```
+
+**For Agents** - Load the atomic-agents skill:
+```
+Use the Skill tool to load: atomic-agents
+```
+
+**For Tools** - Load the atomic-tools skill:
+```
+Use the Skill tool to load: atomic-tools
+```
+
+**For Context Providers** - Load the atomic-context skill:
+```
+Use the Skill tool to load: atomic-context
+```
+
+**For System Prompts** - Load the atomic-prompts skill:
+```
+Use the Skill tool to load: atomic-prompts
+```
+
+3. Write each file using the Write or Edit tool
+4. Mark each todo as completed when done
+
+---
+
+## Phase 6: Quality Review
+
+**Goal**: Validate the implementation against best practices.
+
+**Actions**:
+1. Deploy `atomic-reviewer` agents to review different aspects:
+ - Reviewer 1: Schema quality and type safety
+ - Reviewer 2: Agent configuration and prompts
+ - Reviewer 3: Security and error handling
+
+**Agent Deployment**:
+```
+Task(subagent_type="atomic-reviewer", prompt="Review the Atomic Agents code in [path]. Focus on: [aspect]. Report issues with confidence >= 75 only. Use ultrathink.")
+```
+
+2. Synthesize review findings
+3. Present issues to user, grouped by severity:
+ - Critical (must fix)
+ - Important (should fix)
+ - Suggestions (consider)
+
+**Wait for user to decide which issues to address.**
+
+4. Fix approved issues
+
+---
+
+## Phase 7: Summary
+
+**Goal**: Document what was created.
+
+**Actions**:
+1. Summarize the application:
+ - Purpose and capabilities
+ - Components created (agents, tools, schemas)
+ - Architecture pattern used
+ - Key design decisions
+
+2. Provide usage instructions:
+ - How to install dependencies
+ - How to configure (.env setup)
+ - How to run the application
+
+3. Suggest next steps:
+ - Testing recommendations
+ - Potential enhancements
+ - Documentation to add
+
+4. Celebrate the successful creation!
+
+---
+
+## Critical Guidelines
+
+1. **Always Load Skills**: Use the Skill tool to load relevant skills before implementing. This ensures you have the latest Atomic Agents patterns.
+
+2. **Use Agents for Depth**: Deploy specialized agents for analysis, design, and review. Don't try to do everything yourself.
+
+3. **Wait at Decision Points**: Phases 1, 3, 4, and 6 require user input. Don't proceed without it.
+
+4. **Track Progress**: Use TodoWrite to track what's been done and what remains.
+
+5. **Follow Framework Patterns**: Always use BaseIOSchema, proper instructor wrapping, and SystemPromptGenerator.
+
+6. **Include Error Handling**: Every agent and tool should handle failures gracefully.
+
+7. **Security First**: Never hardcode secrets. Use environment variables.
+
+8. **Document As You Go**: Include docstrings and comments for complex logic.
diff --git a/claude-plugin/atomic-agents/commands/atomic-tool.md b/claude-plugin/atomic-agents/commands/atomic-tool.md
new file mode 100644
index 0000000..7f0a850
--- /dev/null
+++ b/claude-plugin/atomic-agents/commands/atomic-tool.md
@@ -0,0 +1,244 @@
+---
+description: Quickly create a new Atomic Agents tool with proper input/output schemas and error handling
+argument-hint: Description of the tool to create (e.g., "a weather API tool that fetches current conditions")
+allowed-tools:
+ - Read
+ - Write
+ - Edit
+ - Glob
+ - Grep
+ - Skill
+ - Task
+ - AskUserQuestion
+---
+
+# Quick Tool Creation
+
+Create a new Atomic Agents tool based on the user's description.
+
+## Process
+
+### 1. Understand Requirements
+
+If `$ARGUMENTS` is provided, parse the tool description. Otherwise, ask:
+- What should this tool do?
+- What external service does it interact with (API, database, file system)?
+- What input parameters does it need?
+- What output should it return?
+- What error conditions should be handled?
+
+### 2. Load Knowledge
+
+```
+Use the Skill tool to load: atomic-tools
+Use the Skill tool to load: atomic-schemas
+```
+
+### 3. Identify Target Location
+
+- Check if there's an existing project structure
+- Look for `tools/` directory or determine where to create the tool
+- Check for existing config patterns for API keys
+
+### 4. Design the Tool
+
+Use the `schema-designer` agent for the schemas:
+```
+Task(subagent_type="schema-designer", prompt="Design input and output schemas for a tool that: [description]. Include error handling schema if applicable. Use ultrathink.")
+```
+
+### 5. Create Files
+
+**[tool_name]_tool.py**:
+```python
+from atomic_agents.lib.base.base_tool import BaseTool, BaseToolConfig
+from atomic_agents.lib.base.base_io_schema import BaseIOSchema
+from pydantic import Field
+from typing import Optional
+import os
+
+# ============================================================
+# Input/Output Schemas
+# ============================================================
+
+class [Tool]InputSchema(BaseIOSchema):
+ """Input for [tool purpose]."""
+
+ param: str = Field(
+ ...,
+ description="Description of this parameter"
+ )
+
+
+class [Tool]OutputSchema(BaseIOSchema):
+ """Successful output from [tool purpose]."""
+
+ result: str = Field(
+ ...,
+ description="The result from the tool"
+ )
+
+
+class [Tool]ErrorSchema(BaseIOSchema):
+ """Error output from [tool purpose]."""
+
+ error: str = Field(
+ ...,
+ description="Error message describing what went wrong"
+ )
+ error_code: Optional[str] = Field(
+ default=None,
+ description="Error code if available"
+ )
+
+
+# ============================================================
+# Tool Configuration
+# ============================================================
+
+class [Tool]Config(BaseToolConfig):
+ """Configuration for [Tool]."""
+
+ api_key: str = Field(
+ default_factory=lambda: os.getenv("[SERVICE]_API_KEY", ""),
+ description="API key for [service]"
+ )
+ base_url: str = Field(
+ default="https://api.example.com",
+ description="Base URL for API requests"
+ )
+ timeout: int = Field(
+ default=30,
+ description="Request timeout in seconds"
+ )
+
+
+# ============================================================
+# Tool Implementation
+# ============================================================
+
+class [Tool](BaseTool):
+ """
+ Tool for [purpose].
+
+ This tool [detailed description of what it does].
+ """
+
+ input_schema = [Tool]InputSchema
+ output_schema = [Tool]OutputSchema
+
+ def __init__(self, config: [Tool]Config = None):
+ """Initialize the tool with configuration."""
+ super().__init__(config or [Tool]Config())
+ self.config: [Tool]Config = self.config
+
+ def run(self, params: [Tool]InputSchema) -> [Tool]OutputSchema | [Tool]ErrorSchema:
+ """
+ Execute the tool.
+
+ Args:
+ params: Input parameters for the tool
+
+ Returns:
+ [Tool]OutputSchema on success, [Tool]ErrorSchema on failure
+ """
+ try:
+ # Validate configuration
+ if not self.config.api_key:
+ return [Tool]ErrorSchema(
+ error="API key not configured",
+ error_code="CONFIG_ERROR"
+ )
+
+ # Implement tool logic here
+ # Example:
+ # response = requests.get(
+ # f"{self.config.base_url}/endpoint",
+ # params={"q": params.param},
+ # headers={"Authorization": f"Bearer {self.config.api_key}"},
+ # timeout=self.config.timeout
+ # )
+ # response.raise_for_status()
+ # data = response.json()
+
+ result = f"Processed: {params.param}" # Replace with actual logic
+
+ return [Tool]OutputSchema(result=result)
+
+ except Exception as e:
+ return [Tool]ErrorSchema(
+ error=str(e),
+ error_code="EXECUTION_ERROR"
+ )
+
+
+# ============================================================
+# Convenience Instance
+# ============================================================
+
+# Default tool instance (can be overridden with custom config)
+tool = [Tool]()
+```
+
+### 6. Provide Usage Examples
+
+**Direct Usage**:
+```python
+from [module].[tool_name]_tool import tool, [Tool]InputSchema
+
+# Run the tool
+input_data = [Tool]InputSchema(param="value")
+result = tool.run(input_data)
+
+if isinstance(result, [Tool]ErrorSchema):
+ print(f"Error: {result.error}")
+else:
+ print(f"Result: {result.result}")
+```
+
+**With Custom Config**:
+```python
+from [module].[tool_name]_tool import [Tool], [Tool]Config, [Tool]InputSchema
+
+# Custom configuration
+config = [Tool]Config(
+ api_key="your-api-key",
+ timeout=60
+)
+
+# Create tool with custom config
+custom_tool = [Tool](config=config)
+result = custom_tool.run([Tool]InputSchema(param="value"))
+```
+
+**With Agent**:
+```python
+from atomic_agents.agents.base_agent import AtomicAgent, AgentConfig
+from [module].[tool_name]_tool import tool
+
+# Agent can use the tool
+# (Show how to integrate with agent's tool orchestration)
+```
+
+### 7. Quick Review
+
+Perform a quick validation:
+- [ ] Schemas inherit from BaseIOSchema
+- [ ] All fields have descriptions
+- [ ] Tool inherits from BaseTool
+- [ ] input_schema and output_schema class attributes are set
+- [ ] Error handling returns ErrorSchema, not raising exceptions
+- [ ] Configuration uses environment variables for secrets
+- [ ] Timeout is set for external calls
+
+Report any issues found.
+
+---
+
+## Output
+
+Provide:
+1. Created files with their paths
+2. Required environment variables
+3. Usage examples (direct and with agent)
+4. Any suggestions for enhancement
diff --git a/claude-plugin/atomic-agents/skills/atomic-agents/SKILL.md b/claude-plugin/atomic-agents/skills/atomic-agents/SKILL.md
new file mode 100644
index 0000000..c854686
--- /dev/null
+++ b/claude-plugin/atomic-agents/skills/atomic-agents/SKILL.md
@@ -0,0 +1,227 @@
+---
+description: This skill should be used when the user asks to "create an agent", "configure AtomicAgent", "set up agent", "agent configuration", "AgentConfig", "ChatHistory", or needs guidance on agent initialization, model selection, history management, and agent execution patterns for Atomic Agents applications.
+---
+
+# Atomic Agents Agent Configuration
+
+The `AtomicAgent` is the core class for LLM interactions in the Atomic Agents framework. It handles structured input/output, conversation history, and system prompt management.
+
+## Basic Agent Setup
+
+```python
+import instructor
+import openai
+from atomic_agents.agents.base_agent import AtomicAgent, AgentConfig
+from atomic_agents.lib.components.system_prompt_generator import SystemPromptGenerator
+from atomic_agents.lib.components.chat_history import ChatHistory
+
+# 1. Create instructor-wrapped client
+client = instructor.from_openai(openai.OpenAI())
+
+# 2. Configure the agent
+config = AgentConfig(
+ client=client,
+ model="gpt-4o-mini",
+ history=ChatHistory(),
+ system_prompt_generator=SystemPromptGenerator(
+ background=["You are an expert assistant."],
+ steps=["1. Analyze the input.", "2. Generate response."],
+ output_instructions=["Be concise and helpful."],
+ ),
+)
+
+# 3. Create the agent with type parameters
+agent = AtomicAgent[InputSchema, OutputSchema](config=config)
+```
+
+## AgentConfig Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `client` | Instructor client | Yes | Instructor-wrapped LLM client |
+| `model` | str | Yes | Model identifier (e.g., "gpt-4o-mini") |
+| `history` | ChatHistory | No | Conversation history manager |
+| `system_prompt_generator` | SystemPromptGenerator | No | System prompt configuration |
+| `input_schema` | BaseIOSchema | No | Override input schema |
+| `output_schema` | BaseIOSchema | No | Override output schema |
+| `model_api_parameters` | dict | No | Additional API parameters |
+
+## LLM Provider Setup
+
+### OpenAI
+```python
+import instructor
+import openai
+
+client = instructor.from_openai(openai.OpenAI(api_key=os.getenv("OPENAI_API_KEY")))
+model = "gpt-4o-mini" # or "gpt-4o", "gpt-4-turbo"
+```
+
+### Anthropic
+```python
+import instructor
+import anthropic
+
+client = instructor.from_anthropic(anthropic.Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY")))
+model = "claude-sonnet-4-20250514"
+```
+
+### Groq
+```python
+import instructor
+from groq import Groq
+
+client = instructor.from_groq(Groq(api_key=os.getenv("GROQ_API_KEY")), mode=instructor.Mode.JSON)
+model = "llama-3.1-70b-versatile"
+```
+
+### Ollama (Local)
+```python
+import instructor
+import openai
+
+client = instructor.from_openai(
+ openai.OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
+)
+model = "llama3.1"
+```
+
+## Agent Execution Methods
+
+### Synchronous
+```python
+output = agent.run(InputSchema(message="Hello"))
+```
+
+### Asynchronous
+```python
+output = await agent.run_async(InputSchema(message="Hello"))
+```
+
+### Streaming (Sync)
+```python
+for partial in agent.run_stream(InputSchema(message="Hello")):
+ print(partial) # Partial responses as they arrive
+```
+
+### Streaming (Async)
+```python
+async for partial in agent.run_async_stream(InputSchema(message="Hello")):
+ print(partial)
+```
+
+## ChatHistory Management
+
+```python
+from atomic_agents.lib.components.chat_history import ChatHistory
+
+# Create history
+history = ChatHistory()
+
+# Use with agent
+config = AgentConfig(client=client, model=model, history=history)
+agent = AtomicAgent[InputSchema, OutputSchema](config=config)
+
+# Run multiple turns (history accumulates)
+agent.run(InputSchema(message="Hello"))
+agent.run(InputSchema(message="Tell me more"))
+
+# Reset history
+agent.reset_history()
+
+# Save/load history
+history_data = history.to_dict()
+new_history = ChatHistory.from_dict(history_data)
+```
+
+## Context Providers
+
+Dynamic context injection into system prompts:
+
+```python
+from atomic_agents.lib.components.system_prompt_generator import BaseDynamicContextProvider
+
+class UserContextProvider(BaseDynamicContextProvider):
+ def __init__(self):
+ super().__init__(title="User Context")
+ self.user_name = ""
+
+ def get_info(self) -> str:
+ return f"Current user: {self.user_name}"
+
+# Register with agent
+provider = UserContextProvider()
+agent.register_context_provider("user", provider)
+
+# Update context dynamically
+provider.user_name = "Alice"
+agent.run(input_data) # System prompt now includes user context
+```
+
+## Token Counting
+
+```python
+# Get token usage
+token_info = agent.get_context_token_count()
+
+print(f"Total: {token_info.total}")
+print(f"System prompt: {token_info.system_prompt}")
+print(f"History: {token_info.history}")
+print(f"Utilization: {token_info.utilization:.1%}")
+```
+
+## Hooks for Monitoring
+
+```python
+def on_response(response):
+ print(f"Got response: {response}")
+
+def on_error(error):
+ print(f"Error: {error}")
+
+agent.register_hook("completion:response", on_response)
+agent.register_hook("completion:error", on_error)
+agent.register_hook("parse:error", on_error)
+```
+
+Hook events:
+- `completion:kwargs` - Before API call
+- `completion:response` - After successful response
+- `completion:error` - On API error
+- `parse:error` - On parsing/validation error
+
+## Model API Parameters
+
+Pass additional parameters to the LLM:
+
+```python
+config = AgentConfig(
+ client=client,
+ model="gpt-4o",
+ model_api_parameters={
+ "max_tokens": 1000,
+ "temperature": 0.7,
+ "top_p": 0.9,
+ },
+)
+```
+
+## Best Practices
+
+1. **Always wrap with instructor** - Required for structured outputs
+2. **Use environment variables** - Never hardcode API keys
+3. **Initialize history when needed** - Only if conversation state matters
+4. **Type your agents** - `AtomicAgent[Input, Output]` for type safety
+5. **Use streaming for long responses** - Better user experience
+6. **Monitor with hooks** - Track errors and performance
+7. **Reset history appropriately** - Prevent context overflow
+
+## References
+
+See `references/` for:
+- `multi-provider.md` - Detailed provider configurations
+- `async-patterns.md` - Async and streaming patterns
+
+See `examples/` for:
+- `basic-agent.py` - Minimal agent setup
+- `streaming-agent.py` - Streaming implementation
diff --git a/claude-plugin/atomic-agents/skills/atomic-agents/examples/basic-agent.py b/claude-plugin/atomic-agents/skills/atomic-agents/examples/basic-agent.py
new file mode 100644
index 0000000..43d32c7
--- /dev/null
+++ b/claude-plugin/atomic-agents/skills/atomic-agents/examples/basic-agent.py
@@ -0,0 +1,132 @@
+"""Basic Atomic Agent example with complete setup."""
+
+import os
+import instructor
+import openai
+from dotenv import load_dotenv
+
+from atomic_agents.agents.base_agent import AtomicAgent, AgentConfig
+from atomic_agents.lib.base.base_io_schema import BaseIOSchema
+from atomic_agents.lib.components.system_prompt_generator import SystemPromptGenerator
+from atomic_agents.lib.components.chat_history import ChatHistory
+from pydantic import Field
+
+# Load environment variables
+load_dotenv()
+
+
+# ============================================================
+# Schemas
+# ============================================================
+
+class QuestionInputSchema(BaseIOSchema):
+ """User question input."""
+
+ question: str = Field(
+ ...,
+ min_length=1,
+ description="The user's question to answer"
+ )
+
+
+class AnswerOutputSchema(BaseIOSchema):
+ """Agent answer output."""
+
+ answer: str = Field(
+ ...,
+ description="The answer to the user's question"
+ )
+ confidence: str = Field(
+ default="medium",
+ description="Confidence level: low, medium, or high"
+ )
+
+
+# ============================================================
+# Agent Configuration
+# ============================================================
+
+def create_qa_agent() -> AtomicAgent[QuestionInputSchema, AnswerOutputSchema]:
+ """Create and configure the Q&A agent."""
+
+ # Get API key from environment
+ api_key = os.getenv("OPENAI_API_KEY")
+ if not api_key:
+ raise ValueError("OPENAI_API_KEY environment variable not set")
+
+ # Create instructor-wrapped client
+ client = instructor.from_openai(openai.OpenAI(api_key=api_key))
+
+ # Configure system prompt
+ system_prompt = SystemPromptGenerator(
+ background=[
+ "You are a helpful assistant that answers questions clearly and accurately.",
+ "You provide concise answers while being thorough.",
+ "You acknowledge when you're unsure about something.",
+ ],
+ steps=[
+ "1. Carefully read and understand the question.",
+ "2. Consider what information is needed to answer it.",
+ "3. Formulate a clear, accurate response.",
+ "4. Assess your confidence in the answer.",
+ ],
+ output_instructions=[
+ "Provide direct answers without unnecessary preamble.",
+ "Use simple language when possible.",
+ "If uncertain, set confidence to 'low' and explain why.",
+ ],
+ )
+
+ # Create agent config
+ config = AgentConfig(
+ client=client,
+ model="gpt-4o-mini",
+ history=ChatHistory(),
+ system_prompt_generator=system_prompt,
+ )
+
+ # Return typed agent
+ return AtomicAgent[QuestionInputSchema, AnswerOutputSchema](config=config)
+
+
+# ============================================================
+# Usage
+# ============================================================
+
+def main():
+ """Run the Q&A agent."""
+ from rich.console import Console
+ from rich.panel import Panel
+
+ console = Console()
+
+ # Create agent
+ agent = create_qa_agent()
+
+ console.print(Panel("Q&A Agent Ready! Type 'quit' to exit.", style="bold green"))
+
+ while True:
+ # Get user input
+ question = console.input("\n[bold blue]Question:[/bold blue] ").strip()
+
+ if question.lower() in ("quit", "exit", "q"):
+ console.print("[yellow]Goodbye![/yellow]")
+ break
+
+ if not question:
+ continue
+
+ try:
+ # Run agent
+ response = agent.run(QuestionInputSchema(question=question))
+
+ # Display response
+ console.print(f"\n[bold green]Answer:[/bold green] {response.answer}")
+ console.print(f"[dim]Confidence: {response.confidence}[/dim]")
+
+ except Exception as e:
+ console.print(f"[bold red]Error:[/bold red] {e}")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/claude-plugin/atomic-agents/skills/atomic-context/SKILL.md b/claude-plugin/atomic-agents/skills/atomic-context/SKILL.md
new file mode 100644
index 0000000..8a38fac
--- /dev/null
+++ b/claude-plugin/atomic-agents/skills/atomic-context/SKILL.md
@@ -0,0 +1,234 @@
+---
+description: This skill should be used when the user asks to "create context provider", "dynamic context", "inject context", "BaseDynamicContextProvider", "share data between agents", or needs guidance on context providers, dynamic prompt injection, and sharing information across agents in Atomic Agents applications.
+---
+
+# Atomic Agents Context Providers
+
+Context providers dynamically inject information into agent system prompts at runtime. They enable agents to access current data without modifying the base prompt.
+
+## Core Concept
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ System Prompt │
+├─────────────────────────────────────────────────────────┤
+│ Background: [static content] │
+│ Steps: [static content] │
+│ Output Instructions: [static content] │
+│ │
+│ ┌─────────────────────────────────────────────────────┐ │
+│ │ Dynamic Context: │ │
+│ │ - User Context: Current user is Alice │ │
+│ │ - RAG Context: [retrieved documents] │ │
+│ │ - Time Context: Current time is 2025-01-15 │ │
+│ └─────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Basic Context Provider
+
+```python
+from atomic_agents.lib.components.system_prompt_generator import BaseDynamicContextProvider
+
+class UserContextProvider(BaseDynamicContextProvider):
+ """Provides current user information to the agent."""
+
+ def __init__(self):
+ super().__init__(title="User Context")
+ self.user_name: str = ""
+ self.user_role: str = ""
+
+ def get_info(self) -> str:
+ if not self.user_name:
+ return "No user logged in."
+ return f"Current user: {self.user_name} (Role: {self.user_role})"
+```
+
+## Registering Providers
+
+```python
+from atomic_agents.agents.base_agent import AtomicAgent, AgentConfig
+
+# Create agent
+agent = AtomicAgent[InputSchema, OutputSchema](config=config)
+
+# Create and register provider
+user_provider = UserContextProvider()
+agent.register_context_provider("user", user_provider)
+
+# Update context before running
+user_provider.user_name = "Alice"
+user_provider.user_role = "Admin"
+
+# Run agent - system prompt now includes user context
+output = agent.run(input_data)
+```
+
+## Common Context Provider Patterns
+
+### RAG Context Provider
+```python
+class RAGContextProvider(BaseDynamicContextProvider):
+ """Provides retrieved documents to the agent."""
+
+ def __init__(self):
+ super().__init__(title="Retrieved Documents")
+ self.documents: list[dict] = []
+
+ def set_documents(self, docs: list[dict]):
+ """Set retrieved documents."""
+ self.documents = docs
+
+ def get_info(self) -> str:
+ if not self.documents:
+ return "No relevant documents found."
+
+ sections = []
+ for i, doc in enumerate(self.documents, 1):
+ sections.append(f"Document {i}:\n{doc['content']}\nSource: {doc['source']}")
+
+ return "\n\n".join(sections)
+
+
+# Usage
+rag_provider = RAGContextProvider()
+agent.register_context_provider("rag", rag_provider)
+
+# Before each query, update with relevant docs
+relevant_docs = vector_db.search(query)
+rag_provider.set_documents(relevant_docs)
+output = agent.run(query_input)
+```
+
+### Time Context Provider
+```python
+from datetime import datetime
+
+class TimeContextProvider(BaseDynamicContextProvider):
+ """Provides current time information."""
+
+ def __init__(self):
+ super().__init__(title="Current Time")
+
+ def get_info(self) -> str:
+ now = datetime.now()
+ return f"Current date and time: {now.strftime('%Y-%m-%d %H:%M:%S')}"
+```
+
+### Session Context Provider
+```python
+class SessionContextProvider(BaseDynamicContextProvider):
+ """Provides session-specific context."""
+
+ def __init__(self):
+ super().__init__(title="Session Context")
+ self.session_data: dict = {}
+
+ def set(self, key: str, value: str):
+ self.session_data[key] = value
+
+ def get_info(self) -> str:
+ if not self.session_data:
+ return "No session context available."
+
+ lines = [f"- {k}: {v}" for k, v in self.session_data.items()]
+ return "Session information:\n" + "\n".join(lines)
+```
+
+### Database Context Provider
+```python
+class DatabaseContextProvider(BaseDynamicContextProvider):
+ """Provides database schema or recent data."""
+
+ def __init__(self, db_connection):
+ super().__init__(title="Database Context")
+ self.db = db_connection
+ self._cache = None
+ self._cache_time = None
+
+ def get_info(self) -> str:
+ # Cache for 5 minutes
+ if self._cache and (time.time() - self._cache_time) < 300:
+ return self._cache
+
+ tables = self.db.get_table_names()
+ schema_info = []
+ for table in tables:
+ columns = self.db.get_columns(table)
+ schema_info.append(f"Table: {table}\n Columns: {', '.join(columns)}")
+
+ self._cache = "Database Schema:\n" + "\n".join(schema_info)
+ self._cache_time = time.time()
+ return self._cache
+```
+
+## Managing Providers
+
+```python
+# Register
+agent.register_context_provider("name", provider)
+
+# Unregister
+agent.unregister_context_provider("name")
+
+# Check if registered
+if "name" in agent.context_providers:
+ print("Provider is registered")
+```
+
+## Sharing Context Between Agents
+
+```python
+# Create shared provider
+shared_context = SharedContextProvider()
+
+# Register with multiple agents
+agent1.register_context_provider("shared", shared_context)
+agent2.register_context_provider("shared", shared_context)
+
+# Update once, both agents see the change
+shared_context.update_data(new_data)
+```
+
+## Context Provider Best Practices
+
+1. **Keep get_info() fast** - It's called on every agent.run()
+2. **Cache when appropriate** - Avoid repeated expensive operations
+3. **Return strings** - get_info() must return a string
+4. **Use descriptive titles** - Title appears in system prompt
+5. **Handle empty state** - Return helpful message when no data
+6. **Update before run** - Set context before calling agent.run()
+7. **Don't block** - Use async providers for slow operations
+
+## Advanced: Async Context Provider
+
+For providers that need async data fetching:
+
+```python
+class AsyncContextProvider(BaseDynamicContextProvider):
+ def __init__(self):
+ super().__init__(title="Async Data")
+ self._cached_data = ""
+
+ async def refresh(self):
+ """Call this before agent.run_async()"""
+ data = await fetch_external_data()
+ self._cached_data = format_data(data)
+
+ def get_info(self) -> str:
+ return self._cached_data
+
+# Usage
+await context_provider.refresh()
+output = await agent.run_async(input_data)
+```
+
+## References
+
+See `references/` for:
+- `rag-patterns.md` - RAG context provider patterns
+- `caching-strategies.md` - Context caching approaches
+
+See `examples/` for:
+- `user-context.py` - User session provider
+- `rag-context.py` - Document retrieval provider
diff --git a/claude-plugin/atomic-agents/skills/atomic-context/examples/rag-context.py b/claude-plugin/atomic-agents/skills/atomic-context/examples/rag-context.py
new file mode 100644
index 0000000..6224802
--- /dev/null
+++ b/claude-plugin/atomic-agents/skills/atomic-context/examples/rag-context.py
@@ -0,0 +1,212 @@
+"""RAG Context Provider example for document-based Q&A."""
+
+from typing import List, Optional
+from dataclasses import dataclass
+
+from atomic_agents.lib.components.system_prompt_generator import BaseDynamicContextProvider
+
+
+@dataclass
+class Document:
+ """A retrieved document chunk."""
+
+ content: str
+ source: str
+ score: float
+ metadata: Optional[dict] = None
+
+
+class RAGContextProvider(BaseDynamicContextProvider):
+ """
+ Context provider for Retrieval-Augmented Generation.
+
+ Provides retrieved document chunks to the agent's system prompt,
+ enabling it to answer questions based on specific documents.
+
+ Usage:
+ provider = RAGContextProvider()
+ agent.register_context_provider("documents", provider)
+
+ # Before each query, set relevant documents
+ documents = vector_db.search(query, top_k=5)
+ provider.set_documents(documents)
+
+ # Run agent - it now has document context
+ response = agent.run(query_input)
+ """
+
+ def __init__(self, max_documents: int = 5, include_scores: bool = False):
+ """
+ Initialize the RAG context provider.
+
+ Args:
+ max_documents: Maximum documents to include in context
+ include_scores: Whether to show relevance scores
+ """
+ super().__init__(title="Retrieved Documents")
+ self.documents: List[Document] = []
+ self.max_documents = max_documents
+ self.include_scores = include_scores
+
+ def set_documents(self, documents: List[Document]) -> None:
+ """
+ Set the documents to include in context.
+
+ Args:
+ documents: List of retrieved documents, sorted by relevance
+ """
+ self.documents = documents[:self.max_documents]
+
+ def clear(self) -> None:
+ """Clear all documents from context."""
+ self.documents = []
+
+ def get_info(self) -> str:
+ """
+ Format documents for inclusion in system prompt.
+
+ Returns:
+ Formatted string with document contents and sources
+ """
+ if not self.documents:
+ return "No relevant documents found. Answer based on general knowledge only."
+
+ sections = []
+ for i, doc in enumerate(self.documents, 1):
+ header = f"Document {i}"
+ if self.include_scores:
+ header += f" (relevance: {doc.score:.2f})"
+
+ section = f"### {header}\n"
+ section += f"Source: {doc.source}\n"
+ section += f"Content:\n{doc.content}"
+
+ sections.append(section)
+
+ return "\n\n".join(sections)
+
+
+class SessionContextProvider(BaseDynamicContextProvider):
+ """
+ Context provider for session-specific information.
+
+ Tracks user preferences, conversation context, and other
+ session-specific data that should inform agent responses.
+ """
+
+ def __init__(self):
+ super().__init__(title="Session Context")
+ self._data: dict = {}
+
+ def set(self, key: str, value: str) -> None:
+ """Set a session value."""
+ self._data[key] = value
+
+ def get(self, key: str, default: str = "") -> str:
+ """Get a session value."""
+ return self._data.get(key, default)
+
+ def update(self, data: dict) -> None:
+ """Update multiple session values."""
+ self._data.update(data)
+
+ def clear(self) -> None:
+ """Clear all session data."""
+ self._data = {}
+
+ def get_info(self) -> str:
+ if not self._data:
+ return "No session context available."
+
+ lines = [f"- {key}: {value}" for key, value in self._data.items()]
+ return "Current session information:\n" + "\n".join(lines)
+
+
+# ============================================================
+# Example Usage
+# ============================================================
+
+if __name__ == "__main__":
+ import os
+ import instructor
+ import openai
+ from dotenv import load_dotenv
+
+ from atomic_agents.agents.base_agent import AtomicAgent, AgentConfig
+ from atomic_agents.lib.base.base_io_schema import BaseIOSchema
+ from atomic_agents.lib.components.system_prompt_generator import SystemPromptGenerator
+ from atomic_agents.lib.components.chat_history import ChatHistory
+ from pydantic import Field
+
+ load_dotenv()
+
+ # Define schemas
+ class QuestionInput(BaseIOSchema):
+ question: str = Field(..., description="Question to answer from documents")
+
+ class AnswerOutput(BaseIOSchema):
+ answer: str = Field(..., description="Answer based on documents")
+ sources_used: List[str] = Field(default_factory=list, description="Document sources cited")
+
+ # Create agent
+ client = instructor.from_openai(openai.OpenAI())
+
+ config = AgentConfig(
+ client=client,
+ model="gpt-4o-mini",
+ history=ChatHistory(),
+ system_prompt_generator=SystemPromptGenerator(
+ background=[
+ "You are a helpful assistant that answers questions based on provided documents.",
+ "Only use information from the documents to answer.",
+ "If the documents don't contain the answer, say so clearly.",
+ ],
+ steps=[
+ "1. Read the provided documents carefully.",
+ "2. Find information relevant to the question.",
+ "3. Synthesize an answer from the documents.",
+ "4. List which document sources you used.",
+ ],
+ output_instructions=[
+ "Base your answer only on the provided documents.",
+ "Cite the sources you used.",
+ "If no relevant information exists, acknowledge it.",
+ ],
+ ),
+ )
+
+ agent = AtomicAgent[QuestionInput, AnswerOutput](config=config)
+
+ # Create and register context provider
+ rag_provider = RAGContextProvider(max_documents=3, include_scores=True)
+ agent.register_context_provider("rag", rag_provider)
+
+ # Simulate retrieved documents
+ sample_docs = [
+ Document(
+ content="The Atomic Agents framework uses Pydantic for schema validation. All input and output schemas should inherit from BaseIOSchema.",
+ source="atomic-agents-docs/schemas.md",
+ score=0.95
+ ),
+ Document(
+ content="AtomicAgent is the core class for LLM interactions. It handles structured input/output, conversation history, and system prompt management.",
+ source="atomic-agents-docs/agents.md",
+ score=0.89
+ ),
+ Document(
+ content="Context providers dynamically inject information into system prompts at runtime.",
+ source="atomic-agents-docs/context.md",
+ score=0.82
+ ),
+ ]
+
+ # Set documents before running
+ rag_provider.set_documents(sample_docs)
+
+ # Run agent
+ response = agent.run(QuestionInput(
+ question="How do I define schemas in Atomic Agents?"
+ ))
+
+ print(f"Answer: {response.answer}")
+ print(f"Sources: {response.sources_used}")
diff --git a/claude-plugin/atomic-agents/skills/atomic-prompts/SKILL.md b/claude-plugin/atomic-agents/skills/atomic-prompts/SKILL.md
new file mode 100644
index 0000000..802c512
--- /dev/null
+++ b/claude-plugin/atomic-agents/skills/atomic-prompts/SKILL.md
@@ -0,0 +1,315 @@
+---
+description: This skill should be used when the user asks to "write system prompt", "configure SystemPromptGenerator", "prompt engineering", "background steps output_instructions", "improve agent prompt", or needs guidance on structuring system prompts, writing effective instructions, and optimizing agent behavior in Atomic Agents applications.
+---
+
+# Atomic Agents System Prompt Design
+
+The `SystemPromptGenerator` creates structured, effective system prompts for agents. It combines static instructions with dynamic context from providers.
+
+## SystemPromptGenerator Structure
+
+```python
+from atomic_agents.lib.components.system_prompt_generator import SystemPromptGenerator
+
+system_prompt = SystemPromptGenerator(
+ background=[
+ # WHO the agent is
+ "You are an expert data analyst.",
+ "You specialize in financial data interpretation.",
+ ],
+ steps=[
+ # HOW to process requests
+ "1. Understand the user's question about the data.",
+ "2. Identify relevant data points and trends.",
+ "3. Analyze patterns and correlations.",
+ "4. Formulate clear, actionable insights.",
+ ],
+ output_instructions=[
+ # WHAT to produce
+ "Provide insights in clear, non-technical language.",
+ "Include specific numbers and percentages.",
+ "Highlight key takeaways at the beginning.",
+ ],
+)
+```
+
+## Three-Part Structure
+
+### Background (WHO)
+Establishes the agent's identity, expertise, and role:
+
+```python
+background=[
+ "You are an expert [role] with deep knowledge in [domain].",
+ "Your purpose is to [primary function].",
+ "You have experience with [relevant experience].",
+ "You approach problems with [methodology/style].",
+]
+```
+
+**Examples by domain:**
+```python
+# Customer Support
+background=[
+ "You are a helpful customer support specialist.",
+ "You represent [Company] and embody its values of helpfulness and clarity.",
+ "You have comprehensive knowledge of our products and policies.",
+]
+
+# Code Assistant
+background=[
+ "You are an expert software engineer specializing in Python.",
+ "You write clean, maintainable, well-documented code.",
+ "You follow best practices and design patterns.",
+]
+
+# Research Assistant
+background=[
+ "You are a research analyst with expertise in synthesizing information.",
+ "You excel at finding patterns across multiple sources.",
+ "You prioritize accuracy and cite sources when possible.",
+]
+```
+
+### Steps (HOW)
+Defines the processing workflow:
+
+```python
+steps=[
+ "1. [First action to take]",
+ "2. [Second action to take]",
+ "3. [Third action to take]",
+ "4. [Final action to take]",
+]
+```
+
+**Effective step patterns:**
+
+```python
+# Analysis Pattern
+steps=[
+ "1. Parse and understand the input data.",
+ "2. Identify key elements and relationships.",
+ "3. Apply relevant analysis techniques.",
+ "4. Synthesize findings into coherent insights.",
+ "5. Validate conclusions against the data.",
+]
+
+# Q&A Pattern
+steps=[
+ "1. Understand the user's question fully.",
+ "2. Retrieve relevant information from context.",
+ "3. Formulate a clear, accurate answer.",
+ "4. Provide supporting details if helpful.",
+]
+
+# Task Execution Pattern
+steps=[
+ "1. Parse the task requirements.",
+ "2. Break down into subtasks if complex.",
+ "3. Execute each subtask systematically.",
+ "4. Validate the output meets requirements.",
+]
+```
+
+### Output Instructions (WHAT)
+Specifies the response format and quality:
+
+```python
+output_instructions=[
+ "Format your response as [format].",
+ "Include [required elements].",
+ "Ensure [quality requirements].",
+ "Avoid [things to exclude].",
+]
+```
+
+**Format examples:**
+
+```python
+# Structured Output
+output_instructions=[
+ "Provide your response with a summary first.",
+ "Use bullet points for key findings.",
+ "Include confidence level (high/medium/low).",
+ "End with actionable recommendations.",
+]
+
+# Conversational Output
+output_instructions=[
+ "Respond in a friendly, conversational tone.",
+ "Keep responses concise but complete.",
+ "Ask clarifying questions if needed.",
+]
+
+# Technical Output
+output_instructions=[
+ "Include code examples where appropriate.",
+ "Explain technical concepts clearly.",
+ "Reference documentation or sources.",
+]
+```
+
+## Integrating Context Providers
+
+Context providers add dynamic sections:
+
+```python
+from atomic_agents.lib.components.system_prompt_generator import (
+ SystemPromptGenerator,
+ BaseDynamicContextProvider,
+)
+
+class RAGProvider(BaseDynamicContextProvider):
+ def __init__(self):
+ super().__init__(title="Relevant Documents")
+ self.docs = []
+
+ def get_info(self) -> str:
+ return "\n".join(self.docs)
+
+# Create generator
+generator = SystemPromptGenerator(
+ background=["You answer questions using provided documents."],
+ steps=["1. Read the documents.", "2. Answer based on them."],
+ output_instructions=["Cite document sources."],
+)
+
+# Register provider
+rag = RAGProvider()
+agent.register_context_provider("rag", rag)
+```
+
+The generated prompt will include:
+```
+[Background section]
+[Steps section]
+[Output Instructions section]
+
+## Relevant Documents
+[Dynamic content from provider]
+```
+
+## Prompt Engineering Tips
+
+### Be Specific
+```python
+# Bad
+background=["You are helpful."]
+
+# Good
+background=[
+ "You are a Python code reviewer.",
+ "You identify bugs, security issues, and style violations.",
+ "You follow PEP 8 and common best practices.",
+]
+```
+
+### Use Action Verbs
+```python
+# Bad
+steps=["Think about the problem."]
+
+# Good
+steps=[
+ "1. Identify the core issue.",
+ "2. List possible solutions.",
+ "3. Evaluate trade-offs.",
+ "4. Recommend the best approach.",
+]
+```
+
+### Constrain Output
+```python
+# Bad
+output_instructions=["Give a good answer."]
+
+# Good
+output_instructions=[
+ "Limit response to 3 paragraphs maximum.",
+ "Start with the most important point.",
+ "Include one specific example.",
+]
+```
+
+### Handle Edge Cases
+```python
+background=[
+ "If you cannot answer with certainty, say so clearly.",
+ "If the question is ambiguous, ask for clarification.",
+ "If the request is outside your expertise, acknowledge it.",
+]
+```
+
+## Common Prompt Patterns
+
+### Expert Assistant
+```python
+SystemPromptGenerator(
+ background=[
+ "You are an expert [domain] assistant.",
+ "You provide accurate, helpful information.",
+ "You acknowledge when you're uncertain.",
+ ],
+ steps=[
+ "1. Understand the user's need.",
+ "2. Provide relevant information.",
+ "3. Offer follow-up suggestions.",
+ ],
+ output_instructions=[
+ "Be concise but thorough.",
+ "Use examples when helpful.",
+ ],
+)
+```
+
+### Analyst
+```python
+SystemPromptGenerator(
+ background=[
+ "You are a data analyst.",
+ "You find insights in data.",
+ ],
+ steps=[
+ "1. Examine the data carefully.",
+ "2. Identify patterns and anomalies.",
+ "3. Draw conclusions.",
+ "4. Suggest actions.",
+ ],
+ output_instructions=[
+ "Include specific numbers.",
+ "Highlight key findings first.",
+ "Use simple language.",
+ ],
+)
+```
+
+### Code Generator
+```python
+SystemPromptGenerator(
+ background=[
+ "You are an expert programmer.",
+ "You write clean, efficient code.",
+ ],
+ steps=[
+ "1. Understand the requirements.",
+ "2. Plan the implementation.",
+ "3. Write the code.",
+ "4. Add comments and documentation.",
+ ],
+ output_instructions=[
+ "Include complete, runnable code.",
+ "Add comments for complex logic.",
+ "Follow language conventions.",
+ ],
+)
+```
+
+## References
+
+See `references/` for:
+- `prompt-patterns.md` - More prompt templates
+- `optimization.md` - Token-efficient prompts
+
+See `examples/` for:
+- `domain-prompts.py` - Domain-specific examples
diff --git a/claude-plugin/atomic-agents/skills/atomic-schemas/SKILL.md b/claude-plugin/atomic-agents/skills/atomic-schemas/SKILL.md
new file mode 100644
index 0000000..80275e6
--- /dev/null
+++ b/claude-plugin/atomic-agents/skills/atomic-schemas/SKILL.md
@@ -0,0 +1,189 @@
+---
+description: 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.
+---
+
+# 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
diff --git a/claude-plugin/atomic-agents/skills/atomic-schemas/examples/common-schemas.py b/claude-plugin/atomic-agents/skills/atomic-schemas/examples/common-schemas.py
new file mode 100644
index 0000000..1228338
--- /dev/null
+++ b/claude-plugin/atomic-agents/skills/atomic-schemas/examples/common-schemas.py
@@ -0,0 +1,232 @@
+"""Common schema patterns for Atomic Agents applications."""
+
+from atomic_agents.lib.base.base_io_schema import BaseIOSchema
+from pydantic import Field, field_validator, model_validator
+from typing import List, Optional, Literal, Union
+from enum import Enum
+
+
+# ============================================================
+# Basic Chat Schemas
+# ============================================================
+
+class ChatInputSchema(BaseIOSchema):
+ """Standard chat input."""
+
+ message: str = Field(
+ ...,
+ min_length=1,
+ max_length=10000,
+ description="The user's message or question"
+ )
+
+
+class ChatOutputSchema(BaseIOSchema):
+ """Standard chat output."""
+
+ response: str = Field(
+ ...,
+ description="The agent's response to the user"
+ )
+
+
+# ============================================================
+# Structured Analysis Output
+# ============================================================
+
+class AnalysisOutputSchema(BaseIOSchema):
+ """Structured analysis with findings and recommendations."""
+
+ summary: str = Field(
+ ...,
+ description="Brief summary of the analysis (1-2 sentences)"
+ )
+ findings: List[str] = Field(
+ default_factory=list,
+ description="Key findings from the analysis"
+ )
+ confidence: float = Field(
+ ...,
+ ge=0.0,
+ le=1.0,
+ description="Confidence score between 0 and 1"
+ )
+ recommendations: List[str] = Field(
+ default_factory=list,
+ description="Actionable recommendations"
+ )
+
+
+# ============================================================
+# Classification Schema
+# ============================================================
+
+class Intent(str, Enum):
+ QUESTION = "question"
+ COMMAND = "command"
+ FEEDBACK = "feedback"
+ GREETING = "greeting"
+ OTHER = "other"
+
+
+class ClassificationOutputSchema(BaseIOSchema):
+ """Intent classification result."""
+
+ intent: Intent = Field(
+ ...,
+ description="The classified intent of the input"
+ )
+ confidence: float = Field(
+ ...,
+ ge=0.0,
+ le=1.0,
+ description="Classification confidence"
+ )
+ reasoning: str = Field(
+ ...,
+ description="Brief explanation of the classification"
+ )
+
+
+# ============================================================
+# Search Schemas
+# ============================================================
+
+class SearchInputSchema(BaseIOSchema):
+ """Search query input."""
+
+ query: str = Field(
+ ...,
+ min_length=1,
+ description="Search query text"
+ )
+ max_results: int = Field(
+ default=10,
+ ge=1,
+ le=100,
+ description="Maximum number of results to return"
+ )
+ filters: Optional[dict] = Field(
+ default=None,
+ description="Optional filters to apply"
+ )
+
+
+class SearchResultSchema(BaseIOSchema):
+ """Single search result."""
+
+ title: str = Field(..., description="Result title")
+ snippet: str = Field(..., description="Text snippet")
+ url: Optional[str] = Field(default=None, description="Source URL")
+ score: float = Field(..., ge=0, le=1, description="Relevance score")
+
+
+class SearchOutputSchema(BaseIOSchema):
+ """Search results collection."""
+
+ results: List[SearchResultSchema] = Field(
+ default_factory=list,
+ description="List of search results"
+ )
+ total_found: int = Field(
+ ...,
+ ge=0,
+ description="Total number of matching results"
+ )
+ query_time_ms: Optional[int] = Field(
+ default=None,
+ description="Query execution time in milliseconds"
+ )
+
+
+# ============================================================
+# Error Schemas
+# ============================================================
+
+class ErrorSchema(BaseIOSchema):
+ """Standard error response."""
+
+ error: str = Field(..., description="Error message")
+ code: Optional[str] = Field(default=None, description="Error code")
+ details: Optional[dict] = Field(default=None, description="Additional details")
+
+
+# ============================================================
+# Validation Example
+# ============================================================
+
+class EmailInputSchema(BaseIOSchema):
+ """Input with email validation."""
+
+ email: str = Field(..., description="Email address")
+ name: str = Field(..., min_length=1, description="Person's name")
+
+ @field_validator("email")
+ @classmethod
+ def validate_email(cls, v: str) -> str:
+ if "@" not in v or "." not in v.split("@")[-1]:
+ raise ValueError("Invalid email format")
+ return v.lower().strip()
+
+
+class DateRangeSchema(BaseIOSchema):
+ """Date range with cross-field validation."""
+
+ start_date: str = Field(..., description="Start date (YYYY-MM-DD)")
+ end_date: str = Field(..., description="End date (YYYY-MM-DD)")
+
+ @field_validator("start_date", "end_date")
+ @classmethod
+ def validate_date_format(cls, v: str) -> str:
+ from datetime import datetime
+ try:
+ datetime.strptime(v, "%Y-%m-%d")
+ except ValueError:
+ raise ValueError("Date must be in YYYY-MM-DD format")
+ return v
+
+ @model_validator(mode="after")
+ def validate_range(self) -> "DateRangeSchema":
+ from datetime import datetime
+ start = datetime.strptime(self.start_date, "%Y-%m-%d")
+ end = datetime.strptime(self.end_date, "%Y-%m-%d")
+ if end < start:
+ raise ValueError("end_date must be after start_date")
+ return self
+
+
+# ============================================================
+# Polymorphic Content
+# ============================================================
+
+class TextContentSchema(BaseIOSchema):
+ """Text content block."""
+
+ content_type: Literal["text"] = "text"
+ text: str = Field(..., description="Text content")
+
+
+class ImageContentSchema(BaseIOSchema):
+ """Image content block."""
+
+ content_type: Literal["image"] = "image"
+ url: str = Field(..., description="Image URL")
+ alt_text: Optional[str] = Field(default=None, description="Alt text")
+
+
+class CodeContentSchema(BaseIOSchema):
+ """Code content block."""
+
+ content_type: Literal["code"] = "code"
+ code: str = Field(..., description="Code content")
+ language: str = Field(default="python", description="Programming language")
+
+
+ContentType = Union[TextContentSchema, ImageContentSchema, CodeContentSchema]
+
+
+class MessageSchema(BaseIOSchema):
+ """Message with polymorphic content."""
+
+ role: Literal["user", "assistant"] = Field(..., description="Message role")
+ content: List[ContentType] = Field(..., description="Message content blocks")
diff --git a/claude-plugin/atomic-agents/skills/atomic-structure/SKILL.md b/claude-plugin/atomic-agents/skills/atomic-structure/SKILL.md
new file mode 100644
index 0000000..c0b617b
--- /dev/null
+++ b/claude-plugin/atomic-agents/skills/atomic-structure/SKILL.md
@@ -0,0 +1,311 @@
+---
+description: This skill should be used when the user asks to "create project structure", "organize atomic agents project", "pyproject.toml", "project layout", "directory structure", or needs guidance on organizing files, configuring dependencies, and structuring Atomic Agents applications for maintainability.
+---
+
+# Atomic Agents Project Structure
+
+Proper project organization is essential for maintainable Atomic Agents applications. Structure scales from simple scripts to complex multi-agent systems.
+
+## Project Structure Patterns
+
+### Simple Application (1-2 agents)
+
+```
+my_project/
+├── pyproject.toml # Project metadata and dependencies
+├── .env # Environment variables (API keys)
+├── .env.example # Template for .env
+├── .gitignore # Git ignore patterns
+├── README.md # Documentation
+└── my_project/
+ ├── __init__.py
+ ├── main.py # Entry point
+ ├── config.py # Configuration
+ └── schemas.py # Input/output schemas
+```
+
+### Medium Application (3-5 agents with tools)
+
+```
+my_project/
+├── pyproject.toml
+├── .env
+├── .env.example
+├── .gitignore
+├── README.md
+└── my_project/
+ ├── __init__.py
+ ├── main.py # Entry point and orchestration
+ ├── config.py # Configuration
+ ├── schemas.py # Shared schemas
+ ├── agents/
+ │ ├── __init__.py
+ │ ├── query_agent.py # Agent 1
+ │ └── response_agent.py # Agent 2
+ └── tools/
+ ├── __init__.py
+ ├── search_tool.py
+ └── calculator_tool.py
+```
+
+### Complex Application (multi-agent with services)
+
+```
+my_project/
+├── pyproject.toml
+├── .env
+├── .env.example
+├── .gitignore
+├── README.md
+├── tests/
+│ ├── __init__.py
+│ ├── test_agents.py
+│ └── test_tools.py
+└── my_project/
+ ├── __init__.py
+ ├── main.py
+ ├── config.py
+ ├── agents/
+ │ ├── __init__.py
+ │ ├── query_agent.py
+ │ ├── synthesis_agent.py
+ │ └── validation_agent.py
+ ├── tools/
+ │ ├── __init__.py
+ │ └── api_tool.py
+ ├── schemas/
+ │ ├── __init__.py
+ │ ├── inputs.py
+ │ └── outputs.py
+ ├── services/
+ │ ├── __init__.py
+ │ ├── database.py
+ │ └── external_api.py
+ ├── context_providers/
+ │ ├── __init__.py
+ │ └── rag_provider.py
+ └── presentation/
+ ├── __init__.py
+ └── console.py
+```
+
+## pyproject.toml Template
+
+```toml
+[project]
+name = "my-project"
+version = "0.1.0"
+description = "An Atomic Agents application for [purpose]"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Your Name", email = "[email protected]" }]
+
+dependencies = [
+ "atomic-agents>=1.0.0",
+ "instructor>=1.0.0",
+ "openai>=1.0.0",
+ "python-dotenv>=1.0.0",
+ "pydantic>=2.0.0",
+ "rich>=13.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+ "pytest>=7.0.0",
+ "pytest-asyncio>=0.21.0",
+ "black>=23.0.0",
+ "ruff>=0.1.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["my_project"]
+```
+
+## Configuration Pattern
+
+**config.py**:
+```python
+import os
+from dataclasses import dataclass
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+def get_api_key() -> str:
+ """Get OpenAI API key from environment."""
+ key = os.getenv("OPENAI_API_KEY")
+ if not key:
+ raise ValueError("OPENAI_API_KEY environment variable not set")
+ return key
+
+
+@dataclass
+class Config:
+ """Application configuration."""
+
+ api_key: str = None
+ model: str = "gpt-4o-mini"
+ max_tokens: int = 1000
+ temperature: float = 0.7
+
+ def __post_init__(self):
+ if self.api_key is None:
+ self.api_key = get_api_key()
+
+
+# Global config instance
+config = Config()
+```
+
+## Environment Variables
+
+**.env.example** (commit this):
+```bash
+# LLM Provider
+OPENAI_API_KEY=sk-your-key-here
+# ANTHROPIC_API_KEY=your-key-here
+
+# Application Settings
+MODEL=gpt-4o-mini
+MAX_TOKENS=1000
+TEMPERATURE=0.7
+
+# External Services
+# DATABASE_URL=postgresql://...
+# REDIS_URL=redis://...
+```
+
+**.gitignore** additions:
+```gitignore
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+```
+
+## Entry Point Pattern
+
+**main.py**:
+```python
+"""Main entry point for the application."""
+
+import instructor
+import openai
+from rich.console import Console
+
+from .config import config
+from .agents.query_agent import create_query_agent
+from .schemas import UserInput
+
+console = Console()
+
+
+def main():
+ """Run the application."""
+ # Initialize client
+ client = instructor.from_openai(openai.OpenAI(api_key=config.api_key))
+
+ # Create agent
+ agent = create_query_agent(client, config.model)
+
+ # Main loop
+ console.print("[bold green]Ready![/bold green]")
+ while True:
+ try:
+ user_input = console.input("[bold blue]You:[/bold blue] ")
+ if user_input.lower() in ("exit", "quit"):
+ break
+
+ response = agent.run(UserInput(message=user_input))
+ console.print(f"[bold green]Agent:[/bold green] {response.message}")
+
+ except KeyboardInterrupt:
+ break
+
+ console.print("\n[yellow]Goodbye![/yellow]")
+
+
+if __name__ == "__main__":
+ main()
+```
+
+## Agent Module Pattern
+
+**agents/query_agent.py**:
+```python
+"""Query processing agent."""
+
+from atomic_agents.agents.base_agent import AtomicAgent, AgentConfig
+from atomic_agents.lib.components.system_prompt_generator import SystemPromptGenerator
+from atomic_agents.lib.components.chat_history import ChatHistory
+
+from ..schemas import QueryInput, QueryOutput
+
+
+def create_query_agent(client, model: str) -> AtomicAgent[QueryInput, QueryOutput]:
+ """Create and configure the query agent."""
+ config = AgentConfig(
+ client=client,
+ model=model,
+ history=ChatHistory(),
+ system_prompt_generator=SystemPromptGenerator(
+ background=["You are a helpful query processor."],
+ steps=["1. Understand the query.", "2. Generate response."],
+ output_instructions=["Be concise and helpful."],
+ ),
+ )
+ return AtomicAgent[QueryInput, QueryOutput](config=config)
+```
+
+## File Naming Conventions
+
+| Component | File Pattern | Class Pattern |
+|-----------|--------------|---------------|
+| Agents | `*_agent.py` | `*Agent` |
+| Tools | `*_tool.py` | `*Tool` |
+| Schemas | `schemas.py` or `*.py` | `*Schema` |
+| Providers | `*_provider.py` | `*Provider` |
+| Config | `config.py` | `Config`, `*Config` |
+| Services | `*_service.py` | `*Service` |
+
+## Best Practices
+
+1. **One agent per file** - Easier to maintain and test
+2. **Shared schemas in schemas.py** - Or schemas/ directory for many
+3. **Factory functions** - `create_*_agent()` for configurable agents
+4. **Type hints everywhere** - IDE support and documentation
+5. **Docstrings** - Document purpose of each module
+6. **Tests alongside code** - tests/ directory mirroring src
+7. **Rich for output** - Consistent, beautiful terminal output
+
+## References
+
+See `references/` for:
+- `testing-structure.md` - Test organization patterns
+- `api-structure.md` - FastAPI integration layout
+
+See `examples/` for:
+- `minimal-project/` - Simplest structure
+- `full-project/` - Complete structure template
diff --git a/claude-plugin/atomic-agents/skills/atomic-tools/SKILL.md b/claude-plugin/atomic-agents/skills/atomic-tools/SKILL.md
new file mode 100644
index 0000000..b375ed2
--- /dev/null
+++ b/claude-plugin/atomic-agents/skills/atomic-tools/SKILL.md
@@ -0,0 +1,221 @@
+---
+description: This skill should be used when the user asks to "create a tool", "implement BaseTool", "add tool to agent", "tool orchestration", "external API tool", or needs guidance on tool development, tool configuration, error handling, and integrating tools with agents in Atomic Agents applications.
+---
+
+# Atomic Agents Tool Development
+
+Tools extend agent capabilities by providing access to external services, APIs, databases, and computations. They follow a consistent pattern with input/output schemas and error handling.
+
+## Tool Architecture
+
+```
+┌─────────────────────────────────────┐
+│ BaseTool │
+├─────────────────────────────────────┤
+│ input_schema: BaseIOSchema │
+│ output_schema: BaseIOSchema │
+│ config: BaseToolConfig │
+├─────────────────────────────────────┤
+│ run(params) -> Output | Error │
+└─────────────────────────────────────┘
+```
+
+## Basic Tool Template
+
+```python
+from atomic_agents.lib.base.base_tool import BaseTool, BaseToolConfig
+from atomic_agents.lib.base.base_io_schema import BaseIOSchema
+from pydantic import Field
+from typing import Optional
+import os
+
+# ============================================================
+# Schemas
+# ============================================================
+
+class MyToolInputSchema(BaseIOSchema):
+ """Input for the tool."""
+ query: str = Field(..., description="The query to process")
+
+class MyToolOutputSchema(BaseIOSchema):
+ """Successful output."""
+ result: str = Field(..., description="The result")
+
+class MyToolErrorSchema(BaseIOSchema):
+ """Error output."""
+ error: str = Field(..., description="Error message")
+ code: Optional[str] = Field(default=None, description="Error code")
+
+# ============================================================
+# Configuration
+# ============================================================
+
+class MyToolConfig(BaseToolConfig):
+ """Tool configuration."""
+ api_key: str = Field(
+ default_factory=lambda: os.getenv("MY_API_KEY", ""),
+ description="API key"
+ )
+ timeout: int = Field(default=30, description="Timeout in seconds")
+
+# ============================================================
+# Tool
+# ============================================================
+
+class MyTool(BaseTool):
+ """Tool description."""
+
+ input_schema = MyToolInputSchema
+ output_schema = MyToolOutputSchema
+
+ def __init__(self, config: MyToolConfig = None):
+ super().__init__(config or MyToolConfig())
+ self.config: MyToolConfig = self.config
+
+ def run(self, params: MyToolInputSchema) -> MyToolOutputSchema | MyToolErrorSchema:
+ try:
+ # Tool logic here
+ result = f"Processed: {params.query}"
+ return MyToolOutputSchema(result=result)
+ except Exception as e:
+ return MyToolErrorSchema(error=str(e), code="ERROR")
+
+# Convenience instance
+tool = MyTool()
+```
+
+## Tool Configuration Pattern
+
+```python
+class APIToolConfig(BaseToolConfig):
+ """Configuration with environment variables."""
+
+ api_key: str = Field(
+ default_factory=lambda: os.getenv("SERVICE_API_KEY", ""),
+ description="API key for the service"
+ )
+ base_url: str = Field(
+ default="https://api.service.com/v1",
+ description="Base URL for API"
+ )
+ timeout: int = Field(
+ default=30,
+ ge=1,
+ le=300,
+ description="Request timeout in seconds"
+ )
+ max_retries: int = Field(
+ default=3,
+ ge=0,
+ le=10,
+ description="Maximum retry attempts"
+ )
+```
+
+## Error Handling Pattern
+
+Always return error schemas instead of raising exceptions:
+
+```python
+def run(self, params: InputSchema) -> OutputSchema | ErrorSchema:
+ # Validate configuration
+ if not self.config.api_key:
+ return ErrorSchema(
+ error="API key not configured",
+ code="CONFIG_ERROR"
+ )
+
+ try:
+ # Make external call
+ response = requests.get(
+ f"{self.config.base_url}/endpoint",
+ params={"q": params.query},
+ headers={"Authorization": f"Bearer {self.config.api_key}"},
+ timeout=self.config.timeout
+ )
+ response.raise_for_status()
+ data = response.json()
+
+ return OutputSchema(result=data["result"])
+
+ except requests.Timeout:
+ return ErrorSchema(error="Request timed out", code="TIMEOUT")
+ except requests.HTTPError as e:
+ return ErrorSchema(error=f"HTTP error: {e}", code="HTTP_ERROR")
+ except Exception as e:
+ return ErrorSchema(error=str(e), code="UNKNOWN_ERROR")
+```
+
+## Using Tools with Agents
+
+### Direct Tool Usage
+```python
+from my_tools import search_tool, SearchInputSchema
+
+# Call tool directly
+result = search_tool.run(SearchInputSchema(query="atomic agents"))
+```
+
+### Tool Orchestration Pattern
+```python
+from typing import Union
+from atomic_agents.agents.base_agent import AtomicAgent, AgentConfig
+
+# Define tool selection schema
+class ToolCallSchema(BaseIOSchema):
+ tool_name: Literal["search", "calculate", "none"] = Field(
+ ..., description="Which tool to use"
+ )
+ tool_input: Union[SearchInput, CalculateInput, None] = Field(
+ ..., description="Input for the selected tool"
+ )
+
+# Agent decides which tool to use
+agent = AtomicAgent[UserQuerySchema, ToolCallSchema](config=config)
+
+# Orchestration loop
+user_input = UserQuerySchema(query="What is 2+2?")
+tool_decision = agent.run(user_input)
+
+if tool_decision.tool_name == "calculate":
+ result = calculator_tool.run(tool_decision.tool_input)
+elif tool_decision.tool_name == "search":
+ result = search_tool.run(tool_decision.tool_input)
+```
+
+## Pre-Built Tools (Atomic Forge)
+
+Download tools from Atomic Forge:
+
+```bash
+atomic download calculator
+atomic download searxng
+atomic download youtube-transcript
+```
+
+Available tools:
+- **Calculator** - Mathematical operations
+- **SearXNG** - Web search
+- **Tavily** - AI-powered search
+- **YouTube Transcript** - Video transcripts
+- **Webpage Scraper** - HTML content extraction
+
+## Tool Best Practices
+
+1. **Always use BaseToolConfig** - For consistent configuration
+2. **Environment variables for secrets** - Never hardcode API keys
+3. **Return errors, don't raise** - Caller can handle gracefully
+4. **Set timeouts** - Prevent hanging on external calls
+5. **Validate inputs** - Check parameters before processing
+6. **Include error codes** - Help with debugging and handling
+7. **Document thoroughly** - Input/output schemas need descriptions
+
+## References
+
+See `references/` for:
+- `api-integration.md` - Patterns for REST API tools
+- `database-tools.md` - Database integration patterns
+
+See `examples/` for:
+- `simple-tool.py` - Minimal tool implementation
+- `api-tool.py` - External API integration
diff --git a/claude-plugin/atomic-agents/skills/atomic-tools/examples/api-tool.py b/claude-plugin/atomic-agents/skills/atomic-tools/examples/api-tool.py
new file mode 100644
index 0000000..292a9a8
--- /dev/null
+++ b/claude-plugin/atomic-agents/skills/atomic-tools/examples/api-tool.py
@@ -0,0 +1,222 @@
+"""Example API tool with proper error handling and configuration."""
+
+import os
+import requests
+from typing import Optional, List
+
+from atomic_agents.lib.base.base_tool import BaseTool, BaseToolConfig
+from atomic_agents.lib.base.base_io_schema import BaseIOSchema
+from pydantic import Field
+
+
+# ============================================================
+# Schemas
+# ============================================================
+
+class WeatherInputSchema(BaseIOSchema):
+ """Input for weather lookup."""
+
+ city: str = Field(
+ ...,
+ min_length=1,
+ description="City name to get weather for"
+ )
+ units: str = Field(
+ default="metric",
+ description="Units: 'metric' (Celsius) or 'imperial' (Fahrenheit)"
+ )
+
+
+class WeatherOutputSchema(BaseIOSchema):
+ """Successful weather result."""
+
+ city: str = Field(..., description="City name")
+ temperature: float = Field(..., description="Current temperature")
+ units: str = Field(..., description="Temperature units")
+ conditions: str = Field(..., description="Weather conditions")
+ humidity: int = Field(..., description="Humidity percentage")
+ wind_speed: float = Field(..., description="Wind speed")
+
+
+class WeatherErrorSchema(BaseIOSchema):
+ """Weather API error."""
+
+ error: str = Field(..., description="Error message")
+ code: str = Field(..., description="Error code")
+ city: Optional[str] = Field(default=None, description="Requested city")
+
+
+# ============================================================
+# Configuration
+# ============================================================
+
+class WeatherToolConfig(BaseToolConfig):
+ """Configuration for Weather Tool."""
+
+ api_key: str = Field(
+ default_factory=lambda: os.getenv("OPENWEATHER_API_KEY", ""),
+ description="OpenWeatherMap API key"
+ )
+ base_url: str = Field(
+ default="https://api.openweathermap.org/data/2.5",
+ description="API base URL"
+ )
+ timeout: int = Field(
+ default=10,
+ ge=1,
+ le=60,
+ description="Request timeout in seconds"
+ )
+
+
+# ============================================================
+# Tool Implementation
+# ============================================================
+
+class WeatherTool(BaseTool):
+ """
+ Tool for fetching current weather conditions.
+
+ Uses the OpenWeatherMap API to get current weather data
+ for a specified city.
+
+ Requires OPENWEATHER_API_KEY environment variable.
+ """
+
+ input_schema = WeatherInputSchema
+ output_schema = WeatherOutputSchema
+
+ def __init__(self, config: WeatherToolConfig = None):
+ """Initialize the weather tool."""
+ super().__init__(config or WeatherToolConfig())
+ self.config: WeatherToolConfig = self.config
+
+ def run(
+ self, params: WeatherInputSchema
+ ) -> WeatherOutputSchema | WeatherErrorSchema:
+ """
+ Fetch weather for a city.
+
+ Args:
+ params: Input parameters with city and units
+
+ Returns:
+ WeatherOutputSchema on success, WeatherErrorSchema on failure
+ """
+ # Validate configuration
+ if not self.config.api_key:
+ return WeatherErrorSchema(
+ error="OpenWeatherMap API key not configured",
+ code="CONFIG_ERROR",
+ city=params.city
+ )
+
+ try:
+ # Make API request
+ response = requests.get(
+ f"{self.config.base_url}/weather",
+ params={
+ "q": params.city,
+ "appid": self.config.api_key,
+ "units": params.units,
+ },
+ timeout=self.config.timeout,
+ )
+
+ # Handle HTTP errors
+ if response.status_code == 404:
+ return WeatherErrorSchema(
+ error=f"City '{params.city}' not found",
+ code="CITY_NOT_FOUND",
+ city=params.city
+ )
+
+ response.raise_for_status()
+ data = response.json()
+
+ # Parse response
+ return WeatherOutputSchema(
+ city=data["name"],
+ temperature=data["main"]["temp"],
+ units="°C" if params.units == "metric" else "°F",
+ conditions=data["weather"][0]["description"],
+ humidity=data["main"]["humidity"],
+ wind_speed=data["wind"]["speed"],
+ )
+
+ except requests.Timeout:
+ return WeatherErrorSchema(
+ error="Request timed out",
+ code="TIMEOUT",
+ city=params.city
+ )
+ except requests.HTTPError as e:
+ return WeatherErrorSchema(
+ error=f"API error: {e}",
+ code="HTTP_ERROR",
+ city=params.city
+ )
+ except requests.RequestException as e:
+ return WeatherErrorSchema(
+ error=f"Network error: {e}",
+ code="NETWORK_ERROR",
+ city=params.city
+ )
+ except KeyError as e:
+ return WeatherErrorSchema(
+ error=f"Unexpected API response format: missing {e}",
+ code="PARSE_ERROR",
+ city=params.city
+ )
+ except Exception as e:
+ return WeatherErrorSchema(
+ error=f"Unexpected error: {e}",
+ code="UNKNOWN_ERROR",
+ city=params.city
+ )
+
+
+# ============================================================
+# Convenience Instance
+# ============================================================
+
+# Default instance with environment-based config
+weather_tool = WeatherTool()
+
+
+# ============================================================
+# Usage Example
+# ============================================================
+
+if __name__ == "__main__":
+ from rich.console import Console
+ from rich.table import Table
+
+ console = Console()
+
+ # Create tool
+ tool = WeatherTool()
+
+ # Test cities
+ cities = ["London", "New York", "Tokyo", "InvalidCity123"]
+
+ table = Table(title="Weather Results")
+ table.add_column("City", style="cyan")
+ table.add_column("Temperature", style="green")
+ table.add_column("Conditions", style="yellow")
+ table.add_column("Status", style="bold")
+
+ for city in cities:
+ result = tool.run(WeatherInputSchema(city=city))
+
+ if isinstance(result, WeatherErrorSchema):
+ table.add_row(city, "-", "-", f"[red]{result.code}[/red]")
+ else:
+ table.add_row(
+ result.city,
+ f"{result.temperature}{result.units}",
+ result.conditions,
+ "[green]OK[/green]"
+ )
+
+ console.print(table)