Skip to content
Skills Library
AI & agents · Analysis

debug-agent

/debug-agent

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.

Repository
skills ↗
Licence
Apache-2.0
Last repository change
22.10.2026

Assessment and security

90/ 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.
Content25 / 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
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

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

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

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.

Original author description

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.

How it works

  1. Workflow
  2. Boundaries
Original SKILL.md headings · 35 lines, 267 words
SKILL.md preview
---
name: debug-agent
description: >-
  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.
---

# 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

1. Find existing tracing configuration, tracking URI, and experiment. Do not
   recommend reinstalling or reinstrumenting MLflow when tracing already works.
2. 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.
3. 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.
4. 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.
5. Correlate trace evidence with source code as needed. Reading source is fine;
   do not settle on a diagnosis without confirming it against the trace.
6. Report: observed behavior, expected behavior, trace evidence, root cause,
   confidence, and the smallest likely fix. Do not create tests or scorers for a
   diagnosis-only request.

## Boundaries

- If no trace can be produced because the app is uninstrumented, load
  `instrumenting-with-mlflow-tracing` and explain the limitation.
- Log the user's complaint as HUMAN feedback only when a concrete trace is
  identified and doing so is authorized.
- If the user asks to implement the fix, invoke `fix-agent-issue` with the trace
  ID and diagnosis so it can write regression coverage before editing.
Files in this package (2)
  • SKILL.md 2 KB
  • agents/openai.yaml 1 KB

Versions

RepositoryScoreLicence
This page · mlflow/skills90Apache-2.0
HarryBurd33/debug-agent91MIT

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

Database snapshot: 13.11.2026 · package version 28aa846492cd (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

  • 95analyzing-mlflow-trace
    Analyzes a single MLflow trace to answer a user query about it. Use when the user provides a trace ID and asks to debug, investigate, find issues, root-cause errors, understand behavior, or analyze quality. Triggers on "analyze this trace", "what went wrong with this trace",…
  • 100mlflow-agent-improvement
    Fix or change an AI agent's behavior using MLflow traces and regression tests. Use for wrong answers, missing tool calls, new business rules, or context and token-cost optimization. Diagnose first, prove a regression fails, implement the smallest fix, and verify it passes…
  • 100mlflow-traces
    Use when working with MLflow traces: debugging via MCP tools, analyzing performance, logging feedback, writing custom scorers/evaluations, or cleaning up trace data
  • 100eval-mlflow
    MLflow integration for evaluation — sync datasets, log run results, push/pull feedback between the harness and MLflow traces. Use when the user wants to log eval results to MLflow, sync test cases to MLflow datasets, connect judge scores to traces, pull MLflow annotations for…
  • 90trace-debug
    Debug AI system behavior using traces — prompt reconstruction, output comparison, failure attribution. Use when asked "why did the model output this", "debug this LLM failure", or "reconstruct the prompt".
  • 100databricks-genai-evaluation-observability
    Use this skill to review generative-AI evaluation, tracing, and observability design on Databricks: MLflow Tracing instrumentation and span design, trace storage and governance, `mlflow.genai.evaluate()` harness design, the judge-versus-scorer distinction, built-in judge…

Feedback and reports

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