reasoning-trace-optimizer
Debug and optimize AI agents by analyzing reasoning traces. Activates on 'debug agent', 'optimize prompt', 'analyze reasoning', 'why did the agent fail', 'improve agent performance', or when diagnosing agent failures and context degradation.
Install with Tessl CLI
npx tessl i github:muratcankoylan/Agent-Skills-for-Context-Engineering --skill reasoning-trace-optimizerOverall
score
82%
Does it follow best practices?
If you maintain this skill, you can automatically optimize it using the tessl CLI to improve its score:
npx tessl skill review --optimize ./path/to/skillValidation for skill structure
Discovery
89%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a strong skill description with excellent trigger term coverage and clear completeness. The explicit 'Activates on' clause with multiple natural phrases makes it easy for Claude to select appropriately. The main weakness is that the capability description could be more specific about what concrete debugging/optimization actions are performed.
Suggestions
Expand the capability portion with more specific actions, e.g., 'identify reasoning failures, detect context window issues, suggest prompt improvements, trace decision paths'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (AI agents) and some actions ('debug', 'optimize', 'analyzing reasoning traces'), but lacks comprehensive concrete actions like specific debugging techniques or optimization methods. | 2 / 3 |
Completeness | Clearly answers both what ('Debug and optimize AI agents by analyzing reasoning traces') and when ('Activates on...' with explicit trigger phrases and scenarios like 'diagnosing agent failures'). | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural trigger terms users would say: 'debug agent', 'optimize prompt', 'analyze reasoning', 'why did the agent fail', 'improve agent performance', plus conceptual triggers like 'agent failures' and 'context degradation'. | 3 / 3 |
Distinctiveness Conflict Risk | Clear niche focused specifically on AI agent debugging and reasoning trace analysis. The specific triggers like 'why did the agent fail' and 'context degradation' are distinct and unlikely to conflict with general coding or debugging skills. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
72%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill provides strong actionable guidance with executable code examples across multiple usage modes (Python API, CLI, Claude Code integration). The structure and progressive disclosure are excellent. However, it could be more concise by removing explanatory content about interleaved thinking concepts and adding explicit validation checkpoints in the optimization workflow.
Suggestions
Remove or significantly condense the 'Core Concepts' section - Claude understands these concepts and the explanations consume tokens without adding actionable value
Add explicit validation steps to the optimization loop workflow, such as 'If score doesn't improve after 2 iterations, check for X' or 'Validate generated prompts by running a test task before accepting'
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill includes some unnecessary explanations (e.g., explaining why interleaved thinking matters, the 'Core Concepts' section explaining things Claude would understand). The pattern table and examples are useful but the overall content could be tightened by ~30%. | 2 / 3 |
Actionability | Provides fully executable Python code examples, CLI commands, and JSON configuration snippets that are copy-paste ready. Each usage mode has concrete, runnable examples with clear imports and function calls. | 3 / 3 |
Workflow Clarity | The optimization loop diagram shows the workflow, but validation checkpoints are implicit rather than explicit. The 'Guidelines' section mentions reviewing generated skills but doesn't provide a clear validation sequence or error recovery steps for when optimization fails. | 2 / 3 |
Progressive Disclosure | Well-structured with clear sections (When to Activate, Core Concepts, Usage Modes, CLI Commands, etc.). References to external docs are one level deep and clearly signaled. Content is appropriately split between overview and detailed examples. | 3 / 3 |
Total | 10 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 13 / 16 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
description_trigger_hint | Description may be missing an explicit 'when to use' trigger hint (e.g., 'Use when...') | Warning |
metadata_version | 'metadata' field is not a dictionary | Warning |
license_field | 'license' field is missing | Warning |
Total | 13 / 16 Passed | |
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.