Communitygithub.com

JantonioFC/skillsbank

Uso especializado do jq para consulta, filtragem, transformação e integração em pipelines JSON. Padrões práticos para fluxos reais no shell.

O que é skillsbank?

Esta skill cobre o uso avançado do jq, a ferramenta CLI padrão para consulta e transformação de JSON, voltada para desenvolvedores que trabalham com APIs, logs, ferramentas de DevOps (kubectl, AWS CLI, Docker) e automação de shell. Ela ensina desde seleção básica de campos e navegação em arrays até técnicas sofisticadas como filtragem com `select`, mapeamento e transformação de objetos, agregação com `reduce`, tratamento de erros e integração segura com variáveis do shell. A skill é compatível com qualquer ambiente que tenha jq instalado (Linux, macOS, Windows via WSL) e pode ser usada em scripts bash, one-liners ou interativamente. Seu valor está em acelerar o trabalho com dados JSON, evitando parse manual com ferramentas como `grep` ou `sed`, e promovendo padrões robustos e reutilizáveis. Inclui exemplos prontos para copiar e colar, abrangendo desde a extração de IDs de instâncias na AWS até a formatação de saída CSV.

Funciona com✓Claude Code~Codex CLI✓Cursor✓Gemini CLI
npx skills add https://github.com/JantonioFC/skillsbank/tree/HEAD/skills/jq

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

jq — Consulta e Transformação de JSON

Visão Geral

jq é a ferramenta CLI padrão para consultar e remodelar JSON. Esta skill cobre o uso prático em nível especializado: filtrar dados profundamente aninhados, transformar estruturas, agregar valores e compor jq em pipelines de shell. Todos os exemplos estão prontos para copiar e colar em fluxos de trabalho reais.

Quando Usar Esta Skill

  • Use ao analisar saída JSON de APIs, ferramentas CLI (AWS, GitHub, kubectl, docker) ou arquivos de log
  • Use ao transformar estrutura JSON (renomear chaves, achatar arrays, agrupar registros)
  • Use quando o usuário precisar de jq dentro de um script bash ou one-liner
  • Use ao explicar o que uma expressão jq complexa faz

Como Funciona

jq recebe uma expressão de filtro e a aplica à entrada JSON. Filtros se compõem com pipes (|), e o jq lida nativamente com arrays, objetos, strings, números, booleanos e null.

Seleção Básica

# Extrair um campo
echo '{"nome":"alice","idade":30}' | jq '.nome'
# "alice"

# Acesso aninhado
echo '{"usuario":{"email":"[email protected]"}}' | jq '.usuario.email'

# Índice de array
echo '[10, 20, 30]' | jq '.[1]'
# 20

# Fatia de array
echo '[1,2,3,4,5]' | jq '.[2:4]'
# [3, 4]

# Todos os elementos do array
echo '[{"id":1},{"id":2}]' | jq '.[]'

Filtragem com select

# Manter apenas elementos correspondentes
echo '[{"funcao":"admin"},{"funcao":"usuario"},{"funcao":"admin"}]' \
  | jq '[.[] | select(.funcao == "admin")]'

# Comparação numérica
curl -s https://api.github.com/repos/dono/repo/issues \
  | jq '[.[] | select(.comments > 5)]'

# Testar se um campo existe e não é nulo
jq '[.[] | select(.email != null)]'

# Combinar condições
jq '[.[] | select(.ativo == true and .pontuacao >= 80)]'

Mapeamento e Transformação

# Extrair um campo de cada elemento do array
echo '[{"nome":"alice","idade":30},{"nome":"bob","idade":25}]' \
  | jq '[.[] | .nome]'
# ["alice", "bob"]

# Abreviação: map()
jq 'map(.nome)'

# Construir um novo objeto por elemento
jq '[.[] | {usuario: .nome, anos: .idade}]'

# Adicionar um campo calculado
jq '[.[] | . + {senior: (.idade > 28)}]'

# Renomear chaves
jq '[.[] | {nome_usuario: .nome, endereco_email: .email}]'

Agregação e Reduce

# Somar todos os valores
echo '[1, 2, 3, 4, 5]' | jq 'add'
# 15

# Somar um campo entre objetos
jq '[.[].preco] | add'

# Contar elementos
jq 'length'

# Máximo / mínimo
jq 'max_by(.pontuacao)'
jq 'min_by(.criado_em)'

# reduce: acumulador personalizado
echo '[1,2,3,4,5]' | jq 'reduce .[] as $x (0; . + $x)'
# 15

# Agrupar por campo
jq 'group_by(.departamento)'

# Contar por grupo
jq 'group_by(.status) | map({status: .[0].status, contagem: length})'

Interpolação de Strings e Formatação

# Interpolação de strings
jq -r '.[] | "\(.nome) tem \(.idade) anos de idade"'

# Formatar como CSV (sem cabeçalho)
jq -r '.[] | [.nome, .idade, .email] | @csv'

# Formatar como TSV
jq -r '.[] | [.nome, .pontuacao] | @tsv'

# Codificar valor para URL
jq -r '.consulta | @uri'

# Codificar em Base64
jq -r '.dados | @base64'

Trabalhando com Chaves e Caminhos

# Listar todas as chaves de nível superior
jq 'keys'

# Verificar se uma chave existe
jq 'has("email")'

# Excluir uma chave
jq 'del(.senha)'

# Excluir chaves aninhadas de cada elemento
jq '[.[] | del(.id_interno, .dados_crus)]'

# Descida recursiva: encontrar todos os valores de uma chave em qualquer lugar da árvore
jq '.. | .id? // empty'

# Obter todos os caminhos até folhas
jq '[paths(scalars)]'

Condicionais e Tratamento de Erros

# if-then-else
jq 'if .pontuacao >= 90 then "A" elif .pontuacao >= 80 then "B" else "C" end'

# Operador alternativo: usar fallback se nulo ou falso
jq '.apelido // .nome'

# try-catch: pular erros em vez de parar
jq '[.[] | try .aninhado.valor catch null]'

# Suprimir saída nula com // empty
jq '.[] | .campo_opcional // empty'

Integração Prática com Shell

# Ler de arquivo
jq '.usuarios' dados.json

# Saída compacta (sem espaços) para pipe
jq -c '.[]' registros.json | while IFS= read -r registro; do
  echo "Processando: $registro"
done

# Passar variável do shell para o jq
STATUS="ativo"
jq --arg s "$STATUS" '[.[] | select(.status == $s)]'

# Passar um número
jq --argjson limite 42 '[.[] | select(.valor > $limite)]'

# Juntar várias linhas JSON em um array
jq -s '.' registros.ndjson

# Vários arquivos: juntar todos em um array
jq -s 'add' arquivo1.json arquivo2.json

# Pipeline à prova de nulo a partir de um comando
kubectl get pods -o json | jq '.items[] | {nome: .metadata.name, status: .status.phase}'

# GitHub CLI: extrair números de PR
gh pr list --json number,title | jq -r '.[] | "\(.number)\t\(.title)"'

# AWS CLI: listar IDs de instâncias em execução
aws ec2 describe-instances \
  | jq -r '.Reservations[].Instances[] | select(.State.Name=="running") | .InstanceId'

# Docker: mostrar nomes e imagens dos contêineres
docker inspect $(docker ps -q) | jq -r '.[] | "\(.Name)\t\(.Config.Image)"'

Padrões Avançados

# Transpor um objeto de arrays para um array de objetos
# Entrada: {"nomes":["a","b"],"pontuacoes":[10,20]}
jq '[.nomes, .pontuacoes] | transpose | map({nome: .[0], pontuacao: .[1]})'

# Achatar um nível
jq 'flatten(1)'

# Único por campo
jq 'unique_by(.email)'

# Ordenar, deduplicar e reindexar
jq '[.[] | .nome] | unique | sort'

# Walk: aplicar transformação a cada nó recursivamente
jq 'walk(if type == "string" then ascii_downcase else . end)'

# env: ler variáveis de ambiente dentro do jq
export API_KEY=segredo
jq -n 'env.API_KEY'

Melhores Práticas

  • Sempre use -r (saída raw) ao passar resultados do jq para variáveis do shell ou outros comandos para remover as aspas do JSON
  • Use --arg / --argjson para injetar variáveis do shell com segurança — nunca interpole variáveis do shell diretamente em strings de filtro
  • Prefira map(f) a [.[] | f] para legibilidade
  • Use -c (compacto) para pipelines JSON delimitados por nova linha; omita para depuração legível por humanos
  • Teste filtros interativamente com jq -n e entrada literal antes de incorporar em scripts
  • Use empty para descartar elementos indesejados em vez de filtrar para null

Notas de Segurança

  • jq é somente leitura por design — não pode escrever arquivos nem executar comandos
  • Evite incorporar valores de campos JSON não confiáveis diretamente em comandos do shell; sempre cite ou use --arg

Armadilhas Comuns

  • Problema: jq produz null em vez do valor esperado Solução: Verifique erros de digitação nos nomes das chaves; use keys para inspecionar os nomes reais dos campos. Lembre-se que JSON diferencia maiúsculas de minúsculas.

  • Problema: Números aparecem entre aspas na saída Solução: Use --argjson em vez de --arg ao injetar valores numéricos.

  • Problema: O filtro funciona no terminal, mas falha em um script Solução: Garanta que a string do filtro use aspas simples no shell para evitar expansão de variáveis. Exemplo: jq '.campo' e não jq ".campo".

  • Problema: add retorna null em um array vazio Solução: Use add // 0 ou add // "" para fornecer um valor padrão alternativo.

  • Problema: Processar arquivos grandes é lento Solução: Use jq --stream ou mude para jstream/gron para arquivos muito grandes.

Skills Relacionadas

  • @bash-pro — Encapsulando chamadas jq em scripts shell robustos
  • @bash-linux — Padrões gerais de pipeline shell
  • @github-automation — Usando jq com saída JSON do GitHub CLI

Limitações

  • Use esta skill apenas quando a tarefa corresponder claramente ao escopo descrito acima.
  • Não trate a saída como substituta para validação, teste ou revisão especializada específica do ambiente.
  • Pare e peça esclarecimentos se os requisitos de entrada, permissões, limites de segurança ou critérios de sucesso estiverem ausentes.

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

JantonioFC/skillsbank

AI-powered image editing with style transfer and object removal

JantonioFC/skillsbank

Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support.

JantonioFC/skillsbank

Analise e auditoria de editais de leilao judicial e extrajudicial. Riscos ocultos, clausulas perigosas, debitos, ocupante e classificacao da oportunidade.

JantonioFC/skillsbank

Embed Photopea in web apps using photopea.js. Covers embedding, file I/O, scripting, exporting, layers, text, filters, and the full Photoshop-compatible API.

JantonioFC/skillsbank

Best practices for Remotion - Video creation in React

JantonioFC/skillsbank

Generate walkthrough videos from Stitch projects using Remotion with smooth transitions, zooming, and text overlays

JantonioFC/skillsbank

Seek and analyze video content using Memories.ai Large Visual Memory Model for persistent video intelligence

JantonioFC/skillsbank

Writes complete, structured landing pages optimized for SEO ranking, AEO citation, and visitor conversion. Activate when the user wants to write or generate a landing page for a product, service, or offer.

JantonioFC/skillsbank

Video and audio perception, indexing, and editing. Ingest files/URLs/live streams, build visual/spoken indexes, search with timestamps, edit timelines, add overlays/subtitles, generate media, and create real-time alerts.

JantonioFC/skillsbank

Upload, stream, search, edit, transcribe, and generate AI video and audio using the VideoDB SDK.

JantonioFC/skillsbank

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

JantonioFC/skillsbank

Expert in building portfolios that actually land jobs and clients - not just showing work, but creating memorable experiences. Covers developer portfolios, designer portfolios, creative portfolios, and portfolios that convert visitors into opportunities.

JantonioFC/skillsbank

Tool lifecycle UI components for React/Next.js from ui.inference.sh. Display tool calls: pending, progress, approval required, results. Capabilities: tool status, progress indicators, approval flows, results display. Use for: showing agent tool calls, human-in-the-loop approvals, tool output. Triggers: tool ui, tool calls, tool status, tool approval, tool results, agent tools, mcp tools ui, function calling ui, tool lifecycle, tool pending

JantonioFC/skillsbank

Security audit, hardening, threat modeling (STRIDE/PASTA), Red/Blue Team, OWASP checks, code review, incident response, and infrastructure security for any project.

JantonioFC/skillsbank

When the user wants help with paid advertising campaigns on Google Ads, Meta (Facebook/Instagram), LinkedIn, Twitter/X, or other ad platforms. Also use when the user mentions 'PPC,' 'paid media,' 'ROAS,' 'CPA,' 'ad campaign,' 'retargeting,' 'audience targeting,' 'Google Ads,' 'Facebook ads,'...

JantonioFC/skillsbank

Create AI avatar and talking head videos with OmniHuman, Fabric, PixVerse via inference.sh CLI. Models: OmniHuman 1.5, OmniHuman 1.0, Fabric 1.0, PixVerse Lipsync. Capabilities: audio-driven avatars, lipsync videos, talking head generation, virtual presenters. Use for: AI presenters, expla...

JantonioFC/skillsbank

Create AI marketing videos for ads, promos, product launches, and brand content. Models: Veo, Seedance, Wan, FLUX for visuals, Kokoro for voiceover. Types: product demos, testimonials, explainers, social ads, brand videos. Use for: Facebook ads, YouTube ads, product launches, brand awarene...

JantonioFC/skillsbank

Generate AI videos with Google Veo, Seedance, Wan, Grok and 40+ models via inference.sh CLI. Models: Veo 3.1, Veo 3, Seedance 1.5 Pro, Wan 2.5, Grok Imagine Video, OmniHuman, Fabric, HunyuanVideo. Capabilities: text-to-video, image-to-video, lipsync, avatar animation, video upscaling, fole...

JantonioFC/skillsbank

Production-ready CI/CD configurations for Playwright — GitHub Actions, GitLab CI, CircleCI, Azure DevOps, Jenkins, Docker, parallel sharding, reporting, code coverage, and global setup/teardown.

JantonioFC/skillsbank

You are an expert copy editor specializing in marketing and conversion copy. Your goal is to systematically improve existing copy through focused editing passes while preserving the core message.

Habilidades Relacionadas