skogai-jq_skill

Overview

This skill provides a schema-driven library of 60+ jq transformations tailored for AI agents working with JSON. It exposes small, composable transforms with explicit input/output contracts and argument-based invocation. The collection emphasizes discoverability and safe, minimal implementations to make JSON manipulation predictable and testable.

How this skill works

Each transform is a standalone jq script that accepts parameters via --arg and --argjson and operates on JSON piped through stdin. Transforms are organized by category (CRUD, array, string, extract, validate, type conversions) and are designed to be chained with Unix pipes for multi-step workflows. Schemas describe expected inputs, outputs, and examples so you can pick transforms by contract rather than guessing behavior.

When to use it

• Manipulating nested JSON (get/set/delete/check/merge) without writing custom jq every time
• Filtering, mapping, reducing, flattening or deduplicating arrays in JSON payloads
• Extracting patterns from text fields (URLs, code blocks, mentions) embedded in JSON
• Validating required fields or types before further processing
• Converting JSON values between types (to-string, to-number, to-array) safely
• Composing multi-step transformations for API response normalization or config generation

Best practices

• Prefer transforms by schema: choose a transform whose input/output contract matches your goal
• Pass parameters only via --arg or --argjson to keep transforms deterministic and reusable
• Chain small transforms via pipes instead of creating a single large jq script
• Run the provided test scripts for a transform before using it in production
• Use try/catch patterns and has() checks in custom additions to avoid jq pitfalls

Example use cases

• Normalize API responses: filter active users, map to emails, and convert timestamps to ISO
• Edit configuration files: set nested fields, add defaults, and validate required keys
• Extract metadata: pull URLs and mentions from text fields into a summary array
• Data cleaning: deduplicate, flatten nested arrays, and coerce string numbers to numbers
• Validation pipeline: assert required fields and types before ingestion into a database