tool-yq

name	tool-yq
description	Use yq for YAML and structured config queries, edits, and transforms. Trigger when CI configs, manifests, or YAML-based settings need precise changes.

tool-yq

When To Use

• Query and update YAML config files safely.
• Convert between YAML and JSON formats in pipelines.
• Merge and reshape config fragments without manual text editing.

Trusted Commands

yq '.spec.replicas' file.yaml
yq -o json file.yaml
yq -P file.json
yq -i '.version = "2.0"' file.yaml
yq eval-all 'select(fi == 0) * select(fi == 1)' a.yaml b.yaml

Safe Defaults

• Validate with read-only queries before in-place edits.
• Use explicit paths for targeted updates.
• Confirm tool variant expectations (Go yq syntax).

Common Pitfalls

• Multiple yq implementations use different syntax.
• -i modifies files directly and should be reviewed with git diff.
• Broad expressions can unintentionally reshape unrelated sections.

Output Interpretation

• YAML output by default.
• -o json outputs JSON for downstream tooling.
• -P pretty-prints YAML from any supported input.

Why It Matters For Agents

• yq gives precise config manipulation without brittle regex edits.
• It complements jq for non-JSON configuration ecosystems.

Repo Conventions

• Use yq for focused config changes, not full-file rewrites.
• Keep workflow edits minimal and reviewable.

Trigger Examples

• Should trigger: "Change a YAML workflow key without touching other lines."
• Should trigger: "Read the matrix entries from this CI config."
• Should not trigger: "Search all source files for a plain text token."