AgentSkillsCN

jq-yq

利用 jq 和 yq 命令行工具,对 JSON 与 YAML 数据进行操作与处理。当用户提出“解析 JSON”“转换 YAML”“从 JSON 中提取数据”“筛选 JSON 数组”“将 YAML 转换为 JSON”“查询 JSON”或希望通过命令行操作结构化数据时,可使用此技能。

SKILL.md
--- frontmatter
name: jq-yq
description: JSON and YAML manipulation with jq and yq command-line tools. Use when user asks to "parse JSON", "transform YAML", "extract from JSON", "filter JSON array", "convert YAML to JSON", "query JSON", or manipulate structured data from command line.

jq & yq

Command-line JSON and YAML processing.

jq Basics

Extract Values

bash
# Get field
echo '{"name":"John","age":30}' | jq '.name'
# "John"

# Nested field
echo '{"user":{"name":"John"}}' | jq '.user.name'

# Array element
echo '[1,2,3]' | jq '.[0]'
# 1

# Multiple fields
echo '{"a":1,"b":2,"c":3}' | jq '{a,b}'
# {"a":1,"b":2}

Array Operations

bash
# All elements
echo '[1,2,3]' | jq '.[]'

# Filter array
echo '[1,2,3,4,5]' | jq '[.[] | select(. > 2)]'
# [3,4,5]

# Map
echo '[1,2,3]' | jq '[.[] * 2]'
# [2,4,6]

# Length
echo '[1,2,3]' | jq 'length'
# 3

# First/last
echo '[1,2,3]' | jq 'first'
echo '[1,2,3]' | jq 'last'

Object Arrays

bash
# Extract field from each
echo '[{"name":"a"},{"name":"b"}]' | jq '.[].name'

# Filter objects
echo '[{"age":20},{"age":30}]' | jq '[.[] | select(.age > 25)]'

# Sort
echo '[{"a":2},{"a":1}]' | jq 'sort_by(.a)'

# Group
echo '[{"type":"a"},{"type":"b"},{"type":"a"}]' | jq 'group_by(.type)'

Transform

bash
# Build new object
echo '{"first":"John","last":"Doe"}' | jq '{fullName: "\(.first) \(.last)"}'

# Add field
echo '{"a":1}' | jq '. + {b:2}'

# Delete field
echo '{"a":1,"b":2}' | jq 'del(.b)'

# Rename key
echo '{"old":1}' | jq '{new: .old}'

Conditionals

bash
# If-then-else
echo '{"age":20}' | jq 'if .age >= 18 then "adult" else "minor" end'

# Null handling
echo '{"a":null}' | jq '.a // "default"'

Raw Output

bash
# No quotes
echo '{"name":"John"}' | jq -r '.name'
# John

# Compact output
echo '{"a":1}' | jq -c '.'
# {"a":1}

yq Basics

YAML Operations

bash
# Read value
yq '.name' file.yaml

# Update value
yq -i '.version = "2.0"' file.yaml

# Add field
yq -i '.new_field = "value"' file.yaml

# Delete field
yq -i 'del(.unwanted)' file.yaml

Convert Formats

bash
# YAML to JSON
yq -o=json file.yaml

# JSON to YAML
yq -P file.json

# YAML to XML
yq -o=xml file.yaml

Multiple Documents

bash
# Select document
yq 'select(documentIndex == 0)' multi.yaml

# Evaluate all docs
yq ea '. as $item ireduce ([]; . + [$item])' multi.yaml

Common Patterns

API Response Processing

bash
# Get specific fields from API
curl -s api.example.com/users | jq '.data[] | {id, name, email}'

# Count results
curl -s api.example.com/items | jq '.results | length'

# Filter and format
curl -s api.example.com/posts | jq -r '.[] | "\(.id): \(.title)"'

Config File Manipulation

bash
# Update version in package.json
jq '.version = "1.2.3"' package.json > tmp && mv tmp package.json

# Add script
jq '.scripts.test = "jest"' package.json | sponge package.json

# Merge configs
jq -s '.[0] * .[1]' base.json override.json

Kubernetes/Helm

bash
# Get pod names
kubectl get pods -o json | jq -r '.items[].metadata.name'

# Filter by status
kubectl get pods -o json | jq '.items[] | select(.status.phase=="Running")'

# Update YAML manifest
yq -i '.spec.replicas = 3' deployment.yaml

Reference

For advanced jq filters and recipes: references/recipes.md