Files

SKILL.mdagentsreferencesscripts

Install

Install the containing plugin

/plugin install shared-skills@llm-skills

Invoke this skill after installation

/shared-skills:xq

Download xq-skill.zip

This skill is bundled inside shared-skills. Install the plugin once, then Claude Code can use any of its included skills. Browse the full plugin repository at github.com/alisonaquinas/llm-shared-skills.

SKILL.md

name: xq description: > Query and transform XML documents using jq-compatible filter syntax. Use when the task involves extracting fields from XML, filtering XML arrays, converting XML to JSON, converting JSON back to XML, or applying jq-style transformations to XML data. xq is installed alongside yq via pip and works identically to jq but accepts XML input. Also supports streaming large XML files to avoid loading the full document into memory.

xq

Query and transform XML using jq filter syntax. xq transcodes XML to JSON internally, then passes it through jq, giving full access to jq's filter language on XML input.

Prerequisite Check

Run this before proposing xq filters:

command -v xq >/dev/null 2>&1 && command -v jq >/dev/null 2>&1

If xq or jq is missing, surface that first and point to scripts/install.sh or scripts/install.ps1. If the task only needs direct XML queries, fall back to xmllint instead of pretending jq-style filters are available.

Intent Router

Request	Reference	Load When
Install xq, jq dependency	`references/install-and-setup.md`	Setting up on a new system
Flags, options, one-liners	`references/cheatsheet.md`	Need quick command lookup
Streaming, roundtrip, complex filters	`references/advanced-usage.md`	Large files or multi-step transforms

Quick Start

# Extract a field
xq '.root.item.title' file.xml

# From stdin
cat feed.xml | xq '.rss.channel.title'

# Output as XML instead of JSON
xq -x '.rss.channel' feed.xml

# Get array length
xq '.rss.channel.item | length' feed.xml

# Filter array elements
xq '.catalog.book[] | select(.price | tonumber > 20) | .title' books.xml

# Verify the dependency chain before filtering
xq --help
jq --version

# Fallback for direct XML extraction when xq is unavailable
xmllint --xpath '//book/title/text()' books.xml

How It Works

xq converts XML → JSON using xmltodict
The JSON is piped through jq with the given filter
Output is JSON by default; use -x to get XML back

Attributes in XML become @attr keys in JSON:

<item id="42">Hello</item>

becomes:

{"item": {"@id": "42", "#text": "Hello"}}

Core Workflow

Probe structure: xq '.' file.xml — see the full JSON representation
Navigate to target: xq '.root.child' file.xml
Filter or transform with jq syntax
Use -x to reconstruct XML from the result if needed

Safety Notes

Area	Guardrail
XXE	Entity expansion is disabled by default via xmltodict. External entities are not fetched.
Large files	Use `--xml-item-depth N` to stream without loading full document into memory.
jq dependency	`jq` must be installed separately before `xq` works. Verify with `jq --version`.
Repeated elements	XML with repeated sibling elements is converted to a JSON array. A single element produces an object, not an array — use `Arrays` or `--xml-force-list` if needed.

Recovery note: if either xq or jq is missing, keep the fallback boundary explicit. xmllint can query XML directly, but it does not support jq-style transformations.

Resource Index

scripts/install.sh — Install jq and xq on macOS or Linux
scripts/install.ps1 — Install jq and xq on Windows