yq-yaml-processing_skill

Overview

This skill provides practical commands and patterns for querying, filtering, and transforming YAML using the yq v4+ command-line tool. It focuses on common tasks like reading fields, editing files in-place, handling multi-document YAML, merging configurations, and converting formats. Use it to speed up YAML edits in CI/CD, Kubernetes manifests, GitHub Actions workflows, and config automation.

How this skill works

The skill uses yq expressions (jq-like syntax) to navigate YAML paths, select and filter documents, and apply transformations. It demonstrates reading values, in-place updates with -i, multi-document operations, object merges (shallow and deep), and format conversion with -o/-p flags. Examples show array indexing, select() filters, del(), and string functions for practical automation tasks.

When to use it

• Quickly inspect or pretty-print YAML files and multi-document manifests
• Modify Kubernetes manifests, Helm values, or GitHub Actions workflows without opening an editor
• Merge configuration files or deep-merge overrides during CI/CD
• Convert YAML to JSON, XML, CSV, or compact JSON for downstream tools
• Filter or extract specific documents from multi-document YAML bundles

Best practices

• Keep destructive changes behind version control and run yq -i only when changes are committed
• Test complex expressions with non-destructive queries (omit -i) before modifying files
• Prefer eval-all for combining files and *+ for deep merges when merging nested structures
• Use select(document_index == N) to target specific documents in multi-doc files
• Use -o and -p to control formats explicitly when piping between tools or scripts

Example use cases

• Update replica counts across multiple Kubernetes Deployment YAMLs with a single command
• Extract container images from manifests for inventory or security scanning
• Merge environment-specific override files into a base config during CI pipeline
• Split or filter a multi-document manifest to isolate resources of a given kind
• Convert YAML workflow definitions to compact JSON for API consumption or diffing