playbooks

home / skills / yeachan-heo / oh-my-claudecode / trace

trace skill

/skills/trace

This skill displays the agent flow trace timeline and summary, helping you diagnose interactions among hooks, keywords, skills, agents, and tools.

npx playbooks add skill yeachan-heo/oh-my-claudecode --skill trace

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
965 B
---
name: trace
description: Show agent flow trace timeline and summary
---

# Agent Flow Trace

[TRACE MODE ACTIVATED]

## Objective

Display the flow trace showing how hooks, keywords, skills, agents, and tools interacted during this session.

## Instructions

1. **Use `trace_timeline` MCP tool** to show the chronological event timeline
   - Call with no arguments to show the latest session
   - Use `filter` parameter to focus on specific event types (hooks, skills, agents, keywords, tools, modes)
   - Use `last` parameter to limit output

2. **Use `trace_summary` MCP tool** to show aggregate statistics
   - Hook fire counts
   - Keywords detected
   - Skills activated
   - Mode transitions
   - Tool performance and bottlenecks

## Output Format

Present the timeline first, then the summary. Highlight:
- **Mode transitions** (how execution modes changed)
- **Bottlenecks** (slow tools or agents)
- **Flow patterns** (keyword -> skill -> agent chains)

Overview

This skill displays an agent flow trace timeline and a concise summary of execution during a session. It surfaces how hooks, keywords, skills, agents, and tools interacted, revealing mode transitions, bottlenecks, and common flow patterns. The output is organized: timeline first, then aggregate statistics for quick diagnosis.

How this skill works

The skill calls two trace MCP tools: trace_timeline to fetch chronological events and trace_summary to compute aggregate metrics. trace_timeline can be filtered by event type or limited to the last N events. trace_summary reports hook counts, detected keywords, activated skills, mode transitions, and tool performance.

When to use it

  • Diagnosing why a multi-agent session ran slower than expected
  • Understanding which agents and tools were engaged for a given objective
  • Auditing how keywords and hooks triggered downstream skills
  • Spotting mode transitions that caused unexpected behavior
  • Summarizing session activity for post-mortem or reporting

Best practices

  • Run the timeline first to get chronological context, then review the summary for hotspots
  • Use filters (hooks, skills, agents, keywords, tools, modes) to isolate noisy subsystems
  • Limit the timeline with the last parameter when analyzing large sessions to focus on recent events
  • Pay special attention to slow tools and repeated retries as indicators of bottlenecks
  • Correlate mode transitions with timestamps to spot where execution logic diverged

Example use cases

  • Showing a developer which skill triggered an unexpected tool call during a CI run
  • Tracing a keyword -> skill -> agent chain that produced a wrong output
  • Identifying which agent introduced latency in a parallel execution scenario
  • Generating a short report of hook fire counts and active skills after a session
  • Filtering the last 50 events to debug a recent failure without noise from earlier activity

FAQ

How do I view only tool-related events?

Use trace_timeline with filter set to tools and optionally set last to limit the output.

What indicates a bottleneck in the summary?

High average or tail latencies for a tool or repeated agent retries typically indicate a bottleneck.