query-patterns

Opinionated guidance for constructing and interpreting Honeycomb queries on trace and event datasets — operation selection (percentiles not AVG, HEATMAP for distributions), relational field patterns (root., parent., any., none.), calculated fields, query math, and result interpretation (P99/P50 ratios, heatmap bands, TOTAL/OTHER rows, raw JSON via query_result_json). Use this skill when the user wants to query spans, traces, or log/event data in Honeycomb — requests like "show me latency", "error rate", "find slow requests", "find outliers", "interpret results", "relational fields", "calculated fields", or "download raw results". This skill covers all dataset types except metrics datasets (dataset_type=metrics) — for those, use metrics-queries instead.

Quality

93%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

86%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.

A well-structured, opinionated, and highly actionable skill body that delegates detail to real reference files and includes pre-query validation and result-interpretation feedback loops. The only slack is a small amount of definitional over-explanation in the Calculated Fields section.

Suggestions

Trim or remove the definitional sentence "Calculated fields are per-event expressions evaluated at query time. They transform, classify, and combine existing fields without re-instrumenting code." — the patterns and guardrails already convey the purpose.

Consider consolidating the query workflow into one explicit numbered sequence (find_queries → find_columns → broad COUNT/GROUP BY → add filters → interpret with heuristics) so the end-to-end flow with checkpoints is unambiguous.

Dimension	Reasoning	Score
Conciseness	Largely lean and assumes competence, but the two-sentence opener "Calculated fields are per-event expressions evaluated at query time. They transform, classify, and combine existing fields without re-instrumenting code." explains a concept Claude already knows and could be trimmed; fits the efficient-with-minor-over-explanation anchor rather than the fully-lean one.	4 / 5
Actionability	Fully executable, copy-paste-ready patterns throughout — `COUNT, P99(duration_ms), HEATMAP(duration_ms)`, `MUL(IF($error, 1, 0), 100)`, `IF(GTE($http.status_code, 500), "5xx", ...)`, `BUCKET($duration_ms, 500, 0, 3000)`, plus concrete tool calls like `find_columns`, `find_queries`, `query_result_json`, and `run_bubbleup`.	5 / 5
Workflow Clarity	A "Before Every Query" pre-flight checklist with explicit validation (`Validate columns with find_columns before querying`) plus result-driven feedback loops (P99/P50 > 10x → run HEATMAP; large OTHER → increase limit), but there is no single numbered end-to-end sequence with validate-fix-retry, so it sits below the 5 anchor.	4 / 5
Progressive Disclosure	Concise overview that keeps syntax/bulk detail out of SKILL.md and points to five well-signaled one-level-deep reference files (all verified present in references/) plus cross-references to sibling skills; navigation is easy and references are not nested.	5 / 5
	Total	18 / 20 Passed

Description

100%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.

A strong, well-scoped description that crisply states capabilities, gives natural trigger phrases, and draws a clear boundary against the metrics-queries skill. Third-person voice is maintained throughout with no fluff or over-claims.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions across the full query surface — "operation selection", "relational field patterns (root., parent., any., none.)", "calculated fields", "query math", and "result interpretation (P99/P50 ratios, heatmap bands, TOTAL/OTHER rows)" — matching the comprehensive-coverage anchor.	5 / 5
Completeness	Explicitly answers both what ("constructing and interpreting Honeycomb queries") and when ("Use this skill when the user wants to query spans, traces, or log/event data in Honeycomb") with concrete trigger phrases and an explicit dataset-type boundary.	5 / 5
Trigger Term Quality	Comprehensive natural trigger phrases a user would actually say — "show me latency", "error rate", "find slow requests", "find outliers", "interpret results", "download raw results" — plus domain terms like spans, traces, and log/event data; no file extensions apply to this SaaS skill.	5 / 5
Distinctiveness Conflict Risk	Clear niche — Honeycomb trace/event query patterns — with an explicit exclusion ("except metrics datasets (dataset_type=metrics) — for those, use metrics-queries instead") that minimizes conflict with the sibling metrics skill.	5 / 5
	Total	20 / 20 Passed

Validation

100%

Warnings & errors only

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

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: honeycombio/agent-skill
Path: honeycomb/skills/query-patterns/SKILL.md
Commit: 41214b7

Reviewed: 5 days ago

Table of Contents

Discovery Implementation Validation

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.