{"id":"c7b2f477-415e-4641-8cf6-ec08c69df88a","shortId":"GFf7Vf","kind":"skill","title":"jq","tagline":"Expert jq usage for JSON querying, filtering, transformation, and pipeline integration. Practical patterns for real shell workflows.","description":"# jq — JSON Querying and Transformation\n\n## Overview\n\n`jq` is the standard CLI tool for querying and reshaping JSON. This skill covers practical, expert-level usage: filtering deeply nested data, transforming structures, aggregating values, and composing `jq` into shell pipelines. Every example is copy-paste ready for real workflows.\n\n## When to Use This Skill\n\n- Use when parsing JSON output from APIs, CLI tools (AWS, GitHub, kubectl, docker), or log files\n- Use when transforming JSON structure (rename keys, flatten arrays, group records)\n- Use when the user needs `jq` inside a bash script or one-liner\n- Use when explaining what a complex `jq` expression does\n\n## How It Works\n\n`jq` takes a filter expression and applies it to JSON input. Filters compose with pipes (`|`), and `jq` handles arrays, objects, strings, numbers, booleans, and `null` natively.\n\n### Basic Selection\n\n```bash\n# Extract a field\necho '{\"name\":\"alice\",\"age\":30}' | jq '.name'\n# \"alice\"\n\n# Nested access\necho '{\"user\":{\"email\":\"a@b.com\"}}' | jq '.user.email'\n\n# Array index\necho '[10, 20, 30]' | jq '.[1]'\n# 20\n\n# Array slice\necho '[1,2,3,4,5]' | jq '.[2:4]'\n# [3, 4]\n\n# All array elements\necho '[{\"id\":1},{\"id\":2}]' | jq '.[]'\n```\n\n### Filtering with `select`\n\n```bash\n# Keep only matching elements\necho '[{\"role\":\"admin\"},{\"role\":\"user\"},{\"role\":\"admin\"}]' \\\n  | jq '[.[] | select(.role == \"admin\")]'\n\n# Numeric comparison\ncurl -s https://api.github.com/repos/owner/repo/issues \\\n  | jq '[.[] | select(.comments > 5)]'\n\n# Test a field exists and is non-null\njq '[.[] | select(.email != null)]'\n\n# Combine conditions\njq '[.[] | select(.active == true and .score >= 80)]'\n```\n\n### Mapping and Transformation\n\n```bash\n# Extract a field from every array element\necho '[{\"name\":\"alice\",\"age\":30},{\"name\":\"bob\",\"age\":25}]' \\\n  | jq '[.[] | .name]'\n# [\"alice\", \"bob\"]\n\n# Shorthand: map()\njq 'map(.name)'\n\n# Build a new object per element\njq '[.[] | {user: .name, years: .age}]'\n\n# Add a computed field\njq '[.[] | . + {senior: (.age > 28)}]'\n\n# Rename keys\njq '[.[] | {username: .name, email_address: .email}]'\n```\n\n### Aggregation and Reduce\n\n```bash\n# Sum all values\necho '[1, 2, 3, 4, 5]' | jq 'add'\n# 15\n\n# Sum a field across objects\njq '[.[].price] | add'\n\n# Count elements\njq 'length'\n\n# Max / min\njq 'max_by(.score)'\njq 'min_by(.created_at)'\n\n# reduce: custom accumulator\necho '[1,2,3,4,5]' | jq 'reduce .[] as $x (0; . + $x)'\n# 15\n\n# Group by field\njq 'group_by(.department)'\n\n# Count per group\njq 'group_by(.status) | map({status: .[0].status, count: length})'\n```\n\n### String Interpolation and Formatting\n\n```bash\n# String interpolation\njq -r '.[] | \"\\(.name) is \\(.age) years old\"'\n\n# Format as CSV (no header)\njq -r '.[] | [.name, .age, .email] | @csv'\n\n# Format as TSV\njq -r '.[] | [.name, .score] | @tsv'\n\n# URL-encode a value\njq -r '.query | @uri'\n\n# Base64 encode\njq -r '.data | @base64'\n```\n\n### Working with Keys and Paths\n\n```bash\n# List all top-level keys\njq 'keys'\n\n# Check if key exists\njq 'has(\"email\")'\n\n# Delete a key\njq 'del(.password)'\n\n# Delete nested keys from every element\njq '[.[] | del(.internal_id, .raw_payload)]'\n\n# Recursive descent: find all values for a key anywhere in tree\njq '.. | .id? // empty'\n\n# Get all leaf paths\njq '[paths(scalars)]'\n```\n\n### Conditionals and Error Handling\n\n```bash\n# if-then-else\njq 'if .score >= 90 then \"A\" elif .score >= 80 then \"B\" else \"C\" end'\n\n# Alternative operator: use fallback if null or false\njq '.nickname // .name'\n\n# try-catch: skip errors instead of halting\njq '[.[] | try .nested.value catch null]'\n\n# Suppress null output with // empty\njq '.[] | .optional_field // empty'\n```\n\n### Practical Shell Integration\n\n```bash\n# Read from file\njq '.users' data.json\n\n# Compact output (no whitespace) for further piping\njq -c '.[]' records.json | while IFS= read -r record; do\n  echo \"Processing: $record\"\ndone\n\n# Pass a shell variable into jq\nSTATUS=\"active\"\njq --arg s \"$STATUS\" '[.[] | select(.status == $s)]'\n\n# Pass a number\njq --argjson threshold 42 '[.[] | select(.value > $threshold)]'\n\n# Slurp multiple JSON lines into an array\njq -s '.' records.ndjson\n\n# Multiple files: slurp all into one array\njq -s 'add' file1.json file2.json\n\n# Null-safe pipeline from a command\nkubectl get pods -o json | jq '.items[] | {name: .metadata.name, status: .status.phase}'\n\n# GitHub CLI: extract PR numbers\ngh pr list --json number,title | jq -r '.[] | \"\\(.number)\\t\\(.title)\"'\n\n# AWS CLI: list running instance IDs\naws ec2 describe-instances \\\n  | jq -r '.Reservations[].Instances[] | select(.State.Name==\"running\") | .InstanceId'\n\n# Docker: show container names and images\ndocker inspect $(docker ps -q) | jq -r '.[] | \"\\(.Name)\\t\\(.Config.Image)\"'\n```\n\n### Advanced Patterns\n\n```bash\n# Transpose an object of arrays to an array of objects\n# Input: {\"names\":[\"a\",\"b\"],\"scores\":[10,20]}\njq '[.names, .scores] | transpose | map({name: .[0], score: .[1]})'\n\n# Flatten one level\njq 'flatten(1)'\n\n# Unique by field\njq 'unique_by(.email)'\n\n# Sort, deduplicate and re-index\njq '[.[] | .name] | unique | sort'\n\n# Walk: apply transformation to every node recursively\njq 'walk(if type == \"string\" then ascii_downcase else . end)'\n\n# env: read environment variables inside jq\nexport API_KEY=secret\njq -n 'env.API_KEY'\n```\n\n## Best Practices\n\n- Always use `-r` (raw output) when passing `jq` results to shell variables or other commands to strip JSON string quotes\n- Use `--arg` / `--argjson` to inject shell variables safely — never interpolate shell variables directly into filter strings\n- Prefer `map(f)` over `[.[] | f]` for readability\n- Use `-c` (compact) for newline-delimited JSON pipelines; omit it for human-readable debugging\n- Test filters interactively with `jq -n` and literal input before embedding in scripts\n- Use `empty` to drop unwanted elements rather than filtering to `null`\n\n## Security & Safety Notes\n\n- `jq` is read-only by design — it cannot write files or execute commands\n- Avoid embedding untrusted JSON field values directly into shell commands; always quote or use `--arg`\n\n## Common Pitfalls\n\n- **Problem:** `jq` outputs `null` instead of the expected value\n  **Solution:** Check for typos in key names; use `keys` to inspect actual field names. Remember JSON is case-sensitive.\n\n- **Problem:** Numbers are quoted as strings in the output\n  **Solution:** Use `--argjson` instead of `--arg` when injecting numeric values.\n\n- **Problem:** Filter works in the terminal but fails in a script\n  **Solution:** Ensure the filter string uses single quotes in the shell to prevent variable expansion. Example: `jq '.field'` not `jq \".field\"`.\n\n- **Problem:** `add` returns `null` on an empty array\n  **Solution:** Use `add // 0` or `add // \"\"` to provide a fallback default.\n\n- **Problem:** Streaming large files is slow\n  **Solution:** Use `jq --stream` or switch to `jstream`/`gron` for very large files.\n\n## Related Skills\n\n- `@bash-pro` — Wrapping jq calls in robust shell scripts\n- `@bash-linux` — General shell pipeline patterns\n- `@github-automation` — Using jq with GitHub CLI JSON output\n\n## Limitations\n- Use this skill only when the task clearly matches the scope described above.\n- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.\n- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.","tags":["antigravity","awesome","skills","sickn33","agent-skills","agentic-skills","ai-agent-skills","ai-agents","ai-coding","ai-workflows","antigravity-skills","claude-code"],"capabilities":["skill","source-sickn33","skill-jq","topic-agent-skills","topic-agentic-skills","topic-ai-agent-skills","topic-ai-agents","topic-ai-coding","topic-ai-workflows","topic-antigravity","topic-antigravity-skills","topic-claude-code","topic-claude-code-skills","topic-codex-cli","topic-codex-skills"],"categories":["antigravity-awesome-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/sickn33/antigravity-awesome-skills/jq","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add sickn33/antigravity-awesome-skills","source_repo":"https://github.com/sickn33/antigravity-awesome-skills","install_from":"skills.sh"}},"qualityScore":"0.700","qualityRationale":"deterministic score 0.70 from registry signals: · indexed on github topic:agent-skills · 34726 github stars · SKILL.md body (7,372 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-23T12:51:07.317Z","embedding":null,"createdAt":"2026-04-18T21:39:27.339Z","updatedAt":"2026-04-23T12:51:07.317Z","lastSeenAt":"2026-04-23T12:51:07.317Z","tsv":"'/repos/owner/repo/issues':230 '0':365,384,724,991 '1':181,186,201,321,356,726,732 '10':177,716 '15':328,367 '2':187,192,203,322,357 '20':178,182,717 '25':276 '28':304 '3':188,194,323,358 '30':162,179,272 '4':189,193,195,324,359 '42':603 '5':190,234,325,360 '80':256,513 '90':508 'a@b.com':171 'access':167 'accumul':354 'across':332 'activ':252,589 'actual':920 'add':297,327,336,626,981,990,993 'address':311 'admin':215,219,223 'advanc':698 'age':161,271,275,296,303,399,410 'aggreg':50,313 'alic':160,165,270,279 'altern':519 'alway':783,893 'anywher':483 'api':79,774 'api.github.com':229 'api.github.com/repos/owner/repo/issues':228 'appli':132,751 'arg':591,804,897,943 'argjson':601,805,940 'array':97,144,174,183,197,266,613,623,705,708,987 'ascii':763 'ask':1080 'autom':1039 'avoid':883 'aw':82,663,669 'b':515,714 'base64':430,435 'bash':108,154,208,260,316,392,441,500,555,700,1021,1031 'bash-linux':1030 'bash-pro':1020 'basic':152 'best':781 'bob':274,280 'boolean':148 'boundari':1088 'build':286 'c':517,570,827 'call':1025 'cannot':877 'case':927 'case-sensit':926 'catch':532,541 'check':450,910 'clarif':1082 'clear':1055 'cli':29,80,648,664,1044 'combin':248 'command':635,797,882,892 'comment':233 'common':898 'compact':562,828 'comparison':225 'complex':119 'compos':53,138 'comput':299 'condit':249,496 'config.image':697 'contain':684 'copi':62 'copy-past':61 'count':337,375,386 'cover':38 'creat':350 'criteria':1091 'csv':404,412 'curl':226 'custom':353 'data':47,434 'data.json':561 'debug':841 'dedupl':741 'deepli':45 'default':998 'del':461,470 'delet':457,463 'delimit':832 'depart':374 'descent':476 'describ':672,1059 'describe-inst':671 'design':875 'direct':815,889 'docker':85,682,688,690 'done':581 'downcas':764 'drop':858 'ec2':670 'echo':158,168,176,185,199,213,268,320,355,578 'element':198,212,267,291,338,468,860 'elif':511 'els':504,516,765 'email':170,246,310,312,411,456,739 'embed':852,884 'empti':488,547,551,856,986 'encod':423,431 'end':518,766 'ensur':960 'env':767 'env.api':779 'environ':769,1071 'environment-specif':1070 'error':498,534 'everi':58,265,467,754 'exampl':59,974 'execut':881 'exist':238,453 'expans':973 'expect':907 'expert':2,41,1076 'expert-level':40 'explain':116 'export':773 'express':121,130 'extract':155,261,649 'f':821,823 'fail':955 'fallback':522,997 'fals':526 'field':157,237,263,300,331,370,550,735,887,921,976,979 'file':88,558,618,879,1002,1017 'file1.json':627 'file2.json':628 'filter':8,44,129,137,205,817,843,863,949,962 'find':477 'flatten':96,727,731 'format':391,402,413 'general':1033 'get':489,637 'gh':652 'github':83,647,1038,1043 'github-autom':1037 'gron':1013 'group':98,368,372,377,379 'halt':537 'handl':143,499 'header':406 'human':839 'human-read':838 'id':200,202,472,487,668 'if':573 'if-then-els':501 'imag':687 'index':175,745 'inject':807,945 'input':136,711,850,1085 'insid':106,771 'inspect':689,919 'instanc':667,673,677 'instanceid':681 'instead':535,904,941 'integr':12,554 'interact':844 'intern':471 'interpol':389,394,812 'item':642 'jq':1,3,19,25,54,105,120,126,142,163,172,180,191,204,220,231,244,250,277,283,292,301,307,326,334,339,343,347,361,371,378,395,407,416,426,432,448,454,460,469,486,493,505,527,538,548,559,569,587,590,600,614,624,641,658,674,693,718,730,736,746,757,772,777,790,846,869,901,975,978,1007,1024,1041 'json':6,20,35,76,92,135,609,640,655,800,833,886,924,1045 'jstream':1012 'keep':209 'key':95,306,438,447,449,452,459,465,482,775,780,914,917 'kubectl':84,636 'larg':1001,1016 'leaf':491 'length':340,387 'level':42,446,729 'limit':1047 'line':610 'liner':113 'linux':1032 'list':442,654,665 'liter':849 'log':87 'map':257,282,284,382,722,820 'match':211,1056 'max':341,344 'metadata.name':644 'min':342,348 'miss':1093 'multipl':608,617 'n':778,847 'name':159,164,269,273,278,285,294,309,397,409,418,529,643,685,695,712,719,723,747,915,922 'nativ':151 'need':104 'nest':46,166,464 'nested.value':540 'never':811 'new':288 'newlin':831 'newline-delimit':830 'nicknam':528 'node':755 'non':242 'non-nul':241 'note':868 'null':150,243,247,524,542,544,630,865,903,983 'null-saf':629 'number':147,599,651,656,660,930 'numer':224,946 'o':639 'object':145,289,333,703,710 'old':401 'omit':835 'one':112,622,728 'one-lin':111 'oper':520 'option':549 'output':77,545,563,787,902,937,1046,1065 'overview':24 'pars':75 'pass':582,597,789 'password':462 'past':63 'path':440,492,494 'pattern':14,699,1036 'payload':474 'per':290,376 'permiss':1086 'pipe':140,568 'pipelin':11,57,632,834,1035 'pitfal':899 'pod':638 'pr':650,653 'practic':13,39,552,782 'prefer':819 'prevent':971 'price':335 'pro':1022 'problem':900,929,948,980,999 'process':579 'provid':995 'ps':691 'q':692 'queri':7,21,32,428 'quot':802,894,932,966 'r':396,408,417,427,433,575,659,675,694,785 'rather':861 'raw':473,786 're':744 're-index':743 'read':556,574,768,872 'read-on':871 'readabl':825,840 'readi':64 'real':16,66 'record':99,576,580 'records.json':571 'records.ndjson':616 'recurs':475,756 'reduc':315,352,362 'relat':1018 'rememb':923 'renam':94,305 'requir':1084 'reserv':676 'reshap':34 'result':791 'return':982 'review':1077 'robust':1027 'role':214,216,218,222 'run':666,680 'safe':631,810 'safeti':867,1087 'scalar':495 'scope':1058 'score':255,346,419,507,512,715,720,725 'script':109,854,958,1029 'secret':776 'secur':866 'select':153,207,221,232,245,251,594,604,678 'senior':302 'sensit':928 'shell':17,56,553,584,793,808,813,891,969,1028,1034 'shorthand':281 'show':683 'singl':965 'skill':37,72,1019,1050 'skill-jq' 'skip':533 'slice':184 'slow':1004 'slurp':607,619 'solut':909,938,959,988,1005 'sort':740,749 'source-sickn33' 'specif':1072 'standard':28 'state.name':679 'status':381,383,385,588,593,595,645 'status.phase':646 'stop':1078 'stream':1000,1008 'string':146,388,393,761,801,818,934,963 'strip':799 'structur':49,93 'substitut':1068 'success':1090 'sum':317,329 'suppress':543 'switch':1010 'take':127 'task':1054 'termin':953 'test':235,842,1074 'threshold':602,606 'titl':657,662 'tool':30,81 'top':445 'top-level':444 'topic-agent-skills' 'topic-agentic-skills' 'topic-ai-agent-skills' 'topic-ai-agents' 'topic-ai-coding' 'topic-ai-workflows' 'topic-antigravity' 'topic-antigravity-skills' 'topic-claude-code' 'topic-claude-code-skills' 'topic-codex-cli' 'topic-codex-skills' 'transform':9,23,48,91,259,752 'transpos':701,721 'treat':1063 'tree':485 'tri':531,539 'true':253 'try-catch':530 'tsv':415,420 'type':760 'typo':912 'uniqu':733,737,748 'untrust':885 'unwant':859 'uri':429 'url':422 'url-encod':421 'usag':4,43 'use':70,73,89,100,114,521,784,803,826,855,896,916,939,964,989,1006,1040,1048 'user':103,169,217,293,560 'user.email':173 'usernam':308 'valid':1073 'valu':51,319,425,479,605,888,908,947 'variabl':585,770,794,809,814,972 'walk':750,758 'whitespac':565 'work':125,436,950 'workflow':18,67 'wrap':1023 'write':878 'x':364,366 'year':295,400","prices":[{"id":"55637632-393d-49d4-8219-6004254db1b4","listingId":"c7b2f477-415e-4641-8cf6-ec08c69df88a","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"sickn33","category":"antigravity-awesome-skills","install_from":"skills.sh"},"createdAt":"2026-04-18T21:39:27.339Z"}],"sources":[{"listingId":"c7b2f477-415e-4641-8cf6-ec08c69df88a","source":"github","sourceId":"sickn33/antigravity-awesome-skills/jq","sourceUrl":"https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/jq","isPrimary":false,"firstSeenAt":"2026-04-18T21:39:27.339Z","lastSeenAt":"2026-04-23T12:51:07.317Z"}],"details":{"listingId":"c7b2f477-415e-4641-8cf6-ec08c69df88a","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"sickn33","slug":"jq","github":{"repo":"sickn33/antigravity-awesome-skills","stars":34726,"topics":["agent-skills","agentic-skills","ai-agent-skills","ai-agents","ai-coding","ai-workflows","antigravity","antigravity-skills","claude-code","claude-code-skills","codex-cli","codex-skills","cursor","cursor-skills","developer-tools","gemini-cli","gemini-skills","kiro","mcp","skill-library"],"license":"mit","html_url":"https://github.com/sickn33/antigravity-awesome-skills","pushed_at":"2026-04-23T06:41:03Z","description":"Installable GitHub library of 1,400+ agentic skills for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and more. Includes installer CLI, bundles, workflows, and official/community skill collections.","skill_md_sha":"e3c5519e09080a9b73e5bbe4e397fb81ed7e44ed","skill_md_path":"skills/jq/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/jq"},"layout":"multi","source":"github","category":"antigravity-awesome-skills","frontmatter":{"name":"jq","description":"Expert jq usage for JSON querying, filtering, transformation, and pipeline integration. Practical patterns for real shell workflows."},"skills_sh_url":"https://skills.sh/sickn33/antigravity-awesome-skills/jq"},"updatedAt":"2026-04-23T12:51:07.317Z"}}