使用-Claude-技能与-Neo4j
使用 Claude 技能与 Neo4j
在这篇文章中，我们将尝试回答这些问题。经过一些初步探索后，我认为 Skills 功能就像是一种用户级（甚至可能是组织级）的基于文件的程序性记忆形式，其中你存储指令、最佳实践和 LLM 与特定工具或任务交互的使用模式。
单个技能是有组织的文件夹，包含指令、脚本和资源，Claude 可以动态加载以改进其在特定任务上的性能。迄今为止的大多数示例都展示了 Python 代码执行，展示了 Skills 如何直接在 Claude 的环境中自动化或扩展工作流程。Skills 可以存在于不同复杂性的级别，从基于指令的工作流程到功能齐全的模块化能力，这些能力结合了代码、元数据和资源。在核心上，每个 Skill 都是一个包含指令和可选脚本的文件夹，允许 Claude 动态加载任务的正确上下文。例如，一个基本的 Skill 可能只包括简短描述和基于 Markdown 的指导，而一个更高级的 Skill 可能捆绑参考文件和可重复自动化工具或 MCP 服务器的可执行脚本。以下是一个SKILL.md文件的示例。
=== 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()
```py
=== 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.
每个技能可以包含三种级别或类型的内容。
Claude 技能的级别及其在代理生态系统中的位置。由作者创建。
一级提供简洁的元数据，这些元数据始终可供 LLM 发现，帮助 Claude 知道何时一个技能适用。二级添加仅在相关时加载的程序指令，为 Claude 提供特定任务的知识，而不会不必要地消耗上下文，并且作为SKILL.md文件提供。三级引入支持资源和可执行脚本，实现确定性操作和更丰富的自动化。它们是SKILL.md文件中提到的附加文件，以便 LLM 知道何时打开哪个文件。这种渐进式结构在保持上下文使用效率的同时，根据需要解锁越来越强大、专业的行为。
虽然大多数示例展示了使用 Python 代码执行技能，但它们并不仅限于 Python 代码执行。它们还可以定义可重用的指令和结构化流程，用于与其他可用的工具或 MCP 服务器一起工作，使它们成为教授 Claude 如何更有效地执行特定工作的灵活方式。
提高 LLM 的 Cypher 知识
目前我隶属于 Neo4j，因此我们将将其作为我们博客文章的示例。大多数 LLM 仍然使用过时和弃用的语法，并且不熟悉最新的 Cypher 模式，这通常会导致常见错误。在这篇文章中，我们将构建一个 Claude 技能，以提高 LLM 生成 Cypher 的能力，无论你使用 MCP Cypher 服务器 还是 Python 代码执行，以使 LLM 能够从 Neo4j 获取信息。
一件好事是你可以使用 Claude 来帮助你创建技能。但请记住，它非常消耗令牌，我几次达到了专业版限制。
Claude 桌面中的技能创建者功能。图片由作者提供。
我的提示指令模型使用网络搜索来了解自 Neo4j 5.0 以来语法弃用的情况，包括更新的子查询格式，并处理量化路径模式。LLMs 通常会在这点上遇到困难，因为大多数在线可用的 Cypher 示例都是在 Neo4j 5.0 之前编写的。我还添加了几个使用模式，例如要求模型在排序前应用过滤器以确保排序的属性不为空（尽管看起来最新的 Claude 模型已经不再有这个问题了）。
经过几次迭代后，我开发了以下 Claude 技能。想法是只关注读取查询，所以我故意省略了任何写入或索引语法的更改。
该技能可在 GitHub 上找到。
第 1 级
第 1 级元数据定义了技能的身份和目的，以便 Claude 能够识别何时激活它。它提供了技能做什么以及为什么有用的概述，使其在处理 Cypher 生成或 Neo4j 查询验证的项目中可被发现。通过保持这些信息轻量级且始终加载，Claude 可以快速匹配涉及 Cypher 或 Neo4j 的提示，而无需首先解析详细说明。
---
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.
---
它在概念上类似于工具描述，因为它告诉模型技能的功能、何时使用它以及它相关的任务类型。主要区别在于技能执行只是简单地打开包含程序性记忆的文件，这些是使用模式的指令，而不是调用工具。然而，你可以实现这样的工具，该工具也处理记忆（例如，如果你想在数据库而不是文件中存储这样的程序性指令）。
第 2 级
在第 2 级别，技能超越了简单的功能声明，并包括过程性知识作为执行任务正确的具体方法。当 Claude 检测到与技能触发器（在第 1 级别定义）匹配的用户请求时，它会动态地从磁盘读取相应的 SKILL.md 文件。文件仅在需要时加载，保持上下文轻量级，同时仍然提供详细的说明。
一个好的 SKILL.md 文件不仅仅描述了技能可以做什么——它展示了如何安全且正确地执行它。它通常从简短的过程性检查和原则开始，这些原则作为模型的操作规则。这些规则定义了要避免什么，要优先考虑什么，以及哪些模式代表了现代最佳实践。在这个例子中，技能专注于生成现代 Neo4j Cypher 查询。它首先列出要避免的过时语法，并建立明确的生成规则，以确保一致性：
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
最后，SKILL.md 定义了何时引入额外的参考文件。这告诉 Claude 何时获取更深入上下文，例如迁移指南、子查询技术或路径优化说明，但仅当任务需要时。
## 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
在定义了其规则之后，技能通过模拟正确行为的简短示例来展示如何应用这些规则。这些片段并非随意选择，而是展示了模型在生成查询时实际使用的过程性知识。
### 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
```py
### 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 // 过滤空值
WITH p ORDER BY p.salary DESC
LIMIT 3
RETURN collect(p.name) AS topEarners
}
RETURN d.name, topEarners
```py
## Common Query Transformations
### Counting Patterns
```cypher
// 旧：RETURN size((n)-[]->())
// 现代：RETURN count{(n)-[]->()}
```py
### Checking Existence
```cypher
// 旧：WHERE exists((n)-[:REL]->())
// 现代：WHERE EXISTS {MATCH (n)-[:REL]->()}
// 也有效：WHERE exists{(n)-[:REL]->()}
```py
简而言之，第 2 级别的技能在 SKILL.md 中定义了一个清晰、逐步的过程：它设置兼容性检查，用示例编码方法，并指定何时需要额外的上下文。
第 3 级
在第 3 级别，LLM 有能力智能地扩展其上下文。Claude 不再仅依赖于主要的 SKILL.md，可以根据任务需求决定加载哪些支持文件。例如，如果用户提示涉及旧语法，它可以打开 references/deprecated-syntax.md；如果是关于聚合或子查询，它可以引入 references/subqueries.md；对于遍历优化，它可以加载 references/qpp.md。这些文件仍然是静态的 markdown，但 Claude 现在有了自主权，可以从它们中组装出所需的确切上下文，而不是依赖于单一入口点。
第三级也可以包括可执行文件。虽然在这个技能中不存在，但 Python 脚本可以与 markdown 引用一起存在，例如，一个validate_syntax.py或generate_query.py实用程序。在这种情况下，Claude 可以读取过程性指导并调用可执行文件来执行具体的操作，如验证、转换或快速计算。
简而言之，第三级增加了上下文自主性和可选执行。Claude 可以决定加载哪些参考材料以更有效地推理，如果可用，它还可以调用支持的可执行文件来对推理采取行动。
P.s. 我计划很快写一篇关于如何为 Python 代码执行添加 Neo4j 技能的博客文章。
示例用法
我们可以通过附加 Cypher MCP 服务器来测试我们的 Cypher 技能。我们将使用一个名为companies的演示数据库，其中包含有关组织、人员等信息。你可以使用以下 MCP 配置来设置它。
{
"mcpServers": {
"neo4j-database": {
"command": "uvx",
"args": [ "[[email protected]](/cdn-cgi/l/email-protection)", "--transport", "stdio" ],
"env": {
"NEO4J_URI": "neo4j+s://demo.neo4jlabs.com",
"NEO4J_USERNAME": "companies",
"NEO4J_PASSWORD": "companies",
"NEO4J_DATABASE": "companies"
}
}
}
}
让我们给出一个示例问题！
图片由作者提供。
在这个例子中，模型首先确定它需要检索图模式。为了遵循最佳实践，它随后加载了 Neo4j 指南技能，然后生成 Cypher 查询。我们可以看到它使用了 QPP 模式，这是复杂遍历的推荐方法。然而，使用技能的所有这些好处都伴随着成本和延迟的增加。
我们也可以在没有技能的情况下测试它，看看差异。
图片由作者提供。
没有技能的情况下，LLM 直接生成了 Cypher 并使用了旧的语法进行复杂遍历，这可能会慢 1000 倍。
摘要
技能感觉像是向标准化和可重用性迈出的自然下一步，在更广泛的代理生态系统内。它们本质上是由文件组成的模块化构建块，用于程序性记忆，这是一种教会模型如何通过清晰、可重用的指导与项目或团队共享来更一致地工作的方式。在 Neo4j 的背景下，这意味着我们最终可以给 LLM 提供一个可靠的现代 Cypher 语法和最佳实践的参考，而不是希望他们从过时的来源回忆起零散的例子。
同时，技能还处于早期阶段。它们增加了另一层复杂性以及一些延迟，因为每个步骤都涉及到检索、加载和解释额外的文件。从某种意义上说，它们只是工具的一种变体，是一种结构化的方式来存储和重用指令，而不是直接执行代码。将很有趣地看到系统提示和技能内部应该包含的内容之间的边界是如何演变的。
无论哪种方式，这都是朝着正确方向迈出的坚实一步。它推动生态系统向更模块化、可解释和可重用的代理行为发展。正如在这个快速发展的空间中的所有事物一样，它仍然很新，所以现在我们只能看看最终结果会怎样。
Cypher 技能可在GitHub上找到。
浙公网安备 33010602011771号