CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

braintrust-tracing

Braintrust tracing for Claude Code - hook architecture, sub-agent correlation, debugging

Quality

63%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/braintrust-tracing/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

50%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is genuinely informative and much of it is executable (debugging commands, troubleshooting checklist, env var table), but it is structured as a knowledge dump rather than a skill: the sub-agent correlation story is told three times, the correlation workflow stops at pseudocode, and nothing is split into reference files. Consolidating the duplicated sections and adding validation around the destructive state-clearing step are the highest-impact fixes.

Suggestions

Merge the three overlapping sections ("Sub-Agent Tracing", "Session Learnings", "What We Learned About Sub-Agent Correlation") into one canonical sub-agent correlation section; roughly a third of the document is repetition.

Replace the '# Correlate in Python' comment block with the actual matching script or move it to a referenced scripts/ file, and add a verification step (e.g., confirm match count) before the destructive rm of session state files.

Split the architecture diagrams, state-file schema, and historical session learnings into a references/ file (e.g., ARCHITECTURE.md) and keep SKILL.md as a concise overview with clearly signaled one-level-deep pointers.

DimensionReasoningScore

Conciseness

The sub-agent correlation material is explained three separate times — in "Sub-Agent Tracing: What Works and What Doesn't" (PreToolUse injection fails, Task spans contain agentId, SubagentStop provides session_id), again in "Session Learnings (Dec 2025)", and again at length in "What We Learned About Sub-Agent Correlation" — each repeating the same facts nearly verbatim. This is noticeably verbose padding across multiple sections, fitting the 2 anchor; it is not a 1 because the individual sections assume Claude's competence and avoid explaining generic concepts.

2 / 5

Actionability

The debugging commands (tail -f the hook log, braintrust_analyze.py --sessions/--agent-stats, manual hook test with piped echo JSON) and the troubleshooting checklist are copy-paste executable. It falls short of 5 because the correlation workflow ends in commented pseudocode ('# Correlate in Python: ... Match by timing and type') with no actual script, and key commands reference paths outside this bundle.

4 / 5

Workflow Clarity

The troubleshooting checklist and correlation strategy present a recognizable numbered sequence, but there are no validation checkpoints or feedback loops — the 'State corruption' remedy is a destructive batch command (rm ~/.claude/state/braintrust_sessions/*.json) with no verification step before or after, which caps workflow clarity at 3 per the destructive/batch-operation rule.

3 / 5

Progressive Disclosure

No bundle files exist (references/, scripts/, assets/ are absent), so everything lives inline in a ~360-line SKILL.md, including full architecture diagrams, state schemas, and duplicated learnings that clearly belong in separate reference files. Section headers provide some structure, matching the 3 anchor of 'some structure but content that should be separate is inline'; it is not a 2 because the file is genuinely navigable via its clear headings and tables.

3 / 5

Total

12

/

20

Passed

Description

60%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is distinctive and on-topic but structurally incomplete: it reads as a keyword tag list rather than a capability statement. Adding concrete actions and an explicit 'Use when...' trigger clause would lift both specificity and completeness.

Suggestions

Add a 'Use when...' clause (e.g., 'Use when debugging Braintrust hooks, missing traces, or correlating sub-agent traces') to satisfy the trigger guidance that is currently absent and cap-completeness at 3.

Convert the topic list into verb-led capabilities, e.g., 'Set up Braintrust tracing hooks for Claude Code, debug missing spans, correlate sub-agent traces' to raise specificity from concepts to actions.

Include natural synonyms users might say — 'observability', 'telemetry', 'trace logs', 'spans' — to round out trigger term coverage.

DimensionReasoningScore

Specificity

The description "Braintrust tracing for Claude Code - hook architecture, sub-agent correlation, debugging" names the domain and a few topic areas, but contains no action verbs at all — it lists concepts rather than concrete capabilities like 'set up', 'query', or 'correlate traces'. It sits between the vague-generic anchor (2) and the domain-plus-1-2-actions anchor (3), closer to 2 because nothing describes what the skill actually does with those topics.

2 / 5

Completeness

The 'what' is reasonably clear (tracing Claude Code sessions in Braintrust with sub-agent correlation), but there is no 'Use when...' clause or any equivalent trigger guidance — the guideline explicitly caps completeness at 3 for this. It is not a 2 because the 'what' is concrete and specific, not vague.

3 / 5

Trigger Term Quality

"tracing", "Braintrust", "Claude Code", "hook architecture", "sub-agent correlation", and "debugging" are all natural terms a user working in this niche would say. It falls short of the 5 anchor because common synonyms and variations like "observability", "telemetry", "spans", or "logs" are missing, but it clearly exceeds the partial-keyword-coverage anchor at 3.

4 / 5

Distinctiveness Conflict Risk

"Braintrust tracing for Claude Code" is a tightly scoped niche with distinct triggers (Braintrust, tracing, sub-agent correlation, hook debugging) that would not plausibly fire for any other skill. Clear niche with minimal conflict risk.

5 / 5

Total

14

/

20

Passed

Validation

93%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

referenced_paths_exist

Referenced path issues: 5 missing

Warning

Total

15

/

16

Passed

Repository

parcadei/Continuous-Claude-v3

Path

.claude/skills/braintrust-tracing/SKILL.md

Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.