Maxwell Bot: Skill-Agnostic AI Agent Framework

A sample project demonstrating a skill-agnostic AI agent that dynamically loads domain expertise from markdown skill definitions, with an example magnetics/electromagnetics SME skill.

Project Overview

This project showcases a generic agent framework that can work with any domain expertise by loading tool definitions and system prompts from skill.md files. The magnetics example demonstrates how to build an expert-level AI agent for electromagnetics and magnetic circuit design using real equations and precise numerical computations.

Key features:

Skill-agnostic architecture - works with any domain by loading from skill.md files
Hand-rolled agentic loop (no framework dependencies) for transparent agent reasoning
Dynamic tool discovery - parses tool schemas directly from skill.md markdown
Retrieval-augmented generation (RAG) - Chroma vector database with semantic search over domain knowledge
Real physics equations with SI unit constants (e.g., μ₀ = 4π×10⁻⁷ H/m)
8 specialized magnetics tools for field calculations, circuit analysis, and unit conversions
Configuration-driven design - change agent behavior by editing skill.md, no code changes needed
Comprehensive test suite validating all tools and calculations

Architecture

┌──────────────────────────────────────┐
│   CLI (cli.py)                       │
│   - Skill selection & discovery      │
│   - Interactive chat interface       │
└────────────────┬─────────────────────┘
                 │
┌────────────────▼─────────────────────┐
│   SkillAgent (Anthropic SDK)         │
│   - Agentic loop                     │
│   - Tool orchestration               │
│   - skill.md parsing & loading       │
└────────────────┬─────────────────────┘
                 │
        ┌────────▼─────────┐
        │  Skills/         │
        │  <skill-name>/   │
        │  - skill.md      │
        │  - tool configs  │
        └────────┬─────────┘
                 │
     ┌───────────┴───────────┬──────────────┐
     │                       │              │
┌────▼─────┐  ┌─────────┐ ┌─┴──────────┐ ┌─┴──────┐
│ Fields   │  │Circuits │ │ Materials  │ │Convert │
│ (fields) │  │(circuits)│ │ (materials)│ │(units) │
└──────────┘  └─────────┘ └────────────┘ └────────┘

Project Structure

maxwell_bot/
├── agent/
│   ├── agent.py               # SkillAgent: generic, skill-agnostic framework
│   └── __init__.py
├── mcp_server/
│   ├── tools/
│   │   ├── fields.py          # B/H field calculations (solenoid, wire, flux, energy)
│   │   ├── circuits.py        # Reluctance, MMF calculations
│   │   ├── materials.py       # Material property lookup (6 materials)
│   │   ├── converters.py      # Unit conversions (T↔Gauss, Wb↔Maxwell, etc.)
│   │   └── __init__.py
│   └── __init__.py
├── skills/
│   └── maxwell_magnetics/
│       └── skill.md           # Skill definition: tool reference, use cases, boundaries
├── tests/
│   ├── test_fields.py         # Field calculation tests
│   ├── test_circuits.py       # Circuit calculation tests
│   ├── test_materials.py      # Material lookup tests
│   ├── test_converters.py     # Conversion tests
│   └── __init__.py
├── cli.py                     # Interactive CLI entry point
├── requirements.txt           # Python dependencies
├── .gitignore
└── README.md                  # This file

Installation & Setup

Prerequisites

Python 3.9+
pip package manager
An Anthropic API key

Step 1: Clone or Download the Project

git clone https://github.com/jkearney126/maxwell_bot.git
cd maxwell_bot

Step 2: Create a Virtual Environment (Recommended)

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Step 3: Install Dependencies

pip install -r requirements.txt

Step 4: Set Your Anthropic API Key

export ANTHROPIC_API_KEY="sk-ant-..."  # On Windows: set ANTHROPIC_API_KEY=sk-ant-...

Or, for persistent setup, add to your shell profile (~/.bashrc, ~/.zshrc, etc.):

export ANTHROPIC_API_KEY="your-key-here"

Running the Agent

Interactive Chat Interface

python cli.py

This launches an interactive chat where you can:

Select from available skills (if multiple exist)
Choose from 5 example prompts (by number 1-5)
Type your own custom questions
See animated thinking spinner while Claude responds
Type quit or exit to exit

The agent auto-discovers skills from the skills/ directory and loads tool definitions and expertise from each skill's skill.md file.

Skill Definition Files (skill.md)

Each skill lives in skills/<skill-name>/ with a skill.md file that defines:

Use Case Decision Table: Maps problem types to appropriate tools
Tool Reference: Complete tool specifications with:
- Input/output schemas (parsed automatically by the agent)
- Use cases and assumptions
- Physics equations and constants
Boundaries & Constraints: What the agent can/cannot do
Gotchas & Common Mistakes: User guidance for typical errors
Physics Foundations: Key equations and reference constants
Recommended Workflow: Step-by-step reasoning guide

Key Design Pattern

The agent is completely skill-agnostic:

Tool definitions are parsed from skill.md (not hardcoded)
System prompts are loaded from skill.md
To add a new skill: create skills/<name>/skill.md with proper format
To modify behavior: edit skill.md, no code changes needed

This separation of "what" (skill definition) from "how" (agent implementation) makes the framework flexible and reusable.

Knowledge Base & Retrieval-Augmented Generation (RAG)

Each skill can include a knowledge base of domain documents to augment agent responses with relevant context.

How It Works

Vector Database: Uses Chroma with semantic embeddings (all-MiniLM-L6-v2)
Automatic Indexing: Markdown files in skills/<skill>/knowledge/ are indexed on first load
Semantic Search: When user queries, top-3 most relevant document chunks are retrieved
Context Injection: Retrieved knowledge is appended to system prompt before Claude API call

Adding Knowledge Documents

Create markdown files in skills/<skill-name>/knowledge/:

skills/
└── maxwell_magnetics/
    ├── skill.md
    └── knowledge/
        ├── real_world_applications.md
        ├── design_mistakes_troubleshooting.md
        ├── materials_and_components.md
        └── standards_and_safety.md

Document Format:

Use ## Section Title headers for automatic chunking
Each chunk becomes searchable (improves relevance ranking)
Include practical, complementary information (not just duplicating skill.md)

Example: Magnetics Knowledge Base

The included magnetics skill has 4 knowledge documents covering:

Real-World Applications - MRI systems, transformers, motors, relays, speakers
Design Mistakes & Troubleshooting - Common failures, thermal drift, saturation issues
Materials & Components - Real costs, specifications, performance tradeoffs
Standards & Safety - Regulatory requirements, compliance paths, EMC/RoHS

Result: 33 semantic chunks indexed, ~80% relevance for domain-specific queries

Storage & Persistence

Vector database stored in skills/<skill>/.chroma_db/
Automatic persistence: survives process restarts
One collection per skill, allowing multi-skill deployments

Example Output:

✓ Agent initialized with skill: maxwell_magnetics
✓ Loaded 8 tools

======================================================================
SKILL AGENT - MAXWELL_MAGNETICS
======================================================================

Example prompts you can use:
  1. What is the magnetic field at the center of a solenoid with 500 turns, 20cm long, carrying 2A?
  2. I'm designing a magnetic circuit with a 10cm iron core (μr=5000), 2cm² cross-section. What is the reluctance?
  3. How much energy is stored in a 50mT field occupying 0.5 liters?
  4. Compare the permeability of silicon steel vs ferrite.
  5. Convert 1.2 Tesla to Gauss.

======================================================================
User: What is the magnetic field at the center of a solenoid with 500 turns, 20cm long, carrying 2A?
======================================================================

🧠 Thinking...

Agent: I'll calculate the magnetic field at the center of the solenoid using the formula B = μ₀ · n · I...

🔧 Calling tool: solenoid_field
   Input: {
     "turns": 500,
     "length_m": 0.2,
     "current_A": 2.0
   }
   Result: {
     "B_tesla": 0.006283185307179586,
     "equation": "B = μ₀ · n · I"
   }

Agent: The magnetic field at the center of the solenoid is approximately **6.28 mT** (millitesla)...

Running Tests

Run All Tests

pytest tests/ -v

Run Tests for a Specific Module

pytest tests/test_fields.py -v       # Field calculations
pytest tests/test_circuits.py -v     # Circuit calculations
pytest tests/test_materials.py -v    # Material lookups
pytest tests/test_converters.py -v   # Unit conversions

Run Tests with Coverage

pip install pytest-cov
pytest tests/ --cov=mcp_server --cov=agent

Available Tools

Field Calculations

`solenoid_field`

Compute magnetic field at the center of a solenoid.

Equation: B = μ₀ · n · I

Inputs:

turns (int): Number of turns
length_m (float): Length in meters
current_A (float): Current in amperes

Example:

Input: 500 turns, 0.2m long, 2A
Output: B = 6.28 mT

`biot_savart_wire`

Compute magnetic field around an infinite straight current-carrying wire.

Equation: B = μ₀I / (2πr)

Inputs:

current_A (float): Current in amperes
distance_m (float): Distance from wire in meters

Example:

Input: 10A at 0.1m
Output: B = 20 μT

`magnetic_flux`

Compute magnetic flux through a surface.

Equation: Φ = B · A · cos(θ)

Inputs:

B_tesla (float): Flux density in Tesla
area_m2 (float): Area in square meters
angle_deg (float, default 0): Angle in degrees

Example:

Input: 0.1T, 0.01m², 0° angle
Output: Φ = 0.001 Wb (1 mWb)

`energy_stored`

Compute energy stored in a magnetic field.

Equation: W = (B² / (2μ₀)) · Volume

Inputs:

B_tesla (float): Flux density in Tesla
volume_m3 (float): Volume in cubic meters

Example:

Input: 50mT in 0.5L (0.0005m³)
Output: W ≈ 0.99 Joules

Magnetic Circuit Tools

`reluctance`

Compute reluctance of a magnetic circuit path.

Equation: R = l / (μ₀ · μᵣ · A)

Inputs:

length_m (float): Path length in meters
area_m2 (float): Cross-sectional area in square meters
relative_permeability (float): Material's μᵣ

Example:

Input: Iron core (μᵣ=5000), 0.1m long, 2cm² area
Output: R ≈ 79,600 H⁻¹

`mmf_required`

Compute magnetomotive force (MMF) for a magnetic path.

Equation: MMF = H · l

Inputs:

H_field (float): Field strength in A/m
path_length_m (float): Path length in meters

Example:

Input: H = 1000 A/m, l = 0.1m
Output: MMF = 100 AT (Ampere-turns)

Material Properties

`material_lookup`

Return properties of a magnetic material.

Inputs:

material (string): Material name (case-insensitive)

Available Materials:

air — Vacuum/air (μᵣ = 1)
iron — Pure iron, soft magnetic (μᵣ = 5000, Bsat = 2.15 T)
silicon_steel — Transformer core (μᵣ = 4000, Bsat = 2.0 T)
ferrite — Hard magnetic (μᵣ = 2000, Bsat = 0.4 T)
neodymium — NdFeB permanent magnet (μᵣ = 1.05, Bsat = 1.4 T)
mu_metal — Shielding material (μᵣ = 80000, Bsat = 0.8 T)

Example:

Input: "neodymium"
Output: {
  "relative_permeability": 1.05,
  "saturation_flux_density_T": 1.4,
  "coercivity_A_per_m": 955000.0
}

Unit Conversions

`unit_convert`

Convert between magnetic units.

Supported Conversions:

Tesla ↔ Gauss (1 T = 10,000 Gauss)
Weber ↔ Maxwell (1 Wb = 10⁸ Maxwell)
A/m ↔ Oersted (1 A/m ≈ 0.0126 Oersted)
Henry ↔ milliHenry ↔ microHenry (H ↔ mH ↔ uH)

Inputs:

value (float): Value to convert
from_unit (string): Source unit
to_unit (string): Target unit

Example:

Input: 1.2 T → Gauss
Output: 12000 Gauss

Example Interactions

Query 1: Solenoid Design

User: "What is the magnetic field at the center of a solenoid with 500 turns, 20cm long, carrying 2A?"

Agent:

Identifies: Use solenoid field equation B = μ₀ · n · I
Calls solenoid_field tool
Returns: B ≈ 6.28 mT
Explains: The field is uniform along the axis (ideal assumption) and proportional to turn density and current.

Query 2: Magnetic Circuit Design

User: "I'm designing a magnetic circuit with a 10cm iron core (μr=5000), 2cm² cross-section. What is the reluctance?"

Agent:

Identifies: Need to find reluctance R = l / (μ₀ · μᵣ · A)
Calls material_lookup("iron") to verify μᵣ
Calls reluctance with core parameters
Returns: R ≈ 79,577 H⁻¹ (Ampere-turns per Weber)

Query 3: Energy in a Magnetic Field

User: "How much energy is stored in a 50mT field occupying 0.5 liters?"

Agent:

Identifies: Use energy density equation W = (B² / (2μ₀)) · Volume
Converts 0.5 L → 0.0005 m³
Calls energy_stored tool
Returns: W ≈ 0.99 Joules
Context: About the energy in a small magnet or inductor.

Testing

This project includes comprehensive tests covering:

Unit tests for each tool (solenoid, wire, flux, energy, reluctance, MMF)
Material property lookups (all 6 materials)
Unit conversions (bidirectional, edge cases)
Error handling (invalid inputs, missing materials, unsupported conversions)

Run all tests:

pytest tests/ -v --tb=short

Troubleshooting

"ANTHROPIC_API_KEY not found"

Ensure your API key is set:

export ANTHROPIC_API_KEY="sk-ant-..."
python cli.py

"No skills found in skills/ directory"

Ensure your skill is properly structured:

skills/
└── <skill-name>/
    └── skill.md

The agent auto-discovers skills by looking for skill.md files in subdirectories of skills/.

Dependencies

Package	Purpose
`anthropic>=0.25.0`	Anthropic Python SDK (Claude API)
`chromadb>=0.4.0`	Vector database for RAG (Chroma)
`sentence-transformers>=3.0.0`	Semantic embeddings for retrieval
`pytest>=7.4.0`	Test framework
`pytest-asyncio>=0.21.0`	Async test support

Magnetics SME MCP Server

Maxwell Bot: Skill-Agnostic AI Agent Framework

Project Overview

Architecture

Project Structure

Installation & Setup

Prerequisites

Step 1: Clone or Download the Project

Step 2: Create a Virtual Environment (Recommended)

Step 3: Install Dependencies

Step 4: Set Your Anthropic API Key

Running the Agent

Interactive Chat Interface

Skill Definition Files (skill.md)

Key Design Pattern

Knowledge Base & Retrieval-Augmented Generation (RAG)

How It Works

Adding Knowledge Documents

Example: Magnetics Knowledge Base

Storage & Persistence

Example Output:

Running Tests

Run All Tests

Run Tests for a Specific Module

Run Tests with Coverage

Available Tools

Field Calculations

solenoid_field

biot_savart_wire

magnetic_flux

energy_stored

Magnetic Circuit Tools

reluctance

mmf_required

Material Properties

material_lookup

Unit Conversions

unit_convert

Example Interactions

Query 1: Solenoid Design

Query 2: Magnetic Circuit Design

Query 3: Energy in a Magnetic Field

Testing

Troubleshooting

"ANTHROPIC_API_KEY not found"

"No skills found in skills/ directory"

Dependencies

Further Reading

Reviews

`solenoid_field`

`biot_savart_wire`

`magnetic_flux`

`energy_stored`

`reluctance`

`mmf_required`

`material_lookup`

`unit_convert`