Skip to content

Building AI agents, atomically

Plugin 2.2.0: troubleshoot skill, new-app emits AGENTS.md + CLAUDE.md

Eigenwise73dbc8be54f4
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index e959f3e..33a6a4c 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -9,8 +9,8 @@
"plugins": [
{
"name": "atomic-agents",
- "description": "Skills plus explorer and reviewer subagents for building, scaffolding, understanding, and auditing applications with the Atomic Agents Python framework. Progressive-disclosure references for schemas, agents, tools, context providers, prompts, orchestration, memory, hooks, providers, project structure, and testing — plus isolated-context subagents for codebase mapping and code review, and a new-app scaffolder.",
- "version": "2.1.0",
+ "description": "Skills plus explorer and reviewer subagents for building, scaffolding, debugging, understanding, and auditing applications with the Atomic Agents Python framework. Progressive-disclosure references for schemas, agents, tools, context providers, prompts, orchestration, memory, hooks, providers, project structure, and testing — plus a troubleshoot diagnostic, isolated-context subagents for codebase mapping and code review, and a new-app scaffolder.",
+ "version": "2.2.0",
"author": {
"name": "Kenny Vaneetvelde",
"email": "[email protected]"
diff --git a/claude-plugin/atomic-agents/.claude-plugin/plugin.json b/claude-plugin/atomic-agents/.claude-plugin/plugin.json
index 6bf580a..7638345 100644
--- a/claude-plugin/atomic-agents/.claude-plugin/plugin.json
+++ b/claude-plugin/atomic-agents/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "atomic-agents",
- "version": "2.1.0",
- "description": "Skills plus explorer and reviewer subagents for building, scaffolding, understanding, and auditing applications with the Atomic Agents Python framework. Includes the umbrella `framework` skill, action-oriented `create-atomic-schema` / `create-atomic-agent` / `create-atomic-tool` / `create-atomic-context-provider` skills, the `new-app` scaffolder, progressive-disclosure reference material for prompts, orchestration, memory, hooks, providers, project structure, and testing, and isolated-context subagents for codebase mapping and code review.",
+ "version": "2.2.0",
+ "description": "Skills plus explorer and reviewer subagents for building, scaffolding, debugging, understanding, and auditing applications with the Atomic Agents Python framework. Includes the umbrella `framework` skill, action-oriented `create-atomic-schema` / `create-atomic-agent` / `create-atomic-tool` / `create-atomic-context-provider` skills, the `troubleshoot` diagnostic skill, the `new-app` scaffolder (emits AGENTS.md + CLAUDE.md), progressive-disclosure reference material for prompts, orchestration, memory, hooks, providers, project structure, and testing, and isolated-context subagents for codebase mapping and code review.",
"author": {
"name": "Kenny Vaneetvelde",
"email": "[email protected]"
diff --git a/claude-plugin/atomic-agents/CHANGELOG.md b/claude-plugin/atomic-agents/CHANGELOG.md
index 2819cf6..4c23bf6 100644
--- a/claude-plugin/atomic-agents/CHANGELOG.md
+++ b/claude-plugin/atomic-agents/CHANGELOG.md
@@ -5,7 +5,13 @@ All notable changes to the Atomic Agents Claude Code Plugin will be documented i
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).
-## [Unreleased]
+## [2.2.0] - 2026-07-18
+
+### Added
+
+- **`troubleshoot` skill** — diagnostic workflow for the "my agent is broken" moment. Symptom table keyed on the framework's real error messages (docstring enforcement, `AgentConfig.client` validation, provider role/mode errors, `HTTP_STREAM`, history misuse), each with a mechanical fix and a re-run verification step. Escalation map into the `framework` reference files; `framework` routes concrete errors here.
+- **`new-app` emits `AGENTS.md` + `CLAUDE.md`** into every scaffolded project — framework conventions any coding assistant reads, with `CLAUDE.md` as a one-line `@AGENTS.md` import (the documented, Windows-safe pattern). Template includes per-provider quirk lines.
+- Cross-tool install path documented: `npx skills add eigenwise/atomic-agents` works for Cursor, Copilot, Codex, Windsurf, Gemini CLI, and other skills-compatible assistants (discovery via the repo's `.claude-plugin/marketplace.json`).
### Changed
@@ -15,6 +21,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Fixed
- Quoted `argument-hint` YAML values in skill frontmatter so GitHub Copilot CLI ≥1.0.65 loads all skills ([#265](https://github.com/eigenwise/atomic-agents/pull/265)).
+- The repo's maintainer-only `release` skill no longer leaks into `npx skills` discovery (`metadata.internal: true`).
## [2.1.0] - 2026-04-29
diff --git a/claude-plugin/atomic-agents/README.md b/claude-plugin/atomic-agents/README.md
index 24eabc3..373cfce 100644
--- a/claude-plugin/atomic-agents/README.md
+++ b/claude-plugin/atomic-agents/README.md
@@ -4,10 +4,12 @@ A Claude Code plugin that gives Claude deep, just-in-time knowledge of the [Atom
## What you get
-Two skills + two subagents, loaded on demand:
+Seven skills + two subagents, loaded on demand:
- **`framework` skill** — auto-triggered when Claude sees atomic-agents code. Orients Claude on the framework and exposes eleven focused reference files (schemas, agents, tools, context providers, prompts, orchestration, memory, hooks, providers, project structure, testing). Progressive disclosure keeps the parent context lean.
-- **`new-app` skill** — slash-invokable scaffolder (`/atomic-agents:new-app`). Four short questions and produces a runnable project with the right `pyproject.toml`, environment file, and first agent.
+- **Four creation skills** — `create-atomic-schema`, `create-atomic-agent`, `create-atomic-tool`, `create-atomic-context-provider`. Each walks a clarify → write → verify → hand-off workflow for its component type, auto-triggering on the matching phrasing.
+- **`troubleshoot` skill** — auto-triggered on errors and tracebacks from atomic-agents code. Symptom table keyed on the framework's real error messages (provider role/mode mismatches, schema docstring enforcement, history misuse, MCP transports), each with a mechanical fix and a verification step.
+- **`new-app` skill** — slash-invokable scaffolder (`/atomic-agents:new-app`). Four short questions and produces a runnable project with the right `pyproject.toml`, environment file, first agent, and an `AGENTS.md` + `CLAUDE.md` pair so any coding assistant knows the conventions from the first commit.
- **`atomic-explorer` subagent** — auto-triggered (or `Task`-invoked) when you ask to explore, map, or understand an existing atomic-agents codebase. Reads the project in isolated context and returns a compact architecture map (agents, tools, schemas, context providers, orchestration, essential-reading list) without polluting the parent thread with every file it had to open to build that map.
- **`atomic-reviewer` subagent** — auto-triggered (or `Task`-invoked) when you ask for a review, audit, or check of atomic-agents code. Runs in isolated context with read-only tools so the file-exploration load never pollutes the parent thread. Focuses only on framework-specific concerns (BaseIOSchema invariants, Instructor wrapping, per-provider role and mode, context-provider I/O hygiene, orchestration hazards, common API misuses). Returns a single confidence-filtered structured report. Complements generic code review; does not replace it.
diff --git a/claude-plugin/atomic-agents/skills/framework/SKILL.md b/claude-plugin/atomic-agents/skills/framework/SKILL.md
index 1028326..0fa49ac 100644
--- a/claude-plugin/atomic-agents/skills/framework/SKILL.md
+++ b/claude-plugin/atomic-agents/skills/framework/SKILL.md
@@ -74,6 +74,7 @@ For the four most common authoring tasks, dedicated atomic skills give a step-by
| "create an agent" / "add another agent" / "wire up an `AtomicAgent`" | `atomic-agents:create-atomic-agent` |
| "add a tool" / "wrap an API as a tool" / "build a `BaseTool`" | `atomic-agents:create-atomic-tool` |
| "add a context provider" / "inject X into the prompt" / "wire up RAG" | `atomic-agents:create-atomic-context-provider` |
+| "my agent is broken / crashing / returning garbage" + a traceback or error | `atomic-agents:troubleshoot` |
These skills auto-trigger on the matching phrasing. The reference files below are what they (and you) load for deeper material.
@@ -123,6 +124,10 @@ Delegate to the `atomic-explorer` subagent when the project has more than a hand
For a small project (a single `main.py` + one or two agents), reading the files directly in the main thread is fine — the isolation upside is thin.
+## When something is failing right now
+
+A concrete error, traceback, or wrong-output report routes to the `troubleshoot` skill — it carries a symptom table keyed on the framework's real error messages plus the per-provider failure modes. Review is for code that isn't currently on fire; troubleshoot is for code that is.
+
## When the user wants a review
Delegate to the `atomic-reviewer` subagent — do not review in the main thread. The subagent runs in isolated context with read-only tools, keeping the review's file exploration out of the parent conversation. Invoke it via the `Task` tool with the scope (diff, paths, or module) in the prompt. Review findings return as a single structured report the parent thread can act on.
diff --git a/claude-plugin/atomic-agents/skills/new-app/SKILL.md b/claude-plugin/atomic-agents/skills/new-app/SKILL.md
index 4300fc3..f83aa72 100644
--- a/claude-plugin/atomic-agents/skills/new-app/SKILL.md
+++ b/claude-plugin/atomic-agents/skills/new-app/SKILL.md
@@ -47,6 +47,8 @@ Create files in this order. Verify each step before proceeding.
├── .env.example
├── .gitignore
├── README.md
+├── AGENTS.md
+├── CLAUDE.md
└── <project_name>/
├── __init__.py
└── main.py
@@ -95,6 +97,42 @@ Per-provider AgentConfig knobs — match the Instructor factory mode on `AgentCo
Short. Include: what the project is, how to install (`uv sync` or `pip install -e .[dev]`), how to set the API key (`cp .env.example .env` and edit), how to run (`uv run python -m <project_name>.main` or equivalent).
+### `AGENTS.md` and `CLAUDE.md`
+
+Every scaffolded project ships agent instructions so any coding assistant (Cursor, Codex, Copilot, Gemini CLI, ...) knows the framework conventions from the first commit. `CLAUDE.md` contains exactly one line — `@AGENTS.md` — so Claude Code reads the same file without duplication.
+
+`AGENTS.md` template (substitute project specifics):
+
+```markdown
+# <Project Name>
+
+<One-line description from the agent-type answer.>
+
+Built with [Atomic Agents](https://github.com/eigenwise/atomic-agents) — a schema-driven
+framework on Instructor + Pydantic. Docs for LLMs:
+https://eigenwise.github.io/atomic-agents/llms.txt
+
+## Framework conventions
+
+- Import from the top-level package: `from atomic_agents import AtomicAgent, AgentConfig,
+ BaseIOSchema, BaseTool`; context pieces from `atomic_agents.context`.
+- Agents are `AtomicAgent[InputSchema, OutputSchema](config=AgentConfig(...))` — the type
+ parameters carry runtime information, keep them accurate.
+- The LLM client must be wrapped with Instructor before it goes into `AgentConfig.client`.
+- Every `BaseIOSchema` subclass needs a non-empty docstring and `Field(..., description=...)`
+ on each field — both flow into the LLM prompt.
+- Provider knobs (`temperature`, `max_tokens`, ...) go in `AgentConfig.model_api_parameters`.
+- Provider: <chosen provider>. <Provider-specific line from the matrix below, if any.>
+
+## Commands
+
+- Install: `uv sync` (or the pip equivalent chosen at scaffold time)
+- Run: `uv run python -m <project_name>.main`
+- Test: `uv run pytest`
+```
+
+Provider-specific lines for the template: Anthropic → "Requires `max_tokens` in `model_api_parameters`; `mode=Mode.TOOLS`." Gemini → "`assistant_role='model'` and `mode=Mode.GENAI_TOOLS`." Groq/Ollama/MiniMax → "`mode=Mode.JSON` on both the Instructor factory and `AgentConfig`." OpenAI/OpenRouter → omit.
+
## Phase 4 — Install and smoke-test
Execute the install step:
diff --git a/claude-plugin/atomic-agents/skills/troubleshoot/SKILL.md b/claude-plugin/atomic-agents/skills/troubleshoot/SKILL.md
new file mode 100644
index 0000000..81b23c5
--- /dev/null
+++ b/claude-plugin/atomic-agents/skills/troubleshoot/SKILL.md
@@ -0,0 +1,66 @@
+---
+name: troubleshoot
+description: Diagnose and fix a failing or misbehaving Atomic Agents app — import errors, schema validation failures, empty or malformed LLM output, provider role/mode errors, history and context problems, MCP transport errors. Use when the user reports an error, traceback, or wrong behavior in atomic-agents code, asks "why is my agent not working / crashing / returning garbage", or pastes a `ValidationError`, `ImportError`, or provider API error from an atomic-agents project.
+---
+
+# Troubleshoot an Atomic Agents App
+
+Diagnostic workflow for the "it's broken" moment. Most atomic-agents failures are one of a dozen known causes with mechanical fixes. Match the symptom, apply the fix, verify by re-running.
+
+## Workflow
+
+1. **Capture the failure.** Get the exact traceback or wrong-output sample plus the code that produces it (agent construction, schemas, client wiring). If the user pasted only a fragment of the error, ask for the full traceback before guessing.
+2. **Match against the symptom table below.** The quoted strings are the framework's real messages — match on them.
+3. **Apply the fix and re-run** the failing snippet. Do not declare the problem solved without a passing re-run.
+4. **No match?** Load the reference for the failing area (table at the bottom) and reason from there. For a whole-codebase audit rather than one failure, delegate to the `atomic-reviewer` subagent instead.
+
+## Symptom table
+
+### Import and definition errors
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `ImportError`/`ModuleNotFoundError` on `atomic_agents.lib.*`, `atomic_agents.agents.base_agent`, or `BaseAgent` | v1 import paths, removed in v2 | Import from the top level: `from atomic_agents import AtomicAgent, AgentConfig, BaseIOSchema, BaseTool`; context pieces from `atomic_agents.context` |
+| `ValueError: <Name> must have a non-empty docstring to serve as its description` at import time | `BaseIOSchema` subclass without a docstring | Add a docstring describing the schema — it flows into the LLM prompt, so write it for the model |
+| `ValidationError` when constructing `AgentConfig`, complaining about `client` | Raw provider SDK client passed; `AgentConfig.client` requires an Instructor-wrapped client | Wrap it: `instructor.from_openai(...)`, `instructor.from_anthropic(...)`, `instructor.from_genai(...)` |
+| `TypeError` about missing type parameters, or output typed as `BasicChatOutputSchema` when a custom schema was expected | `AtomicAgent` instantiated without generics | Write `AtomicAgent[InputSchema, OutputSchema](config=...)` — the type parameters carry runtime information (they drive Instructor's `response_model`) |
+
+### Provider errors at run time
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Anthropic error mentioning `max_tokens` is required | Anthropic requires it per request | `model_api_parameters={"max_tokens": 4096}` on `AgentConfig` |
+| Gemini error about invalid role / role ordering | Gemini names the assistant role `model` | `assistant_role="model"` on `AgentConfig`; use `instructor.from_genai(...)` with `mode=Mode.GENAI_TOOLS` and match `AgentConfig.mode` |
+| Empty output, `None` fields, or JSON-parse noise on Groq / Ollama / MiniMax | Provider needs JSON mode; factory and config modes disagree | Create the client with `Mode.JSON` and set `mode=Mode.JSON` on `AgentConfig` — the two must always match |
+| Works on OpenAI, breaks on another provider with no code change | Provider quirks live in `AgentConfig`, not the agent | Check the per-provider matrix in [framework/references/providers.md](../framework/references/providers.md) |
+
+### Wrong or degraded behavior (no exception)
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Pydantic `ValidationError` from inside `run()` after retries | Model can't satisfy the output schema | Improve field `description=`s and the schema docstring first; loosen over-tight constraints; only then consider a stronger model. Inspect attempts via the `parse:error` hook |
+| Agent "forgets" earlier turns | Fresh `ChatHistory` created per call, or none passed | Create one `ChatHistory` and reuse it across `run()` calls |
+| Context/cost grows without bound in long sessions | Unbounded history | Set `max_context_tokens` on `AgentConfig` — oldest turns are trimmed automatically |
+| Every `run()` is slow before the LLM call even starts | Blocking I/O in a context provider's `get_info()` | `get_info()` runs on every `run()`; move fetching out, cache, or make the provider hold precomputed state |
+| `history.load(...)` "doesn't work" | Called as a classmethod | `load` is an instance method that mutates in place: `history = ChatHistory(); history.load(saved)`. `dump()` returns a JSON string |
+
+### MCP interop
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `AttributeError: STREAMABLE_HTTP` | No such member | `MCPTransportType.HTTP_STREAM` (others: `SSE`, `STDIO`) |
+| MCP tools fetch but calls fail | Transport/endpoint mismatch | See MCP section of [framework/references/tools.md](../framework/references/tools.md) and the `mcp-agent` example |
+
+## Escalation map
+
+| Failing area | Load |
+|---|---|
+| Schema design, validators | [framework/references/schemas.md](../framework/references/schemas.md) |
+| Agent config, run modes, streaming | [framework/references/agents.md](../framework/references/agents.md) |
+| Provider wiring, roles, modes | [framework/references/providers.md](../framework/references/providers.md) |
+| History, persistence, multi-agent memory | [framework/references/memory.md](../framework/references/memory.md) |
+| Hooks, retries, telemetry | [framework/references/hooks.md](../framework/references/hooks.md) |
+| Tools, MCP | [framework/references/tools.md](../framework/references/tools.md) |
+| Orchestration between agents | [framework/references/orchestration.md](../framework/references/orchestration.md) |
+
+Related skills: `framework` (general guidance, auto-triggers), `create-atomic-agent` / `create-atomic-schema` / `create-atomic-tool` / `create-atomic-context-provider` (building rather than fixing). For a review of code that isn't currently failing, use the `atomic-reviewer` subagent.
diff --git a/docs/guides/quickstart.md b/docs/guides/quickstart.md
index ef3a4be..d37ff57 100644
--- a/docs/guides/quickstart.md
+++ b/docs/guides/quickstart.md
@@ -439,6 +439,44 @@ To run any of these examples:
uv run python chatbot.py
```
+## Set Up Your Project for AI Coding Assistants
+
+If you build with an AI assistant (Claude Code, Cursor, Copilot, Codex, Gemini CLI, ...), two small steps make it know Atomic Agents instead of guessing at the API:
+
+1. **Install the agent skills** — guided workflows for creating schemas, agents, tools, and context providers, plus a troubleshooting diagnostic:
+
+ ```bash
+ # Claude Code
+ /plugin marketplace add eigenwise/atomic-agents
+ /plugin install atomic-agents@eigenwise
+
+ # Any other skills-compatible assistant
+ npx skills add eigenwise/atomic-agents
+ ```
+
+2. **Drop an `AGENTS.md` into your project root** so every assistant picks up the framework conventions. Add a `CLAUDE.md` containing just `@AGENTS.md` so Claude Code reads the same file:
+
+ ```markdown
+ # My Project
+
+ Built with [Atomic Agents](https://github.com/eigenwise/atomic-agents) — a schema-driven
+ framework on Instructor + Pydantic. Docs for LLMs:
+ https://eigenwise.github.io/atomic-agents/llms.txt
+
+ ## Framework conventions
+
+ - Import from the top-level package: `from atomic_agents import AtomicAgent, AgentConfig,
+ BaseIOSchema, BaseTool`; context pieces from `atomic_agents.context`.
+ - Agents are `AtomicAgent[InputSchema, OutputSchema](config=AgentConfig(...))` — the type
+ parameters carry runtime information, keep them accurate.
+ - The LLM client must be wrapped with Instructor before it goes into `AgentConfig.client`.
+ - Every `BaseIOSchema` subclass needs a non-empty docstring and `Field(..., description=...)`
+ on each field — both flow into the LLM prompt.
+ - Provider knobs (`temperature`, `max_tokens`, ...) go in `AgentConfig.model_api_parameters`.
+ ```
+
+Projects scaffolded with the `new-app` skill get both files automatically. Assistants can also pull the full docs from [llms.txt](https://eigenwise.github.io/atomic-agents/llms.txt) or query them via [Context7](https://context7.com/eigenwise/atomic-agents).
+
## Next Steps
After trying these examples, you can: