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
How do you install this skill?
- 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.
- Shell / CLI
- Local filesystem
bashkit (npm)
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.
tmp="$(mktemp -d)"
git clone --depth 1 https://github.com/jbreite/bashkit.git "$tmp"
mkdir -p ~/.claude/skills
cp -R "$tmp/skills/bashkit-debug" ~/.claude/skills/
rm -rf "$tmp"Generated from the source repository and skill path; it copies only this skill's folder. If the author's install steps above differ, follow those first. To scope it to one project, replace ~/.claude/skills with that project's .claude/skills.
How do you use this skill?
Once installed, send your agent any of these to trigger it:
- what went wrong
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.
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 does this skill compare with similar options?
Side by side with related skills; every score comes from the same FSRS standard.
| Skill | FS score | Stars | Last updated | License |
|---|---|---|---|---|
| BashKit Debug Trace Analyzer this page | 57 · Use with care | ★ 11 | 4mo ago | MIT |
| Stripe AI Developer Toolkit | Not yet reviewed | ★ 1.9k | 11d ago | MIT |
| Cloudflare Sandbox Builder | 46 · Use with care | ★ 3.1k | 11d ago | Apache-2.0 |
| unbox-ai — AI Agent Trace Analysis CLI | 54 · Use with care | ★ 10k | 11d ago | Apache-2.0 |
| Azure AI Projects for TypeScript ✓ Microsoft · Official | 49 · Use with care | ★ 2.7k | 3mo ago | MIT |
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.
How did FollowSkills review this skill?
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.
Open a dimension to read why it scored that way
Evidence confidence：Low — Mostly static review, author material or a limited demo; useful for discovery, not high-risk decisions.
See the full review method →