skills.rest
matteing
matteingCOMMUNITY
Explore all skills by this author →
Website𝕏@matteingGitHub

debugging

Diagnose Opal agent runtime failures with structured debug_state JSON snapshots.

56|2|Updated Feb 8, 2026
Search Tags:#debugging#tooling#diagnostics#introspection#event-log#token-usage#opal
One-click install
npx skills add https://github.com/matteing/opal --skill debugging-matteing
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: debugging
Source: https://github.com/matteing/opal/tree/main/.claude/skills/debugging
Command: npx skills add https://github.com/matteing/opal --skill debugging-matteing

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Provides in-turn self-diagnosis for Opal agents so you can discover why a tool failed, an agent is looping, context is being lost, or features are not available. It surfaces session metadata, token usage, recent events, queued tasks, and tool availability to pinpoint root causes during a live session.

Core Features & Use Cases

  • Structured snapshots: Use the debug_state tool to produce basic snapshots, event-limited views, message-inclusive views, or full diagnostics combining events and messages.
  • Token pressure and context checks: Inspect token_usage.current_context_tokens versus context_window to detect compaction risk and lost context.
  • Tool and queue diagnostics: Verify tools.enabled vs tools.all, inspect pending_steers, remaining_tool_calls, and has_pending_tool_task to find stuck executions or missing tools.
  • Event timeline analysis: Read newest-first events for request_start/request_end, tool_execution_start/tool_execution_end, error, and agent_abort patterns to trace failures and retries.
  • Integration testing guidance: Reproduce and test session lifecycles using repository scripts for one-off RPC calls and full session runs when validating fixes.

Quick Start

Enable Opal's debug feature and request a debug_state snapshot including recent events and messages to inspect token usage, tool lists, and the event timeline.

Frequently Asked Questions about debugging

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I inspect agent state and diagnose runtime issues during a live session?▼

You can inspect agent state by using the debug_state tool to produce structured JSON snapshots of session metadata, token usage, recent events, and queued tasks during a live session. This provides in-turn self-diagnosis to pinpoint root causes of runtime failures.

What is the best way to check token usage and context window limits before compaction occurs?▼

Check token pressure by comparing token_usage.current_context_tokens against the context_window limit in a debug_state snapshot. This detects compaction risk and identifies when context is being lost due to approaching token limits.

How do I trace tool execution failures and agent loops using event logs?▼

Read the newest-first event timeline in the debug_state snapshot to trace tool_execution_start and tool_execution_end patterns. Analyzing the event log helps identify exactly where tool executions fail or why an agent is looping.

Do I need to enable a specific feature flag to access the in-memory event log?▼

Yes, you must enable Opal's debug feature flag to access the in-memory event log. Without this feature flag enabled, the debug_state tool cannot retrieve the session event timeline or produce diagnostic snapshots.

Can I diagnose stuck tool executions and missing tools during an Opal session?▼

Yes, you can diagnose stuck executions by inspecting pending_steers, remaining_tool_calls, and has_pending_tool_task. Comparing tools.enabled versus tools.all in the snapshot verifies tool availability and finds missing tools.

How do I reproduce and test session lifecycles when validating fixes for agent runtime failures?▼

Reproduce and test session lifecycles using repository scripts for one-off RPC calls and full session runs. This integration testing approach validates fixes by simulating the complete session state and tracing the event timeline.

Related Skills

Explore More Software Engineering Skills→
ano4lano4l

debug-menu

Provide an in-app debug menu for iOS DEBUG builds using SwiftUI.

Community
Advanced
mccode415mccode415

reflection

Analyze past AI sessions to identify root causes and generate actionable recommendations.

Community
Advanced
travisjneumantravisjneuman
88

event-planner

Create structured timelines, budgets, and checklists for event planning.

Community
Advanced
scooter-lacroixscooter-lacroix
8

no-task-output

Prevent TaskOutput tool use to avoid flooding the main context window.

Community
Basic