# debug-agent

> Claude/Codex skill by [@mlflow](https://omgskills.com/library/mlflow/index.md) · 82 stars · Updated 2026-10-23

Root-causes AI agent failures from MLflow traces without requiring a code change, regression suite, scorer, or evaluation run. Use when the user asks to debug, investigate, explain, or determine why an agent produced an output. Prefer an existing matching trace; reproduce only when no usable trace exists.

## Install

```sh
git clone https://github.com/mlflow/skills /tmp/skills && ln -s /tmp/skills/debug-agent ~/.claude/skills/debug-agent
```

## From README

Debug Agent Diagnose the failure and report evidence. Do not edit the agent unless the user also asks for a fix; for behavior changes, hand off to fix-agent-issue after the diagnosis. Workflow Find existing tracing configuration, tracking URI, and experiment. Do not recommend reinstalling or reinstrumenting MLflow when tracing already works. Find a trace matching the reported input, time, session, user, or trace ID. If one exists, use it directly. Do not reproduce a production-only or externally dependent failure merely to satisfy a workflow. Only when no usable trace exists, reproduce the issue once through the normal instrumented entry point and retrieve the resulting trace. If reproduction is unsafe or impossible, state what evidence is missing and stop. Inspect the matching trace span by span. Read assessments first, then inputs, outputs, errors, LLM calls, retrieval results, and tool calls. Use analyze-mlflow-trace for detailed trace anatomy.

## Links

- HTML page: https://omgskills.com/library/mlflow/skills/debug-agent/
- GitHub: https://github.com/mlflow/skills
- Author: [@mlflow](https://omgskills.com/library/mlflow/index.md)

## More from this repo

- [agent-evaluation](https://omgskills.com/library/mlflow/skills/agent-evaluation/index.md) — Use this when you need to EVALUATE OR IMPROVE or OPTIMIZE an existing LLM agent's output quality - including improving...
   - [@mlflow](https://omgskills.com/library/mlflow/index.md) · 82 stars
- [analyzing-mlflow-session](https://omgskills.com/library/mlflow/skills/analyze-mlflow-chat-session/index.md) — Analyzes an MLflow session — a sequence of traces from a multi-turn chat conversation or interaction.
   - [@mlflow](https://omgskills.com/library/mlflow/index.md) · 82 stars
- [analyzing-mlflow-trace](https://omgskills.com/library/mlflow/skills/analyze-mlflow-trace/index.md) — Analyzes a single MLflow trace to answer a user query about it.
   - [@mlflow](https://omgskills.com/library/mlflow/index.md) · 82 stars