debug-agent

Locate dev-only agent diagnostics under BRAIN_HOME and correlate them with logs via agentTurnId.

Updated Aug 23, 2026
One-click install
npx skills add https://github.com/cirne/brain-app --skill debug-agent-cirne
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: debug-agent
Source: https://github.com/cirne/brain-app/tree/main/.cursor/skills/debug-agent
Command: npx skills add https://github.com/cirne/brain-app --skill debug-agent-cirne

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Locates brain-app dev-only per-turn agent diagnostics under BRAIN_HOME (JSONL lines per agent turn + small JSON for suggest-repair) and correlates them with structured logs via agentTurnId and session IDs to surface actionable debugging artifacts.

Core Features & Use Cases

  • Locate dev-only agent diagnostics under BRAIN_HOME for a given run.
  • Correlate diagnostics with server logs using agentTurnId and sessionId to diagnose issues across turns.
  • Read schema versions and file layouts to interpret agent diagnostics during development (not production).

Quick Start

Run the debug-agent workflow to locate and correlate dev-only agent diagnostics with structured logs by agentTurnId and sessionId.

Frequently Asked Questions about debug-agent

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

FAQPage Schema
How do I locate dev-only agent diagnostics for a specific brain-app run?

You can locate dev-only agent diagnostics by scanning the BRAIN_HOME directory for JSONL files containing per-turn agent data and small JSON files for suggest-repair. This Skill surfaces those autogenerated diagnostic artifacts reliably during local development.

Can I correlate structured server logs with agent diagnostics using session IDs?

Yes, you can correlate structured logs with agent diagnostics by matching agentTurnId and sessionId across both datasets. This correlation surfaces actionable debugging artifacts across individual agent turns during development.

What is the on-disk layout for brain-app per-turn agent diagnostics?

The on-disk layout consists of JSONL lines recording each agent turn alongside small JSON files for suggest-repair, organized under BRAIN_HOME. The Skill relies on AGENT_DIAGNOSTICS_SCHEMA_VERSION and known file naming schemes to interpret this layout.

Does this diagnostics approach work for production environments or is it dev-only?

This diagnostics approach is strictly dev-only. It is designed to locate autogenerated diagnostic files and diagnose specific agent or LLM tool turns from local logs during development, not in production environments.

How do I diagnose a specific agent or LLM tool turn from local logs?

Diagnose a specific agent turn by running the debug-agent workflow to locate and correlate dev-only diagnostics with structured logs using agentTurnId and sessionId. This surfaces actionable artifacts tied to that exact turn.

Why do I need AGENT_DIAGNOSTICS_SCHEMA_VERSION when debugging an agent request?

AGENT_DIAGNOSTICS_SCHEMA_VERSION is needed because it ensures the Skill correctly interprets the on-disk file layout and JSONL diagnostics structure. Relying on this version and known naming schemes surfaces relevant artifacts reliably.