jq

Use when the user needs to query, filter, reshape, extract, create, or construct JSON data — including API responses, config files, log output, or any structured data — or when helping the user write or debug JSON transformations.

Quality

92%

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

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

An excellent, lean reference body: fully executable one-line examples, a compact and accurate flag table, and genuinely useful gojq-specific differences and error-handling tips with essentially no padding. The only structural consideration is that the quick-reference detail (flags, unsupported features) is fully inlined in a ~92-line body rather than optionally split into a bundle file.

Dimension	Reasoning	Score
Conciseness	Lean and efficient throughout: no explanation of what JSON is, a compact flags table, one-line executable examples, and a differences-from-standard-jq section that covers genuinely non-obvious gojq behavior (key ordering, precision limits, unsupported flags). Every token earns its place.	5 / 5
Actionability	Every code block is a copy-paste-executable shell command, and the examples cover the common cases: field extraction, array filtering, reshaping, --arg/--argjson variables, slurping, compact output, raw output, file arguments, and -n construction. The Tips section adds concrete error-handling idioms (try, // fallback) and format strings.	5 / 5
Workflow Clarity	This is a single-purpose reference skill with no multi-step workflow; per the simple-skill exception, workflow clarity scores 5 because the single action (use the built-in jq with these flags and patterns) is unambiguous, and error-handling guidance (try, //, -e exit-status) is provided.	5 / 5
Progressive Disclosure	Well-organized sections (Flags, Differences, Common Patterns, Tips) with no nested or buried references — good structure with content mostly appropriately placed. At ~92 lines it exceeds the under-50-line simple-skill threshold, and the flags table and unsupported-features detail could arguably live in a reference file, so it does not warrant a 5.	4 / 5
	Total	19 / 20 Passed

Description

83%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 description with an explicit and multi-scenario "Use when" trigger clause and a solid list of concrete transformation verbs. Its main weaknesses are the absence of the tool name (jq) and missing common synonyms like "parse" or "pretty-print", which slightly limit trigger coverage and distinctiveness.

Suggestions

Mention the tool or command surface (e.g., "using jq syntax/filters") to sharpen distinctiveness from generic JSON-manipulation skills.

Add common natural synonyms users would say, such as "parse JSON" or "pretty-print JSON", to broaden trigger coverage.

Include a file-extension trigger (e.g., ".json files") alongside the existing content-type triggers.

Dimension	Reasoning	Score
Specificity	Lists several specific actions ("query, filter, reshape, extract, create, or construct") with concrete objects ("API responses, config files, log output"), matching the several-specific-actions anchor. It falls short of 5 because actions stay at generic verb level without naming the mechanism or tool capabilities.	4 / 5
Completeness	Explicitly answers both: the "what" ("query, filter, reshape, extract, create, or construct JSON data") and the "when" via a concrete "Use when the user needs to..." clause covering multiple trigger scenarios including debugging. Clearly a 5, not 4, since the when-clause is fully explicit with concrete trigger phrases.	5 / 5
Trigger Term Quality	Good natural-phrase coverage: "query", "filter", "extract", "API responses", "config files", "debug JSON transformations" are phrases users would actually say. Missing common synonyms such as "parse", "pretty-print", or the tool name "jq" itself, so not a 5.	4 / 5
Distinctiveness Conflict Risk	The JSON-data-transformation niche is mostly distinct from other skills. However, it never names the tool (jq) or its command surface, leaving minor overlap risk with generic JSON-manipulation or scripting skills, so not a 5.	4 / 5
	Total	17 / 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: charmbracelet/crush
Path: internal/skills/builtin/jq/SKILL.md
Commit: 8da3490

Reviewed: 4 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.