Skip to content
Skills Library
AI & agents · Building & coding

create-atomic-agent

/create-atomic-agent

Build and wire an `AtomicAgent[InSchema, OutSchema]` — schemas, `AgentConfig`, `SystemPromptGenerator`, provider client, history, hooks, optional context providers. Use when the user asks to "create an agent", "add another agent", "build an `AtomicAgent`", "wire up an agent", "make a planner/router/extractor agent", or runs `/atomic-agents:create-atomic-agent`.

Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Build and wire an `AtomicAgent[InSchema, OutSchema]` — schemas, `AgentConfig`, `SystemPromptGenerator`, provider client, history, hooks, optional context providers. Use when the user asks to "create an agent", "add another agent", "build an `AtomicAgent`", "wire up an agent", "make a planner/router/extractor agent", or runs `/atomic-agents:create-atomic-agent`.

Triggers from the description

create an agentadd another agentbuild an `AtomicAgent`wire up an agentmake a planner/router/extractor agent
Original author description

Build and wire an `AtomicAgent[InSchema, OutSchema]` — schemas, `AgentConfig`, `SystemPromptGenerator`, provider client, history, hooks, optional context providers. Use when the user asks to "create an agent", "add another agent", "build an `AtomicAgent`", "wire up an agent", "make a planner/router/extractor agent", or runs `/atomic-agents:create-atomic-agent`.

How it works

  1. When this fires vs the umbrella framework skill
  2. Phase 1 — Clarify
  3. Phase 2 — Plan
  4. Phase 3 — Implement
  5. Phase 4 — Run and verify
  6. Phase 5 — Hand off
  7. Anti-patterns
Original SKILL.md headings · 157 lines, 865 words
SKILL.md preview
---
name: create-atomic-agent
description: Build and wire an `AtomicAgent[InSchema, OutSchema]` — schemas, `AgentConfig`, `SystemPromptGenerator`, provider client, history, hooks, optional context providers. Use when the user asks to "create an agent", "add another agent", "build an `AtomicAgent`", "wire up an agent", "make a planner/router/extractor agent", or runs `/atomic-agents:create-atomic-agent`.
---

# Create an Atomic Agent

An agent is an LLM-backed transformer from one `BaseIOSchema` to another. Building one means: design the schemas, write the system prompt, wire the provider client, build the `AgentConfig`, instantiate `AtomicAgent[In, Out]`.

For deep material (streaming, token counting, hooks, multi-agent memory), the authority is `../framework/references/agents.md` plus `providers.md`, `prompts.md`, and `memory.md`. This skill is the action-oriented path: clarify → write → run.

## When this fires vs the umbrella `framework` skill

- **This skill**: the user is creating or wiring a specific agent — "add a planner agent", "build a Q&A agent", "make a router that classifies tickets".
- **`framework` skill**: questions about Atomic Agents in general, or the user is doing something other than authoring an agent.

## Phase 1 — Clarify

Bundle into one message:

1. **What should the agent do?** One sentence. Becomes the persona / `background` line.
2. **Inputs and outputs.** Use `BasicChatInputSchema` / `BasicChatOutputSchema` for free-form chat. Use a custom pair for anything structured (extraction, classification, planning, routing). When custom, branch to the `create-atomic-schema` skill for the schema authoring.
3. **Provider.** OpenAI / Anthropic / Groq / Ollama / Gemini / OpenRouter / MiniMax. Default: whatever the project already uses; otherwise OpenAI.
4. **Conversational?** Yes → wire a `ChatHistory`. No (single-shot transformer) → omit it for stateless behavior.
5. **Context providers.** Anything to inject into the prompt at runtime (current time, user identity, retrieved docs)? If yes, plan to also use the `create-atomic-context-provider` skill afterwards.

Skip anything already settled in context.

## Phase 2 — Plan

State the plan in one short block:

- File: `<project>/agents/<agent_name>.py` (or directly in `main.py` for a tiny project — see `../framework/references/project-structure.md`).
- Schemas: which pair, where they live.
- Provider + model + Instructor mode. Default models: OpenAI `gpt-5-mini`, Anthropic `claude-haiku-4-5`, Groq `llama-3.3-70b-versatile`, Ollama `llama3.1`, Gemini `gemini-2.5-flash`.
- `SystemPromptGenerator` content — three sections: `background`, `steps`, `output_instructions`.
- History? Hooks? Context providers?

## Phase 3 — Implement

### Canonical imports (do not deviate)

```python
from atomic_agents import (
    AtomicAgent, AgentConfig,
    BasicChatInputSchema, BasicChatOutputSchema,
)
from atomic_agents.context import ChatHistory, SystemPromptGenerator
from instructor import Mode
```

### Wire the provider client (always Instructor-wrapped)

The full per-provider matrix lives in `../framework/references/providers.md`. Quick recap:

```python
# OpenAI — default mode is Mode.TOOLS
import os, instructor, openai
client = instructor.from_openai(openai.OpenAI(api_key=os.environ["OPENAI_API_KEY"]))
model = "gpt-5-mini"
api_params: dict = {}

# Anthropic — Mode.TOOLS, max_tokens REQUIRED in model_api_parameters
import anthropic
client = instructor.from_anthropic(anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"]))
model = "claude-haiku-4-5"
api_params = {"max_tokens": 4096}

# Gemini — Mode.GENAI_TOOLS, assistant_role="model"
from google import genai
client = instructor.from_genai(genai.Client(api_key=os.environ["GEMINI_API_KEY"]), mode=Mode.GENAI_TOOLS)
model = "gemini-2.5-flash"
api_params = {}

# Groq / Ollama / MiniMax — Mode.JSON in both factory and AgentConfig
```

### Build the agent

```python
from atomic_agents import AtomicAgent, AgentConfig
from atomic_agents.context import ChatHistory, SystemPromptGenerator

agent = AtomicAgent[MyInput, MyOutput](
    config=AgentConfig(
        client=client,
        model=model,
        history=ChatHistory(),  # omit for stateless
        system_prompt_generator=SystemPromptGenerator(
            background=["You are a concise research assistant."],
            steps=[
                "Read the question carefully.",
                "Decide what minimum information answers it.",
                "Produce the answer in the required schema.",
            ],
            output_instructions=[
                "Reply under 100 words.",
                "If unsure, set status='error' and explain why.",
            ],
        ),
        # Provider-specific knobs — match the Instructor factory
        # mode=Mode.TOOLS,                         # OpenAI / Anthropic / OpenRouter
        # mode=Mode.JSON,                          # Groq / Ollama / MiniMax
        # mode=Mode.GENAI_TOOLS, assistant_role="model",  # Gemini
        model_api_parameters=api_params or {"temperature": 0.2},
    )
)
```

### Generics carry the truth

`AtomicAgent[MyInput, MyOutput]` — write the type parameters explicitly. The framework reads them at class-definition time. Do **not** rely on subclass-level `input_schema` / `output_schema` class attributes.

### Provider-specific knobs (most common gotchas)

- **Anthropic** without `max_tokens` in `model_api_parameters` → API rejects every call.
- **Gemini** without `assistant_role="model"` → role mismatch on every turn.
- **Groq / Ollama / MiniMax** with `Mode.TOOLS` → tools formatted in a way the provider does not accept; flip to `Mode.JSON`.
- Reasoning models (o-series, GPT-5 reasoning variants) → often want `system_role=None` and `reasoning_effort` in `model_api_parameters`.

## Phase 4 — Run and verify

```python
out = agent.run(MyInput(...))
print(out)
```

Quick smoke test without paying for a real call:

```bash
uv run python -c "from <project>.agents.<agent_name> import agent; print(type(agent).__name__, '->', agent.input_schema.__name__, '/', agent.output_schema.__name__)"
```

If output validation fails repeatedly, the `parse:error` hook has the details — see `../framework/references/hooks.md` for registration.

## Phase 5 — Hand off

Tell the user:

- How to call `agent.run(...)` (and `run_async`, `run_stream`, `run_async_stream` when appropriate).
- Which env var to set for the provider key.
- Optional next steps:
  - Tools the agent should be able to invoke → `create-atomic-tool` skill.
  - Dynamic data injected into the prompt → `create-atomic-context-provider` skill.
  - Custom schemas → `create-atomic-schema` skill.
  - Multiple agents working together → `../framework/references/orchestration.md`.
  - Telemetry / retries / logging → `../framework/references/hooks.md`.
  - Conversation persistence, summarization, multi-agent memory → `../framework/references/memory.md`.

## Anti-patterns

- Forgetting to wrap the client with `instructor.from_*` — structured outputs silently stop working.
- `BaseModel` instead of `BaseIOSchema` for the agent's input or output type.
- `AgentConfig.mode` out of sync with the Instructor factory mode.
- `assistant_role="assistant"` on Gemini — must be `"model"`.
- Missing `max_tokens` on Anthropic — every call fails.
- Hardcoded API keys in the source — read from env.
- Unbounded `ChatHistory` in a long-running service — monitor `agent.get_context_token_count().utilization` or set `max_messages`.

For deep material — streaming, async, token counting, hooks, multi-agent history — load `../framework/references/agents.md`.

Versions

The database has no other skills named create-atomic-agent.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 1336e89dbbc3 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100framework
    Guide for the Atomic Agents Python framework — schemas, agents, tools, context providers, prompts, orchestration, and provider configuration. Use when code imports from `atomic_agents`, defines an `AtomicAgent`, `BaseTool`, or `BaseIOSchema`, or the user asks about multi-agent…
  • 100create-atomic-tool
    Build a `BaseTool[InSchema, OutSchema]` subclass — input/output schemas, `BaseToolConfig`, `run()` (and optional `run_async()`), env-driven secrets, typed failure outputs. Use when the user asks to "add a tool", "create a tool", "wrap an API as a tool", "build a `BaseTool`",…
  • 100nemo-fabric-build-adapter
    Build, migrate, review, and maintain third-party NVIDIA NeMo Fabric adapters against the public adapter contract. Use when creating adapter or target descriptors, mapping AgentConfig into an agent harness or custom-agent runtime, implementing start/invoke/stop, declaring schemas…
  • 100agent-creation
    Create a new Stencila agent. Use when asked to create, write, scaffold, or set up an agent directory or AGENT.md file. Covers workspace and user-level agents with model, provider, tool, trust, and MCP configuration.
  • 100agent-sdk-quickstart
    Build a first agent with the Claude Agent SDK (TypeScript or Python): install, run query(), read result messages, restrict tools and permissions, add custom tools through an in-process MCP server, and guard tool calls with hooks. Also explains when to pick the Agent SDK, the…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.