Utiliser les compétences de Claude avec Neo4j | Vers la science des données

a été sur une lancée ces derniers temps avec d’abord l’introduction de la norme MCP, et maintenant le lancement du nouveau Fonctionnalité de compétences. Chaque version ajoute un élément supplémentaire à leur boîte à outils agentique croissante, et naturellement, les mêmes questions reviennent : quand devriez-vous l’utiliser, à quoi sert-il et comment s’intègre-t-il dans l’écosystème agentique actuel ?

Dans cet article, nous essaierons de répondre à ces questions. Après une exploration initiale, la fonctionnalité Compétences me semble être une forme de mémoire procédurale basée sur des fichiers à l’échelle de l’utilisateur (et potentiellement de l’organisation), dans laquelle vous stockez les instructions, les meilleures pratiques et les modèles d’utilisation sur la façon dont le LLM doit interagir avec des outils ou des tâches spécifiques.

Les compétences individuelles sont des dossiers organisés contenant des instructions, des scripts et des ressources que Claude peut charger dynamiquement pour améliorer ses performances sur des tâches spécialisées. Jusqu’à présent, la plupart des exemples présentent l’exécution de code Python, démontrant comment Skills peut automatiser ou étendre les flux de travail directement dans l’environnement de Claude. Les compétences peuvent exister à différents niveaux de complexité, allant de simples flux de travail basés sur des instructions à des fonctionnalités modulaires complètes combinant code, métadonnées et ressources. À la base, chaque compétence est un dossier qui regroupe des instructions et des scripts facultatifs, permettant à Claude de charger dynamiquement le bon contexte pour une tâche. Par exemple, une compétence de base peut inclure uniquement une brève description et des conseils basés sur les démarques, tandis qu’une compétence plus avancée peut regrouper des fichiers de référence et des scripts exécutables pour une automatisation reproductible entre les outils ou les serveurs MCP. Voici un exemple de SKILL.md déposer.

=== Level 1
---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, and merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

=== Level 2
 
# PDF Processing

## Quick start
Use pdfplumber to extract text from PDFs:

```python
import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

=== Level 3

## When to Load Reference Documentation

Load the appropriate reference file when:

### references/pdfplumber-api.md

* You need details on all available methods for extracting text, tables, or metadata.
* You want examples of using `extract_text()`, `extract_tables()`, or layout analysis features.
* You're troubleshooting inconsistent extraction results or bounding box coordinates.

Chaque compétence possède trois niveaux ou types de contenu qu’elle peut contenir.

Niveau 1 fournit des métadonnées concises qui sont toujours disponibles au LLM pour la découverte, aidant Claude à savoir quand une compétence s’applique. Niveau 2 ajoute des instructions procédurales qui se chargent uniquement lorsque cela est pertinent, donnant à Claude un savoir-faire spécifique à une tâche sans consommer inutilement de contexte et est disponible en tant que SKILL.md déposer. Niveau 3 introduit des ressources de support et des scripts exécutables, permettant des opérations déterministes et une automatisation plus riche. Ce sont des fichiers supplémentaires mentionnés dans le SKILL.mdfichier afin que le LLM sache quel fichier ouvrir et quand. Ensemble, cette structure progressive maintient une utilisation efficace du contexte tout en débloquant des comportements spécialisés de plus en plus puissants selon les besoins.

Bien que la plupart des exemples présentent des compétences en matière d’exécution de code Python, ils ne se limitent pas à l’exécution de code Python. Ils peuvent également définir des instructions réutilisables et des processus structurés pour travailler avec d’autres outils disponibles ou serveurs MCP, ce qui en fait un moyen flexible d’apprendre à Claude comment effectuer un travail spécifique plus efficacement.

Améliorer la connaissance Cypher des LLM

Pour le moment, je suis affilié à Neo4j et nous l’utiliserons donc comme exemple dans notre article de blog. La plupart des LLM utilisent encore une syntaxe obsolète et obsolète et ne sont pas familiers avec les derniers modèles de chiffrement, ce qui entraîne souvent des erreurs courantes. Dans cet article, nous allons créer une compétence Claude qui améliore la capacité d’un LLM à générer du Cypher, que vous utilisiez Serveur de chiffrement MCP ou l’exécution de code Python pour donner au LLM la possibilité de récupérer des informations depuis Neo4j.

Une bonne chose est que vous pouvez utiliser Claude pour vous aider à créer une compétence. Gardez simplement à l’esprit que cela nécessite beaucoup de jetons et que j’ai atteint les limites de la version Pro à plusieurs reprises.

Mon invite a demandé au modèle d’utiliser la recherche sur le Web pour en savoir plus sur la dépréciation de la syntaxe depuis Neo4j 5.0, d’inclure le format de sous-requête mis à jour et de gérer les modèles de chemin quantifiés. Les LLM ont souvent du mal à résoudre ce problème car la plupart des exemples Cypher disponibles en ligne ont été écrits avant Neo4j 5.0. J’ai également ajouté plusieurs modèles d’utilisation, comme exiger que le modèle applique un filtre avant le tri pour garantir que la propriété en cours de tri n’est pas nulle (bien qu’il semble que les derniers modèles Claude n’aient plus ce problème).

Après quelques itérations, j’ai développé la compétence Claude suivante. L’idée était de se concentrer uniquement sur les requêtes de lecture, j’ai donc intentionnellement laissé de côté toute modification de syntaxe d’écriture ou d’index.

La compétence est disponible sur GitHub.

Niveau 1

Les métadonnées de niveau 1 définissent l’identité et le but de la compétence afin que Claude puisse reconnaître quand l’activer. Il fournit un résumé de haut niveau de ce que fait la compétence et pourquoi elle est utile, la rendant visible dans les projets traitant de la génération Cypher ou de la validation des requêtes Neo4j. En gardant ces informations légères et toujours chargées, Claude peut rapidement faire correspondre les invites impliquant Cypher ou Neo4j à cette compétence sans avoir besoin d’analyser au préalable des instructions détaillées.

---
name: neo4j-cypher-guide
description: Comprehensive guide for writing modern Neo4j Cypher read queries.
Essential for text2cypher MCP tools and LLMs generating Cypher queries.
Covers removed/deprecated syntax, modern replacements, CALL subqueries for reads, COLLECT patterns, sorting best practices, and Quantified Path Patterns (QPP) for efficient graph traversal.
---

Son concept est similaire à la description d’un outil, car il indique au modèle ce que fait la compétence, quand l’utiliser et pour quels types de tâches elle est pertinente. La principale différence est que l’exécution des compétences ouvre simplement un fichier contenant de la mémoire procédurale, qui sont des instructions pour les modèles d’utilisation, au lieu d’appeler un outil. Cependant, vous pouvez implémenter un tel outil qui gère également la mémoire (par exemple, si vous souhaitez stocker de telles instructions procédurales dans une base de données au lieu d’un fichier).

Niveau 2

Au niveau 2, la compétence va au-delà d’une simple déclaration de capacité et inclut les connaissances procédurales comme méthodes concrètes pour effectuer correctement une tâche. Lorsque Claude détecte une requête utilisateur correspondant au déclencheur d’une compétence (définie au niveau 1), il lit dynamiquement le SKILL.md fichier à partir du disque. Le fichier est chargé uniquement lorsque cela est nécessaire, ce qui permet de conserver un contexte léger tout en fournissant des instructions détaillées.

Un bon SKILL.md le fichier ne se contente pas de décrire quoi la compétence peut faire – ça se voit comment pour le faire correctement et en toute sécurité. Cela commence généralement par de courtes vérifications procédurales et des principes qui servent de règles de fonctionnement du modèle. Ceux-ci définissent ce qu’il faut éviter, ce qu’il faut préférer et quels modèles représentent les meilleures pratiques modernes. Pour cet exemple, la compétence se concentre sur la génération de requêtes Neo4j Cypher modernes. Il commence par lister les syntaxes obsolètes à éviter et par établir des règles de génération claires qui assurent la cohérence :

This skill helps generate Neo4j Cypher read queries using modern syntax patterns and avoiding deprecated features. It focuses on efficient query patterns for graph traversal and data retrieval.

## Quick Compatibility Check

When generating Cypher queries, immediately avoid these REMOVED features:
- ❌ `id()` function → Use `elementId()`
- ❌ Implicit grouping keys → Use explicit WITH clauses
- ❌ Pattern expressions for lists → Use pattern comprehension or COLLECT subqueries
- ❌ Repeated relationship variables → Use unique variable names
- ❌ Automatic list to boolean coercion → Use explicit checks

## Core Principles for Query Generation

1. **Use modern syntax patterns** - QPP for complex traversals, CALL subqueries for complex reads
2. **Optimize during traversal** - Filter early within patterns, not after expansion
3. **Always filter nulls when sorting** - Add IS NOT NULL checks for sorted properties
4. **Explicit is better than implicit** - Always use explicit grouping and type checking

Enfin, le SKILL.md définit quand extraire des fichiers de référence supplémentaires. Cela indique à Claude quand récupérer un contexte plus approfondi, tel que des guides de migration, des techniques de sous-requête ou des notes d’optimisation de chemin, mais uniquement si la tâche l’exige.

## When to Load Reference Documentation

Load the appropriate reference file when:

### references/deprecated-syntax.md
- Migrating queries from older Neo4j versions
- Encountering syntax errors with legacy queries
- Need complete list of removed/deprecated features

### references/subqueries.md
- Working with CALL subqueries for reads
- Using COLLECT or COUNT subqueries
- Handling complex aggregations
- Implementing sorting with null filtering

### references/qpp.md
- Optimizing variable-length path queries
- Need early filtering during traversal
- Working with paths longer than 3-4 hops
- Complex pattern matching requirements

Après avoir défini ses règles, la compétence montre comment les appliquer à travers de courts exemples qui modélisent un comportement correct. Ces extraits ne sont pas arbitraires, mais ils montrent les connaissances procédurales réelles utilisées par le modèle lors de la génération de requêtes.

### For Aggregations
Use COUNT{}, EXISTS{}, and COLLECT{} subqueries:
```cypher
MATCH (p:Person)
WHERE count{(p)-[:KNOWS]->()} > 5
RETURN p.name,
exists{(p)-[:MANAGES]->()} AS isManager
```

### For Complex Read Operations
Use CALL subqueries for sophisticated data retrieval:
```cypher
MATCH (d:Department)
CALL (d) {
MATCH (d)<-[:WORKS_IN]-(p:Person)
WHERE p.salary IS NOT NULL // Filter nulls
WITH p ORDER BY p.salary DESC
LIMIT 3
RETURN collect(p.name) AS topEarners
}
RETURN d.name, topEarners
```

## Common Query Transformations

### Counting Patterns
```cypher
// Old: RETURN size((n)-[]->())
// Modern: RETURN count{(n)-[]->()}
```

### Checking Existence
```cypher
// Old: WHERE exists((n)-[:REL]->())
// Modern: WHERE EXISTS {MATCH (n)-[:REL]->()}
// Also valid: WHERE exists{(n)-[:REL]->()}
```

En bref, une compétence de niveau 2 définit une procédure claire, étape par étape, à l’intérieur SKILL.md: il définit des contrôles de compatibilité, code la méthode avec des exemples et spécifie quand accéder à un contexte supplémentaire.

Niveau 3

Au niveau 3, le LLM a la capacité d’élargir intelligemment son propre contexte. Au lieu de compter uniquement sur le principal SKILL.mdClaude peut décider quels fichiers de support charger en fonction des besoins de la tâche. Par exemple, si une invite utilisateur implique une syntaxe héritée, elle peut ouvrir references/deprecated-syntax.md; s’il s’agit d’agrégations ou de sous-requêtes, cela peut apporter references/subqueries.md; et pour les optimisations de traversée, il peut charger references/qpp.md. Ces fichiers restent statiques, mais Claude a désormais l’autonomie d’assembler exactement le contexte dont il a besoin plutôt que de dépendre d’un seul point d’entrée.

Le niveau 3 peut également inclure des fichiers exécutables. Bien qu’ils ne soient pas présents dans cette compétence, les scripts Python pourraient cohabiter avec les références de démarque, par exemple, un validate_syntax.py ou generate_query.py utilitaire. Dans ce cas, Claude pourrait à la fois lire des instructions procédurales et appeler l’exécutable pour effectuer des opérations concrètes telles que la validation, la transformation ou le calcul rapide.

En bref, le niveau 3 ajoute une autonomie contextuelle et une exécution facultative. Claude peut décider quels documents de référence charger pour raisonner plus efficacement et, s’ils sont disponibles, il peut invoquer des exécutables de support pour agir sur ce raisonnement.

Ps, je prévois d’écrire bientôt un article de blog sur la façon d’ajouter une compétence Neo4j pour l’exécution de code Python..

Exemple d’utilisation

Nous pouvons tester nos compétences Cypher en connectant un serveur Cypher MCP. Nous utiliserons une base de données de démonstration nommée companies qui contient des informations sur les organisations, les personnes, etc. Vous pouvez le configurer avec la configuration MCP suivante.

{
  "mcpServers": {
    "neo4j-database": {
      "command": "uvx",
      "args": [ "[email protected]", "--transport", "stdio" ],
      "env": {
        "NEO4J_URI": "neo4j+s://demo.neo4jlabs.com",
        "NEO4J_USERNAME": "companies",
        "NEO4J_PASSWORD": "companies",
        "NEO4J_DATABASE": "companies"
      }
    }
  }
}

Donnons-lui un exemple de question !

Dans cet exemple, le modèle a d’abord déterminé qu’il devait récupérer le schéma graphique. Pour suivre les bonnes pratiques, il a ensuite chargé la compétence du guide Neo4j avant de générer la requête Cypher. Nous pouvons voir qu’il a utilisé le modèle QPP, l’approche recommandée pour les traversées complexes. Cependant, tous ces avantages liés à l’utilisation des compétences ont un coût et une latence accrus.

Nous pouvons également le tester sans compétence pour voir la différence.

Sans cette compétence, le LLM a directement généré le Cypher et utilisé l’ancienne syntaxe pour les traversées complexes, qui peuvent être jusqu’à 1 000 fois plus lentes.

Résumé

Les compétences semblent être la prochaine étape naturelle dans l’évolution plus large vers la standardisation et la réutilisabilité au sein de l’écosystème agent. Il s’agit essentiellement d’éléments de base modulaires, basés sur des fichiers, pour la mémoire procédurale, un moyen d’enseigner aux modèles comment travailler de manière plus cohérente avec des conseils clairs et réutilisables qui peuvent être partagés entre les projets ou les équipes. Dans le contexte Neo4j, cela signifie que nous pouvons enfin donner aux LLM une référence fiable pour la syntaxe Cypher moderne et les meilleures pratiques, au lieu d’espérer qu’ils rappellent des exemples dispersés provenant de sources obsolètes.

Dans le même temps, les compétences sont encore précoces. Ils ajoutent une autre couche de complexité et un peu de latence, puisque chaque étape implique la récupération, le chargement et l’interprétation de fichiers supplémentaires. En un sens, ils ne sont qu’une variante d’outils, une manière structurée de stocker et de réutiliser des instructions plutôt que d’exécuter du code directement. Il sera intéressant de voir comment la frontière évolue entre ce qui appartient à l’invite système et ce qui devrait vivre dans une compétence.

Quoi qu’il en soit, c’est un pas dans la bonne direction. Cela pousse l’écosystème vers un comportement d’agent plus modulaire, interprétable et réutilisable. Comme pour tout dans cet espace en évolution rapide, c’est encore nouveau, donc pour l’instant nous n’aurons qu’à voir ce qui se passe.

La compétence Cypher est disponible sur GitHub.