trace-agent
Skill1 starsChanged 5 months agoMITView on GitHub
Debug a single LangChain / LangGraph / tool-use agent run — dump the step and tool-call trace, find where it diverged from the intended path, and isolate the bad prompt, tool, or state. Use when an agent did the wrong thing and you need to know why. Trigger phrases "trace this run", "why did the agent do that", "debug this agent run".
In this repository16 other files it gives its agents.
- catchupSkill
- claude-mdSkill
- context-budgetSkill
- db-querySkill
- debug-fixSkill
- eval-agentSkill
- explainSkill
- fix-issueSkill
- incident-ruleSkill
- pr-reviewSkill
- refactorSkill
- secrets-checkSkill
- setup-projectSkill
- shipSkill
- tddSkill
- test-writerSkill
The file
Files
trace-agent
Trigger: "trace this run" / "why did the agent do that" / "debug this agent run"
Standing rules: ../_conventions.md.
An agent went wrong on one run. Find the exact step where it diverged — don't theorize from the top. Read the actual trace. If it's an intermittent LLM issue, say so rather than inventing a deterministic cause.
Steps
- Get the trace. Find how this project records runs: LangSmith, a LangGraph checkpoint/thread, structured logs, or a captured transcript. If tracing isn't on, STOP and offer to enable it (LangSmith env vars, a callback handler, or a run logger) — don't reconstruct a run from imagination.
- Confirm the setup. Model id and provider (read the client code — don't
assume), the system prompt, the tool schemas the agent had, and the input for
this run. For Claude, check the
claude-apireference for tool-use behavior. - Walk the steps in order. For each step capture: the model's reasoning/ output, which tool it called, the args, the tool result, and the resulting state. Mark the FIRST step where it diverged from what should have happened.
- Isolate the cause at the divergence point. One of:
- Prompt — ambiguous/missing instruction let the model choose wrong.
- Tool schema — bad description or arg names misled the tool choice.
- Tool result — the tool returned wrong/empty data and the agent trusted it.
- State — stale or wrong context carried into the step.
- Parsing — malformed model output mis-parsed downstream. Name which, with evidence from the trace.
- Report (terse): where it diverged (step N) · the cause · the minimal
change to fix it · whether it's deterministic or a sampling issue. If the fix
is a prompt/tool change, offer to run
eval-agentafter to confirm no regression.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

