BashKit Debug Trace Analyzer
Analyzes JSONL debug traces from BashKit agent runs to pinpoint errors, slow operations, and abnormal execution patterns.
The skill is read-only (cat/grep/jq over JSONL trace files) with no writes, network calls, or destructive operations; the helper script uses set -euo pipefail, checks for jq and file existence. Trace files contain agent session data (commands, paths, outputs) and the skill gives no sensitive-data redaction guidance. Deducted for incomplete data-flow disclosure and undeclared jq/bc provenance.
Docs and script are self-consistent: event lifecycle, id correlation, parent fields, and per-tool summary fields align; the script gives clear failure feedback (missing jq, missing file). But static review cannot execute: summarize-trace.sh has no corresponding tests (repo tests cover cache/context modules), bc is required but not pre-checked, and edge cases (empty file, LAST_TS < FIRST_TS) are unhandled as far as visible. Static cap 10; per the 'happy path plausible but edges thin' anchor, kept at 10.
Trigger conditions are explicit ('debug trace', 'analyze trace', '.l' files) and the scenario (debugging a BashKit agent run) and prerequisite (BASHKIT_DEBUG traces) are clear; non-fit boundaries are only implicit (non-BashKit JSONL). jq is a hard dependency with a graceful in-script error; no mainland-China reachability issue since core function is local. Deducted for limited boundary/input-validation disclosure and no Chinese support.
SKILL.md is well-layered (format → playbook → script → enabling traces); the repo provides MIT LICENSE, versioned package (0.7.2), and CI (test/lint/typecheck + codecov). Deducted for no skill-level version/changelog, no FAQ, no known-limitations section, and maintenance responsibility only inferable from an unverified publisher.
The analysis playbook is structured (overview/errors/performance/patterns/recommendations) and the script pre-compresses large traces for token efficiency, offering clear marginal value over manual grepping. But static review cannot verify real output quality; latency thresholds are unexplained heuristics. Static cap 7; scored 6 for limited direct-usability evidence.
Format definitions, the script, and README's BASHKIT_DEBUG docs corroborate each other; the repo has real CI workflows and committed tests, but none cover this skill's key paths (script, trace parsing). No third-party execution evidence, no independent reproduction. Scored 4 for thin coverage of the skill's own claims.
- Trace files contain full tool inputs/outputs (commands, file contents, URLs); redact sensitive data before analysis — the skill offers no redaction guidance.
- summarize-trace.sh depends on jq and bc; bc is not pre-checked, and empty files or anomalous timestamps may corrupt duration calculations.
- This is a static review only; the script was not executed and the documented trace format was not validated against real BASHKIT_DEBUG output.
- Publisher is unverified by the FollowSkills registry; the skill itself carries no version or changelog and the update path is unclear.
- Latency thresholds in the docs (bash >10s etc.) are unexplained heuristics without supporting data.
What does this skill do, and when should you use it?
This is a debugging skill for BashKit, an agentic coding toolkit for the Vercel AI SDK. It reads JSONL trace files generated via the BASHKIT_DEBUG environment variable, correlates tool-call start/end/error events by ID, and reconstructs the full execution timeline. A built-in playbook guides identification of errors, operations exceeding latency thresholds, and agent loops or unproductive retries, culminating in a structured diagnostic report. Developers building agents with BashKit who struggle to answer "what exactly went wrong in this run" get a ready-made triage tool.
Reads .l trace files and parses the per-line DebugEvent structure; pairs start/end/error events by id and maps nested sub-agent calls via the parent field; extracts key metrics from tool-specific summary fields (e.g. bash exitCode, grep fileCount); flags slow operations against thresholds (bash >10s, task >60s, etc.); detects patterns like repeated calls, retries without fixes, and orphaned start events; can pre-compress large files with the bundled summarize-trace.sh, then produces a report structured as overview/errors/performance/patterns/recommendations.
- You built a BashKit agent and a run failed — you need to see which tool call errored and why
- An agent seems stuck and you want duration data to find a hanging bash command
- An agent repeats the same command and you suspect missing caching or a loop
- Investigating why a sub-agent consumed excessive tokens
- Reporting a failed agent run to your team with a structured diagnosis
What are this skill's strengths and limitations?
- Trace format fully documented in SKILL.md (DebugEvent interface, per-tool summary fields), making analysis rules concrete and reproducible
- Includes a latency-threshold table and anti-pattern checklist (loops, retries without fixes, orphaned events) rather than generic log-reading
- Ships summarize-trace.sh to pre-compress large traces, saving analysis tokens
- Clear trigger phrases for automatic model invocation
- Only understands traces produced by BashKit — useless for other frameworks' logs
- Trace output is truncated (strings ~4000 chars, arrays 20 items), so key details may be lost
- No independent testing or user feedback vouches for skill quality
- Requires correctly setting BASHKIT_DEBUG at runtime, or there is no data to analyze
How do you install this skill?
Place the skills/bashkit-debug/ folder in your project's skills directory (BashKit's discoverSkills scans .skills/ and ~/.bashkit/skills/; any local Agent Skills client can load the SKILL.md directly). Install bashkit first (bun add bashkit) so traces can be generated.
How do you use this skill?
1) Run your agent with tracing enabled: BASHKIT_DEBUG=file:./trace.l node my-agent.js; 2) Trigger the skill, e.g. "bashkit debug" or "what went wrong" pointing at trace.l; 3) For large files, run ./skills/bashkit-debug/summarize-trace.sh trace.l first for a compact timeline; 4) Review the report for errors, slow calls, and recommendations.
How does this skill compare with similar options?
BashKit itself parallels Claude Code's built-in toolset (Bash/Read/Edit/Grep/Task) ported to the Vercel AI SDK ecosystem; this skill effectively adds a debug-trace analysis layer for it, and compared to generic log-reading skills its edge is deep familiarity with BashKit's specific event format.