Guia da Skill
A skill gcyphrq permite que agentes de IA de codificação executem consultas Cypher em arquivos JSON de grafos usando comandos em linguagem natural. Instale-a uma vez e faça perguntas como "Quais serviços dependem do API Gateway?" e obtenha resultados JSON estruturados.
O que a Skill Faz
Quando instalada, a skill ensina um agente de IA a:
- Traduzir linguagem natural para consultas Cypher automaticamente
- Executar consultas em seus arquivos JSON de grafos usando a CLI
gcyphrq - Interpretar resultados e apresentá-los em um formato legível
- Encadear múltiplas consultas para análises complexas (blast radius, rastreamento de caminho, análise de grau)
A skill inclui uma biblioteca curada de padrões de consulta para perguntas comuns de infraestrutura — dependências de serviços, topologia de replicação, cobertura de monitoramento e muito mais.
Instalação
Usando a CLI (Recomendado)
A maneira mais fácil é usar o comando de instalação embutido. Ele detecta seus agentes instalados (pi, Claude Code, OpenCode) e instala a skill automaticamente:
# Instalar globalmente (links simbólicos nos diretórios de configuração dos agentes)
gcyphrq --install-skill global
# Instalar localmente (copia para o diretório atual)
gcyphrq --install-skill local
O comando --install-skill:
- Detecta quais agentes estão instalados no seu sistema
- Cria links simbólicos (global) ou cópias (local) do conteúdo da skill
- Gera arquivos de referência
CLAUDE.md/AGENTS.mdpara Claude Code e OpenCode - É idempotente — seguro executar várias vezes
Após a instalação:
- Pi reconhece a skill automaticamente. Invoque com
/skill:gcyphrqou descreva o que deseja em linguagem natural. - Claude Code reconhece a skill automaticamente quando você faz perguntas relacionadas a grafos.
- OpenCode carrega a skill quando seus prompts correspondem à sua descrição (consultas de grafo, topologia de infraestrutura, dependências de serviços, etc.).
Instalação Manual
Se o comando de instalação não funcionar para sua configuração, você pode colocar o diretório da skill manualmente:
# pi
mkdir -p ~/.pi/agent/skills/gcyphrq
curl -sL https://raw.githubusercontent.com/plelevier/gcyphrq/main/skills/gcyphrq/SKILL.md \
-o ~/.pi/agent/skills/gcyphrq/SKILL.md
# Claude Code
mkdir -p ~/.claude/skills/gcyphrq
curl -sL https://raw.githubusercontent.com/plelevier/gcyphrq/main/skills/gcyphrq/SKILL.md \
-o ~/.claude/skills/gcyphrq/SKILL.md
# OpenCode
mkdir -p ~/.opencode/skills/gcyphrq
curl -sL https://raw.githubusercontent.com/plelevier/gcyphrq/main/skills/gcyphrq/SKILL.md \
-o ~/.opencode/skills/gcyphrq/SKILL.md
Você também pode baixar o diretório references/ (contendo queries.md e example-graph.json) em um subdiretório references/ junto com SKILL.md para padrões de consulta adicionais e um grafo de teste autocontido.
Outros Agentes
Para qualquer agente de IA de codificação que suporte instruções personalizadas ou prompts de sistema:
- Instale a CLI:
npm install -g gcyphrq - Copie o SKILL.md de
https://raw.githubusercontent.com/plelevier/gcyphrq/main/skills/gcyphrq/SKILL.mdpara as instruções personalizadas do seu agente - Copie os arquivos de referência de
https://raw.githubusercontent.com/plelevier/gcyphrq/main/skills/gcyphrq/references/(contendoqueries.mdeexample-graph.json) para um subdiretórioreferences/junto com SKILL.md - Aponte para seus arquivos de grafo — substitua
<graph.json>nos exemplos da skill pelos caminhos para seus arquivos de grafo reais
Pré-requisitos
- CLI gcyphrq instalada e no PATH — veja Primeiros Passos para instruções de instalação
- Um arquivo JSON de grafo para consultar (use o
references/example-graph.jsonincluído para começar)
Exemplos de Prompts
Uma vez instalada a skill, você pode usar prompts em linguagem natural. Aqui estão exemplos que a skill deve resolver:
Dependências de Serviços
Prompt: "De quais serviços o API Gateway depende?"
A skill traduz isso para uma consulta Cypher que rastreia as conexões de saída do nó API Gateway.
Prompt: "Mostre-me todos os serviços conectados ao PostgreSQL."
Retorna todos os serviços com conexões TCP ao banco de dados PostgreSQL Primary.
Análise de Blast Radius
Prompt: "Se o Kafka cair, o que quebra?"
Rastreia todos os nós alcançáveis a partir do Cluster Kafka dentro de 2 saltos para mostrar o raio de impacto.
Prompt: "Qual é o blast radius se o API Gateway falhar?"
Mapeia todos os serviços downstream e infraestrutura afetados pela indisponibilidade do API Gateway.
Rastreamento de Caminho
Prompt: "Mostre-me o caminho da CDN até o banco de dados."
Encontra o caminho de conexão entre os nós da CDN e do banco de dados, mostrando os serviços intermediários.
Prompt: "Como uma requisição flui do API Gateway até o banco de dados do usuário?"
Rastreia o caminho da requisição através de autenticação, serviços RPC e conexões de banco de dados.
Topologia de Infraestrutura
Prompt: "Como as filas de mensagem estão conectadas?"
Lista toda a infraestrutura de filas de mensagem e suas relações de produtor/consumidor.
Prompt: "Qual é a configuração de replicação dos bancos de dados?"
Mostra as relações primário-réplica e os tipos de arestas de replicação.
Análise de Grau
Prompt: "Qual serviço tem mais conexões de saída?"
Calcula o grau de saída para todos os serviços e retorna o mais conectado.
Prompt: "Encontre serviços com mais de 2 conexões de saída."
Filtra serviços pelo limite de grau de saída usando agregação e WHERE.
Cobertura de Monitoramento
Prompt: "Quais serviços estão sendo monitorados?"
Encontra todos os serviços conectados à infraestrutura de monitoramento (Prometheus, Grafana, etc.).
Prompt: "Quais serviços não têm monitoramento?"
Usa OPTIONAL MATCH para encontrar serviços sem conexões de monitoramento.
Dependências Externas
Prompt: "Quais serviços chamam APIs externas?"
Rastreia serviços RPC através de 1-3 saltos para encontrar dependências de API externas.
Prompt: "Liste todas as integrações externas."
Retorna todos os nós com o rótulo External e seus chamadores upstream.
Filtragem Avançada
Prompt: "Mostre-me todos os serviços RPC ou Worker."
Usa WHERE com OR para corresponder a múltiplos tipos.
Prompt: "Encontre serviços que não são jobs em lote."
Usa WHERE com NOT para excluir um tipo.
Prompt: "Liste serviços em us-east-1 que tenham 'Service' no nome."
Usa WHERE com AND para combinar condições.
Paginação
Prompt: "Mostre-me a página 2 de serviços, 10 por página, ordenado alfabeticamente."
Usa ORDER BY, SKIP e LIMIT para paginar pelos resultados dos serviços.
Mutações no Grafo
Prompt: "Adicione um novo serviço de monitoramento chamado 'Datadog'."
Usa CREATE para adicionar um novo nó ao grafo.
Prompt: "Defina o status do API Gateway como 'deprecated'."
Usa SET para atualizar uma propriedade do nó.
Prompt: "Remova o rótulo 'Person' de Alice."
Usa REMOVE para remover um rótulo ou propriedade de um nó, mantendo o nó e seus relacionamentos intactos.
Referência da Skill
O arquivo da skill (SKILL.md) inclui:
- Uso da CLI — sintaxe de comandos, opções, piping stdin, encadeamento de consultas
- Formato do arquivo de grafo — estrutura de nós e arestas
- Funcionalidades Cypher suportadas — matriz de funcionalidades completa com status
- Padrões de consulta — consultas pré-construídas usando o
references/example-graph.jsonincluído - Formato de saída — formato de grafo (padrão) e formato de linhas com exemplos de encadeamento
- Limitações — restrições conhecidas (sem subconsultas, sem APOC, etc.)
Solução de Problemas
| Problema | Solução |
|---|---|
gcyphrq: command not found | Execute npm install -g gcyphrq |
| Skill não detectada pelo agente | Verifique se o SKILL.md está no diretório de skills correto para sua plataforma |
| Consulta retorna resultados vazios | Verifique se os rótulos dos nós e nomes de propriedades correspondem exatamente ao seu arquivo de grafo |
Próximos Passos
- [Primeiros Passos]({{ '/getting-started/' | relative_url }}) — Instale o gcyphrq e execute sua primeira consulta
- [Guia de Consultas]({{ '/query-guide/' | relative_url }}) — Referência completa da sintaxe Cypher
- [Exemplos]({{ '/examples/' | relative_url }}) — 30 consultas prontas para execução com saída de exemplo
- [API da Biblioteca]({{ '/library-api/' | relative_url }}) — Use gcyphrq programaticamente em Node.js / TypeScript