Guide de la compétence
La compétence gcyphrq permet aux agents de codage IA d'exécuter des requêtes Cypher sur des fichiers de graphe JSON en utilisant des invites en langage naturel. Installez-la une fois, puis posez des questions comme "Quels services dépendent de la passerelle API ?" et obtenez des résultats JSON structurés.
Ce que fait la compétence
Une fois installée, la compétence apprend à un agent IA à :
- Traduire le langage naturel en requêtes Cypher automatiquement
- Exécuter des requêtes sur vos fichiers de graphe JSON à l'aide de la CLI
gcyphrq - Interpréter les résultats et les présenter dans un format lisible
- Enchaîner plusieurs requêtes pour des analyses complexes (rayon de souffle, traçage de chemins, analyse de degré)
La compétence inclut une bibliothèque de modèles de requêtes pour les questions d'infrastructure courantes — dépendances de services, topologie de réplication, couverture de surveillance, et plus.
Installation
Utilisation de la CLI (Recommandée)
Le moyen le plus simple est d'utiliser la commande d'installation intégrée. Elle détecte vos agents installés (Pi, Claude Code, OpenCode) et installe la compétence automatiquement :
# Installation globale (liens symboliques dans les répertoires de configuration des agents)
gcyphrq --install-skill global
# Installation locale (copie dans le répertoire courant)
gcyphrq --install-skill local
La commande --install-skill :
- Détecte quels agents sont installés sur votre système
- Crée des liens symboliques (global) ou copie (local) le contenu de la compétence
- Génère les fichiers de référence
CLAUDE.md/AGENTS.mdpour Claude Code et OpenCode - Est idempotent — peut être exécuté plusieurs fois sans risque
Après l'installation :
- Pi reconnaît la compétence automatiquement. Invoquez-la avec
/skill:gcyphrqou décrivez ce que vous voulez en langage naturel. - Claude Code reconnaît la compétence automatiquement lorsque vous posez des questions liées aux graphes.
- OpenCode charge la compétence lorsque vos invites correspondent à sa description (requêtes de graphe, topologie d'infrastructure, dépendances de services, etc.).
Installation manuelle
Si la commande d'installation ne fonctionne pas pour votre configuration, vous pouvez placer le répertoire de la compétence manuellement :
# 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
Vous pouvez également télécharger le répertoire references/ (contenant queries.md et example-graph.json) dans un sous-répertoire references/ au côté de SKILL.md pour des modèles de requêtes supplémentaires et un graphe de test autonome.
Autres agents
Pour tout agent de codage IA prenant en charge les instructions personnalisées ou les invites système :
- Installez la CLI :
npm install -g gcyphrq - Copiez le SKILL.md depuis
https://raw.githubusercontent.com/plelevier/gcyphrq/main/skills/gcyphrq/SKILL.mddans les instructions personnalisées de votre agent - Copiez les fichiers de référence depuis
https://raw.githubusercontent.com/plelevier/gcyphrq/main/skills/gcyphrq/references/(contenantqueries.mdetexample-graph.json) dans un sous-répertoirereferences/au côté de SKILL.md - Pointez vers vos fichiers de graphe — remplacez
<graph.json>dans les exemples de la compétence par les chemins vers vos fichiers de graphe réels
Prérequis
- CLI gcyphrq installée et dans le PATH — voir Pour commencer pour les instructions d'installation
- Un fichier de graphe JSON à interroger (utilisez
references/example-graph.jsonfourni pour commencer)
Exemples d'invites
Une fois la compétence installée, vous pouvez utiliser des invites en langage naturel. Voici des exemples que la compétence doit résoudre :
Dépendances de services
Invite : "De quels services dépend la passerelle API ?"
La compétence traduit cela en une requête Cypher qui trace les connexions sortantes du nœud de la passerelle API.
Invite : "Montre-moi tous les services connectés à PostgreSQL."
Retourne tous les services avec des connexions TCP à la base de données principale PostgreSQL.
Analyse du rayon de souffle
Invite : "Si Kafka tombe, que se casse ?"
Trace tous les nœuds accessibles depuis le cluster Kafka dans un rayon de 2 sauts pour montrer le rayon d'impact.
Invite : "Quel est le rayon de souffle si la passerelle API tombe ?"
Cartographie tous les services en aval et l'infrastructure affectés par l'indisponibilité de la passerelle API.
Traçage de chemins
Invite : "Montre-moi le chemin du CDN à la base de données."
Trouve le chemin de connexion entre les nœuds CDN et base de données, en montrant les services intermédiaires.
Invite : "Comment une requête circule-t-elle de la passerelle API à la base de données utilisateur ?"
Trace le chemin de la requête à travers l'authentification, les services RPC et les connexions à la base de données.
Topologie d'infrastructure
Invite : "Comment les files d'attente de messages sont-elles connectées ?"
Liste toute l'infrastructure des files d'attente de messages et leurs relations producteur/consommateur.
Invite : "Quelle est la configuration de réplication des bases de données ?"
Montre les relations primaire-réplica et les types d'arêtes de réplication.
Analyse de degré
Invite : "Quel service a le plus de connexions sortantes ?"
Calcule le degré sortant pour tous les services et retourne le plus connecté.
Invite : "Trouve les services avec plus de 2 connexions sortantes."
Filtre les services par seuil de degré sortant en utilisant des agrégations et WHERE.
Couverture de surveillance
Invite : "Quels services sont surveillés ?"
Trouve tous les services connectés à l'infrastructure de surveillance (Prometheus, Grafana, etc.).
Invite : "Quels services n'ont pas de surveillance ?"
Utilise OPTIONAL MATCH pour trouver les services sans connexions de surveillance.
Dépendances externes
Invite : "Quels services appellent des API externes ?"
Trace les services RPC sur 1 à 3 sauts pour trouver les dépendances d'API externes.
Invite : "Liste toutes les intégrations externes."
Retourne tous les nœuds avec l'étiquette Externe et leurs appelants en amont.
Filtrage avancé
Invite : "Montre-moi tous les services RPC ou Worker."
Utilise WHERE avec OR pour correspondre à plusieurs types.
Invite : "Trouve les services qui ne sont pas des jobs batch."
Utilise WHERE avec NOT pour exclure un type.
Invite : "Liste les services dans us-east-1 qui ont 'Service' dans le nom."
Utilise WHERE avec AND pour combiner des conditions.
Pagination
Invite : "Montre-moi la page 2 des services, 10 par page, triés par ordre alphabétique."
Utilise ORDER BY, SKIP et LIMIT pour paginer les résultats des services.
Mutations de graphe
Invite : "Ajoute un nouveau service de surveillance appelé 'Datadog'."
Utilise CREATE pour ajouter un nouveau nœud au graphe.
Invite : "Définis le statut de la passerelle API sur 'obsolète'."
Utilise SET pour mettre à jour une propriété d'un nœud.
Invite : "Supprime l'étiquette 'Personne' d'Alice."
Utilise REMOVE pour retirer une étiquette ou supprimer une propriété d'un nœud tout en conservant le nœud et ses relations.
Référence de la compétence
Le fichier de compétence (SKILL.md) inclut :
- Utilisation de la CLI — syntaxe des commandes, options, entrée via stdin, chaînage de requêtes
- Format du fichier de graphe — structure des nœuds et des arêtes
- Fonctionnalités Cypher prises en charge — matrice complète des fonctionnalités avec statut
- Modèles de requêtes — requêtes pré-construites utilisant
references/example-graph.jsonfourni - Format de sortie — format graphe (par défaut) et format lignes avec exemples de chaînage
- Limitations — contraintes connues (pas de sous-requêtes, pas d'APOC, etc.)
Dépannage
| Problème | Solution |
|---|---|
gcyphrq : commande introuvable | Exécutez npm install -g gcyphrq |
| Compétence non détectée par l'agent | Vérifiez que SKILL.md se trouve dans le répertoire de compétence correct pour votre plateforme |
| La requête retourne des résultats vides | Vérifiez que les étiquettes des nœuds et les noms de propriétés correspondent exactement à votre fichier de graphe |
Prochaines étapes
- [Pour commencer]({{ '/getting-started/' | relative_url }}) — Installez gcyphrq et exécutez votre première requête
- [Guide des requêtes]({{ '/query-guide/' | relative_url }}) — Référence complète de la syntaxe Cypher
- [Exemples]({{ '/examples/' | relative_url }}) — 30 requêtes prêtes à l'emploi avec sortie d'exemple
- [API de la bibliothèque]({{ '/library-api/' | relative_url }}) — Utilisez gcyphrq par programmation en Node.js / TypeScript