How to use the Reasoning Trace Optimizer agent skill

What is an agent skill and what does this one do?

An agent skill is a folder containing a SKILL.md file with instructions that an AI agent (such as Claude) loads when a request matches the skill's description. The skill tells the agent how to approach a specific kind of task.

This skill teaches the agent to analyze reasoning traces and look for failure patterns: context_degradation (losing track of information over long contexts), tool_confusion (misunderstanding tool capabilities or outputs), instruction_drift (gradually deviating from instructions), goal_abandonment, circular_reasoning (repeating actions without progress) and premature_conclusion (finishing before the task is done). It can then suggest a better system prompt.

Install the skill from the ZIP download

Download the ZIP for the skill from this page and unzip it. For a personal setup, place the skill folder in ~/.claude/skills/. To keep it only within one project, place it in that project's .claude/skills/ folder.

If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.

• Personal: ~/.claude/skills/reasoning-trace-optimizer
• Single project: .claude/skills/reasoning-trace-optimizer

How to trigger the skill with natural requests

You do not need a special command for most uses. The skill is meant to activate when you ask about agent reasoning, debugging, or failures. Phrases the source lists as triggers include requests to debug reasoning traces, a task that failed and needs explaining, mentions of context degradation, tool confusion or instruction drift, and requests to improve agent performance or reduce errors.

In Claude Code you can also call the slash command directly to analyze the current session. It extracts thinking blocks, identifies patterns, suggests prompt improvements and can optionally update the system prompt.

• Why did my agent keep calling the wrong tool after the third turn? Check for tool confusion.
• My research agent stopped working toward the original goal. Analyze its reasoning trace.
• Our agent fails on similar tasks again and again. What should we change in its prompt?

Run the analysis modes and example workflows

The SKILL.md describes four modes. Mode 1 captures a run of a task through MiniMax M2.1 and analyzes its reasoning, returning a score and a list of detected patterns. Mode 2 runs an optimization loop that iterates until the prompt reaches a score threshold, with a configurable maximum number of iterations. Mode 3, universal session analysis, analyzes the thinking blocks of an agent's session and the source says it works with Claude, GPT and others. Mode 4 converts optimization learnings into reusable skills.

The command line tool rto offers matching commands: capture, analyze, optimize and generate-skill. The source's example for a full run is an optimization with five iterations that also generates a skill.

• Before example: system prompt 'You are a helpful assistant.', score 45/100, patterns tool_confusion and goal_abandonment.
• After example: a prompt that adds explicit guidelines such as verifying search results and keeping track of the original goal, with a score of 85/100 and no patterns detected.

What the skill needs before it runs

The main modes depend on things that are not in the listed files. They need Python with the reasoning_trace_optimizer package, which is referenced but not included in the file list, plus python-dotenv. You also need either a MiniMax API key or an ANTHROPIC_API_KEY set in a .env file that points to api.minimax.io. The rto command line tool is optional and only needed for CLI use.

Because the modes send captured runs to the MiniMax endpoint, you need to be comfortable with that data leaving your machine. The skill runs scripts and uses the network.

• Python with the reasoning_trace_optimizer package (not in the listed files)
• python-dotenv
• MiniMax API key, or ANTHROPIC_API_KEY in a .env file pointing to api.minimax.io
• Optional: rto command-line tool

Safety notes and tips for good results

Captured runs, including task data and session thinking, are sent to a third-party API in the main modes. The optimizer can change prompts, so review its output before using it in production. The source says generated skills should be reviewed before sharing, and that each optimization iteration uses significant tokens.

For better results, keep the full response history including thinking blocks, since the source says M2.1 needs this for optimal performance. Define tools with clear, unambiguous descriptions. The source notes that 5-10% improvement per iteration is typical for convergence thresholds.

• Keep full response history, including thinking blocks.
• Write tool descriptions that are clear and unambiguous.
• Review optimized prompts and generated skills before sharing or deploying.
• Watch token usage across iterations.