# Troubleshoot

Diagnose and fix a failing or misbehaving Atomic Agents app, import errors, schema...

- Repository: https://github.com/Eigenwise/atomic-agents (6314 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-10-29
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add Eigenwise/atomic-agents --skill troubleshoot -g -a claude-code -y`
Codex: `npx skills add Eigenwise/atomic-agents --skill troubleshoot -g -a codex -y`
Cursor: `npx skills add Eigenwise/atomic-agents --skill troubleshoot -g -a cursor -y`
Gemini CLI: `npx skills add Eigenwise/atomic-agents --skill troubleshoot -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add Eigenwise/atomic-agents`

## 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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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

The rest: https://github.com/Eigenwise/atomic-agents/blob/HEAD/claude-plugin/atomic-agents/skills/troubleshoot/SKILL.md