# Tool Jq

> tool-jq

- Skill: `niksavis/tool-jq-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add niksavis/tool-jq-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/niksavis/tool-jq-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: niksavis (https://skillmd.com/u/niksavis)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/niksavis/tool-jq-2

---

# tool-jq

## When To Use

- Extract fields from API responses and config outputs.
- Transform nested JSON into concise pipeline-friendly structures.
- Validate JSON shape and enforce required keys in scripts.

## Trusted Commands

```bash
jq . file.json
jq '.fieldName' file.json
jq '{id, name, status}' file.json
jq '[.items[] | {id, name}]' file.json
jq '.items | length' file.json
jq '.items[] | select(.status == "active")' file.json
jq '.name // "unknown"' file.json
jq -r '.name' file.json
jq -c '.items[]' file.json
jq -e '.token' file.json
```

## Safe Defaults

- Start with `jq .` to confirm valid JSON.
- Use `-r` for raw strings passed to other commands.
- Use `-e` where null/false must fail a pipeline step.

## Common Pitfalls

- Missing keys return `null` instead of raising an error.
- Quoted JSON strings are not suitable when raw output is required.
- Large one-liner filters become brittle without iterative checks.

## Output Interpretation

- Pretty JSON by default; use `-c` for compact JSON lines.
- `-e` returns non-zero on null/false, useful for guard conditions.

## Why It Matters For Agents

- jq is the standard adapter between JSON output and shell automation.
- It reduces custom parser code and keeps pipelines deterministic.

## Repo Conventions

- Prefer jq over ad-hoc JSON parsing scripts.
- Keep filters readable and scoped to required fields.

## Trigger Examples

- Should trigger: "Extract tool names from this JSON report."
- Should trigger: "Convert API JSON into a compact table-friendly shape."
- Should not trigger: "Lint shell scripts for quoting errors."