yq

This skill should be used when the user asks to "get a field from docker-compose", "extract value from yaml", "what services are in this compose file", "get the image from kubernetes manifest", "pull workflow triggers from github actions", "check the version in pubspec.yaml", or when needing specific fields from YAML/JSON config files without loading the entire file.

⭐2stars🔀0forks📁View on GitHub🕐Updated Dec 21, 2025⬇️2downloads

When & Why to Use This Skill

The yq skill is a specialized YAML and JSON processing utility designed to extract specific fields and data points from configuration files with high precision. It optimizes AI performance by retrieving only the necessary information, significantly reducing token consumption and context clutter when working with large-scale files like Docker Compose, Kubernetes manifests, and CI/CD workflows.

Use Cases

  • Case 1: Extracting specific service images, port mappings, or environment variables from complex docker-compose.yml files without reading the entire configuration.
  • Case 2: Auditing GitHub Actions workflows to identify specific job triggers, step names, or 'runs-on' parameters for CI/CD pipeline analysis.
  • Case 3: Querying Kubernetes manifests to retrieve container specs, replica counts, or metadata labels from large deployment or service YAMLs.
  • Case 4: Checking dependency versions and script definitions in project configuration files such as pubspec.yaml, package.json, or tsconfig.json.
  • Case 5: Navigating deeply nested structures in large configuration files (>50 lines) to provide precise answers while maintaining context efficiency.
nameyq
descriptionThis skill should be used when the user asks to "get a field from docker-compose", "extract value from yaml", "what services are in this compose file", "get the image from kubernetes manifest", "pull workflow triggers from github actions", "check the version in pubspec.yaml", or when needing specific fields from YAML/JSON config files without loading the entire file.

yq: YAML/JSON Query Tool

Extract specific fields from YAML and JSON files without reading entire contents into context.

When to Use

Use yq when:

  • Need specific field(s) from YAML/JSON config
  • File is large (>50 lines) and only need subset
  • Querying nested structures
  • Working with docker-compose, GitHub Actions, K8s, Helm charts

Just use Read when:

  • File is small (<50 lines)
  • Need to understand overall structure
  • Making edits (need full context anyway)

Common Files

  • docker-compose.yml - services, ports, volumes, networks
  • .github/workflows/*.yml - triggers, jobs, steps
  • kubernetes/*.yaml - deployments, services, configmaps
  • pubspec.yaml - Flutter/Dart dependencies
  • package.json - npm dependencies (use jq)
  • tsconfig.json - TypeScript config (use jq)

Quick Reference

# Get specific field
yq '.version' pubspec.yaml
yq '.services.web.image' docker-compose.yml

# Get all keys at level
yq '.services | keys' docker-compose.yml

# Get nested array element
yq '.jobs.build.steps[0].name' .github/workflows/ci.yml

# Filter by condition
yq '.services.[] | select(.ports)' docker-compose.yml

# Multiple fields
yq '.name, .version' pubspec.yaml

# Output as JSON
yq -o=json '.' config.yaml

jq for JSON

Same patterns, different tool:

# Get dependency version
jq '.dependencies["react"]' package.json

# Get all script names
jq '.scripts | keys' package.json

# Get compiler options
jq '.compilerOptions.target' tsconfig.json

Docker Compose Patterns

# List all services
yq '.services | keys' docker-compose.yml

# Get ports for a service
yq '.services.web.ports' docker-compose.yml

# Get all images
yq '.services.*.image' docker-compose.yml

# Get environment variables
yq '.services.api.environment' docker-compose.yml

GitHub Actions Patterns

# Get workflow triggers
yq '.on' .github/workflows/ci.yml

# List all jobs
yq '.jobs | keys' .github/workflows/ci.yml

# Get steps for a job
yq '.jobs.build.steps[].name' .github/workflows/ci.yml

# Get runs-on value
yq '.jobs.build.runs-on' .github/workflows/ci.yml

Kubernetes Patterns

# Get container image
yq '.spec.template.spec.containers[0].image' deployment.yaml

# Get replicas
yq '.spec.replicas' deployment.yaml

# Get all labels
yq '.metadata.labels' service.yaml

# Get ports
yq '.spec.ports' service.yaml

Core Principle

Extract exactly what's needed in one command. Saves 80-95% context vs reading entire config files.