Guía de la Habilidad

La habilidad gcyphrq permite a los agentes de IA para codificación ejecutar consultas Cypher sobre archivos JSON de grafos usando instrucciones en lenguaje natural. Instálala una vez, luego haz preguntas como "¿Qué servicios dependen de la API Gateway?" y obtén resultados JSON estructurados.

Qué Hace la Habilidad

Cuando está instalada, la habilidad enseña a un agente de IA a:

Traducir lenguaje natural a consultas Cypher automáticamente
Ejecutar consultas contra tus archivos JSON de grafos usando el CLI gcyphrq
Interpretar resultados y presentarlos en un formato legible
Encadenar múltiples consultas para análisis complejos (radio de explosión, trazado de rutas, análisis de grado)

La habilidad incluye una biblioteca seleccionada de patrones de consulta para preguntas comunes de infraestructura: dependencias de servicios, topología de replicación, cobertura de monitoreo y más.

Instalación

Usando el CLI (Recomendado)

La forma más sencilla es usar el comando de instalación integrado. Detecta tus agentes instalados (pi, Claude Code, OpenCode) e instala la habilidad automáticamente:

# Instalar globalmente (enlaces simbólicos en directorios de configuración del agente)
gcyphrq --install-skill global

# Instalar localmente (copia en el directorio actual)
gcyphrq --install-skill local

El comando --install-skill:

Detecta qué agentes están instalados en tu sistema
Crea enlaces simbólicos (global) o copias (local) del contenido de la habilidad
Genera archivos de referencia CLAUDE.md / AGENTS.md para Claude Code y OpenCode
Es idempotente — se puede ejecutar varias veces sin problemas

Después de la instalación:

Pi reconoce la habilidad automáticamente. Invócala con /skill:gcyphrq o describe lo que quieres en lenguaje natural.
Claude Code reconoce la habilidad automáticamente cuando haces preguntas relacionadas con grafos.
OpenCode carga la habilidad cuando tus prompts coinciden con su descripción (consultas de grafos, topología de infraestructura, dependencias de servicios, etc.).

Instalación Manual

Si el comando de instalación no funciona para tu configuración, puedes colocar el directorio de la habilidad 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

También puedes descargar el directorio references/ (que contiene queries.md y example-graph.json) en un subdirectorio references/ junto a SKILL.md para obtener patrones de consulta adicionales y un grafo de prueba autónomo.

Otros Agentes

Para cualquier agente de IA para codificación que admita instrucciones personalizadas o system prompts:

Instala el CLI: npm install -g gcyphrq
Copia el SKILL.md desde https://raw.githubusercontent.com/plelevier/gcyphrq/main/skills/gcyphrq/SKILL.md en las instrucciones personalizadas de tu agente
Copia los archivos de referencia desde https://raw.githubusercontent.com/plelevier/gcyphrq/main/skills/gcyphrq/references/ (que contienen queries.md y example-graph.json) en un subdirectorio references/ junto a SKILL.md
Apunta a tus archivos de grafo — reemplaza <graph.json> en los ejemplos de la habilidad con las rutas a tus archivos de grafo reales

Prerrequisitos

CLI gcyphrq instalado y en PATH — consulta Primeros Pasos para instrucciones de instalación
Un archivo JSON de grafo para consultar (usa el references/example-graph.json incluido para empezar)

Ejemplos de Prompts

Una vez instalada la habilidad, puedes usar prompts en lenguaje natural. Aquí hay ejemplos que la habilidad debería resolver:

Dependencias de Servicios

Prompt: "¿De qué servicios depende la API Gateway?"

La habilidad traduce esto a una consulta Cypher que rastrea las conexiones salientes del nodo API Gateway.

Prompt: "Muéstrame todos los servicios conectados a PostgreSQL."

Devuelve todos los servicios con conexiones TCP a la base de datos PostgreSQL Primaria.

Análisis de Radio de Explosión

Prompt: "Si Kafka se cae, ¿qué se rompe?"

Rastrea todos los nodos alcanzables desde el Clúster Kafka en un máximo de 2 saltos para mostrar el radio de impacto.

Prompt: "¿Cuál es el radio de explosión si falla la API Gateway?"

Mapea todos los servicios descendentes e infraestructura afectados por la indisponibilidad de la API Gateway.

Trazado de Rutas

Prompt: "Muéstrame la ruta desde la CDN hasta la base de datos."

Encuentra la ruta de conexión entre los nodos CDN y base de datos, mostrando los servicios intermedios.

Prompt: "¿Cómo fluye una solicitud desde la API Gateway hasta la base de datos de usuarios?"

Traza la ruta de la solicitud a través de autenticación, servicios RPC y conexiones a la base de datos.

Topología de Infraestructura

Prompt: "¿Cómo están conectadas las colas de mensajes?"

Lista toda la infraestructura de colas de mensajes y sus relaciones productor/consumidor.

Prompt: "¿Cuál es la configuración de replicación de las bases de datos?"

Muestra las relaciones primaria-réplica y los tipos de aristas de replicación.

Análisis de Grado

Prompt: "¿Qué servicio tiene más conexiones salientes?"

Calcula el grado de salida de todos los servicios y devuelve el más conectado.

Prompt: "Encuentra servicios con más de 2 conexiones salientes."

Filtra servicios por umbral de grado de salida usando agregación y WHERE.

Cobertura de Monitoreo

Prompt: "¿Qué servicios están siendo monitoreados?"

Encuentra todos los servicios conectados a infraestructura de monitoreo (Prometheus, Grafana, etc.).

Prompt: "¿Qué servicios no tienen monitoreo?"

Usa OPTIONAL MATCH para encontrar servicios sin conexiones de monitoreo.

Dependencias Externas

Prompt: "¿Qué servicios llaman a APIs externas?"

Traza servicios RPC a través de 1-3 saltos para encontrar dependencias de APIs externas.

Prompt: "Lista todas las integraciones externas."

Devuelve todos los nodos con la etiqueta External y sus llamantes ascendentes.

Filtrado Avanzado

Prompt: "Muéstrame todos los servicios RPC o Worker."

Usa WHERE con OR para coincidir con múltiples tipos.

Prompt: "Encuentra servicios que no sean trabajos por lotes."

Usa WHERE con NOT para excluir un tipo.

Prompt: "Lista servicios en us-east-1 que tengan 'Service' en el nombre."

Usa WHERE con AND para combinar condiciones.

Paginación

Prompt: "Muéstrame la página 2 de servicios, 10 por página, ordenados alfabéticamente."

Usa ORDER BY, SKIP y LIMIT para paginar los resultados de servicios.

Mutaciones del Grafo

Prompt: "Agrega un nuevo servicio de monitoreo llamado 'Datadog'."

Usa CREATE para agregar un nuevo nodo al grafo.

Prompt: "Establece el estado de la API Gateway a 'deprecated'."

Usa SET para actualizar una propiedad de un nodo.

Prompt: "Elimina la etiqueta 'Person' de Alice."

Usa REMOVE para eliminar una etiqueta o propiedad de un nodo manteniendo el nodo y sus relaciones intactas.

Referencia de la Habilidad

El archivo de habilidad (SKILL.md) incluye:

Uso del CLI — sintaxis de comandos, opciones, entrada por stdin, encadenamiento de consultas
Formato del archivo de grafo — estructura de nodos y aristas
Características de Cypher soportadas — matriz completa de características con estado
Patrones de consulta — consultas preconstruidas usando el references/example-graph.json incluido
Formato de salida — formato de grafo (predeterminado) y formato de filas con ejemplos de encadenamiento
Limitaciones — restricciones conocidas (sin subconsultas, sin APOC, etc.)

Solución de Problemas

Problema	Solución
`gcyphrq: command not found`	Ejecuta `npm install -g gcyphrq`
La habilidad no es detectada por el agente	Verifica que el `SKILL.md` esté en el directorio de habilidades correcto para tu plataforma
La consulta devuelve resultados vacíos	Verifica que las etiquetas de los nodos y los nombres de propiedades coincidan exactamente con tu archivo de grafo

Próximos Pasos

[Primeros Pasos]({{ '/getting-started/' | relative_url }}) — Instala gcyphrq y ejecuta tu primera consulta
[Guía de Consultas]({{ '/query-guide/' | relative_url }}) — Referencia completa de sintaxis Cypher
[Ejemplos]({{ '/examples/' | relative_url }}) — 30 consultas listas para ejecutar con salida de ejemplo
[API de la Librería]({{ '/library-api/' | relative_url }}) — Usa gcyphrq programáticamente en Node.js / TypeScript

plelevier/gcyphrq

¿Qué es gcyphrq?

Preguntar en tu IA favorita

Documentación