使用Claude技能与Neo4j

对克劳德技能及其在Neo4j中潜在应用的实践探索

使用Claude技能与Neo4j

使用 Gemini 生成

Anthropic最近表现不俗，第一推出了MCP标准，目前又推出了新的Skills功能。每次发布都为他们不断壮大的代理工具包增添了一件新的元素，自然地，同样的问题再次出现：何时使用它，它的用途是什么，以及它如何融入当前的代理生态系统？

在这篇文章中，我们将尝试回答这些问题。经过一些初步探索，技能功能对我来说感觉像是用户范围（以及潜在的组织范围）的基于文件的程序性记忆形式，您可以在其中存储指导、最佳实践和使用模式，以指导 LLM 如何与特定工具或任务进行交互。

个人技能是组织指令、脚本和资源的文件夹，克劳德可以动态加载这些内容，以提高其在专门任务上的表现。到目前为止，大多数示例展示了Python代码执行，演示了技能如何在克劳德的环境中直接自动化或扩展工作流程。技能可以存在于不同复杂度的级别，从基于简单指令的工作流到完全具备模块化功能的能力，结合了代码、元数据和资源。在本质上，每个技能都是一个文件夹，打包了指令和可选脚本，允许克劳德动态加载任务的正确上下文。例如，一个基本的技能可能只包括简短描述和基于markdown的指导，而一个更高级的技能可能捆绑了参考文件和可执行脚本，以便在工具或MCP服务器上实现可重复自动化。以下是一个SKILL.md文件的示例。

技能.md

=== 等级 1
—
名称：pdf处理
描述：从PDF文件中提取文本和表格，填写表单，并合并文档。在处理PDF文件或用户提到PDF、表单或文档提取时使用。
—
=== 等级 2

# PDF处理
## 快速开始
使用pdfplumber从PDF中提取文本：
“`python
import pdfplumber
with pdfplumber.open(“document.pdf”) as pdf:
text = pdf.pages[0].extract_text()
“`
=== 等级 3
## 何时加载参考文档
当以下情况发生时加载适当的参考文件：
###
references/pdfplumber-api.md
* 您需要有关提取文本、表格或元数据的所有可用方法的详细信息。
* 您想要使用`extract_text()`、`extract_tables()`或布局分析功能的示例。
* 您正在解决提取结果不一致或边界框坐标的问题。

# PDF处理
## 快速开始
使用pdfplumber从PDF中提取文本：
“`python
import pdfplumber
with pdfplumber.open(“document.pdf”) as pdf:
text = pdf.pages[0].extract_text()
“`
=== 等级 3
## 何时加载参考文档
在以下情况下加载适当的参考文件：
###
references/pdfplumber-api.md
* 您需要有关提取文本、表格或元数据的所有可用方法的详细信息。
* 您想要使用`extract_text()`、`extract_tables()`或布局分析功能的示例。
* 您正在解决提取结果不一致或边界框坐标的问题。

每种技能都有三个级别或类型的内容可以包含。

使用Claude技能与Neo4j

克劳德技能水平及其在主体生态系统中的适应性。由作者创建。

级别1提供了简洁的元数据，LLM始终可以通过发现来获取，协助克劳德知道何时应用技能。级别2增加了程序化指令，仅在相关时加载，为克劳德提供了特定任务的专业知识，而不会不必要地消耗上下文，并且可以作为SKILL.md文件提供。级别3引入了支持资源和可执行脚本，实现确定性操作和更丰富的自动化。它们是SKILL.md文件中提到的附加文件，以便LLM知道何时以及打开哪个文件。总的来说，这种渐进式结构在保持上下文使用高效的同时，在需要时解锁越来越强劲、专业化的行为。

技能.md

虽然大多数示例展示了使用Python代码执行技能，但它们并不局限于Python代码执行。它们还可以定义可重复使用的指令和结构化流程，用于与其他可用工具或MCP服务器一起工作，这使它们成为教导克劳德如何更有效地执行特定工作的灵活方式。

提高对LLMs的Cypher知识

目前我与Neo4j有关联，因此我们将在博客文章中以其为例。大多数LLM仍在使用过时和已弃用的语法，并不熟悉最新的Cypher模式，这常常导致常见错误。在本文中，我们将构建一个Claude技能，提高LLM生成Cypher的能力，无论您是使用MCP Cypher服务器还是Python代码执行，都可以让LLM能够从Neo4j获取信息。

一个很好的事情是你可以使用克劳德来协助你创建一个技能。只需记住这需要大量的令牌，并且我有几次达到了专业版的限制。

使用Claude技能与Neo4j

Claude桌面中的技能创建者功能。作者提供的图片。

我的提示要求模型使用网络搜索了解自Neo4j 5.0以来的语法弃用情况，包括更新的子查询格式，并处理量化路径模式。LLM常常会遇到困难，由于大多数在线可用的Cypher示例是在Neo4j 5.0之前编写的。我还添加了几种用法模式，例如要求模型在排序之前应用过滤器以确保被排序的属性不为空（尽管最新的Claude模型似乎不再有这个问题）。

经过几次迭代，我开发了以下的 Claude 技能。我的想法是只专注于读取查询，所以我故意省略了任何写入或索引语法的更改。

这项技能可在GitHub上找到。

等级1

一级元数据定义了技能的身份和目的，以便克劳德能够识别何时激活它。它提供了技能的高级摘要以及它的作用，使其在处理Cypher生成或Neo4j查询验证的项目中可被发现。通过保持这些信息轻量级且始终加载，克劳德可以快速将涉及Cypher或Neo4j的提示与该技能匹配，而无需第一解析详细的说明。

名称：neo4j-cypher-guide
描述：撰写现代Neo4j Cypher读取查询的综合指南。
对于text2cypher MCP工具和生成Cypher查询的LLMs至关重大。
涵盖了已移除/弃用的语法、现取代代方案、用于读取的CALL子查询、COLLECT模式、排序最佳实践以及用于高效图遍历的Quantified Path Patterns（QPP）。

这在概念上类似于工具描述，由于它告知模型技能的作用是什么，何时使用以及适用于什么类型的任务。主要区别在于技能执行只是打开一个包含程序性记忆的文件，这些记忆是用于使用模式的指令，而不是调用一个工具。不过，您可以实现一个处理记忆的工具（例如，如果您想将这些程序性指令存储在数据库中而不是文件中）。

2级

在第2级，该技能不仅限于简单的能力声明，还包括作为正确执行任务的具体方法的程序知识。当克劳德检测到与技能触发器匹配的用户请求（在第1级中定义），它会动态地从磁盘中读取相应的SKILL.md文件。该文件仅在需要时加载，使上下文保持轻量级同时仍提供详细说明。

技能.md

一个好的SKILL.md文件不仅仅描述技能能做什么，它还展示如何安全正确地执行。一般以简短的程序检查和原则开头，这些原则作为模型的操作规则。这些定义了要避免什么，要偏好什么，以及哪些模式代表了现代最佳实践。以生成现代的Neo4j Cypher查询为例，该技能着重于列出要避免的过时语法，并建立明确的生成规则以强制保持一致性：

技能.md

这项技能有助于使用现代语法模式生成Neo4j Cypher读取查询，避免使用已弃用的功能。它专注于用于图遍历和数据检索的高效查询模式。
## 快速兼容性检查
在生成Cypher查询时，立即避免以下已移除的功能：
– ❌ `id()` 函数 → 使用 `elementId()`
– ❌ 隐式分组键 → 使用显式的 WITH 子句
– ❌ 用于列表的模式表达式 → 使用模式推导或 COLLECT 子查询
– ❌ 重复的关系变量 → 使用唯一的变量名
– ❌ 自动列表到布尔值的强制转换 → 使用显式检查
## 查询生成的核心原则
1. **使用现代语法模式** – 用于复杂遍历的 QPP，用于复杂读取的 CALL 子查询
2. **在遍历过程中优化** – 在模式内部尽早过滤，而不是在扩展后
3. **排序时始终过滤空值** – 为排序属性添加 IS NOT NULL 检查
4. **显式优于隐式** – 始终使用显式分组和类型检查

这项技能有助于使用现代语法模式生成Neo4j Cypher读取查询，并避免使用已弃用的功能。它专注于图遍历和数据检索的高效查询模式。
## 快速兼容性检查
在生成Cypher查询时，立即避免以下已移除的功能：
– ❌ `id()` 函数 → 使用 `elementId()`
– ❌ 隐式分组键 → 使用显式的 WITH 子句
– ❌ 列表的模式表达式 → 使用模式推导或 COLLECT 子查询
– ❌ 重复的关系变量 → 使用唯一的变量名
– ❌ 自动列表到布尔值的强制转换 → 使用显式检查
## 查询生成的核心原则
1. **使用现代语法模式** – 复杂遍历使用 QPP，复杂读取使用 CALL 子查询
2. **在遍历过程中进行优化** – 在模式内部尽早过滤，而不是在扩展后
3. **排序时始终过滤空值** – 对排序属性添加 IS NOT NULL 检查
4. **显式胜于隐式** – 始终使用显式分组和类型检查

最后，SKILL.md 定义了何时引入额外的参考文件。这告知克劳德何时获取更深入的上下文，列如迁移指南、子查询技术或路径优化说明，但仅在任务需要时。

技能.md

何时加载参考文档
在以下情况下加载适当的参考文件：
###
references/deprecated-syntax.md
– 从旧版 Neo4j 迁移查询时
– 遇到旧查询的语法错误时
– 需要完整的已移除/已弃用功能列表时
### references/subqueries.md
– 处理用于读取的 CALL 子查询时
– 使用 COLLECT 或 COUNT 子查询时
– 处理复杂的聚合
– 实现带有空值过滤的排序
### references/qpp.md
– 优化变长路径查询
– 遍历过程中需要早期过滤时
– 处理超过 3-4 跳的路径时
– 复杂的模式匹配要求

何时加载参考文档
在以下情况下加载适当的参考文件：
###
references/deprecated-syntax.md
– 从较早版本的 Neo4j 迁移查询时
– 遇到旧查询的语法错误时
– 需要完整的已移除/已弃用功能列表时
### references/subqueries.md
– 处理用于读取的 CALL 子查询时
– 使用 COLLECT 或 COUNT 子查询时
– 处理复杂的聚合
– 实现带有空值过滤的排序
### references/qpp.md
– 优化变长路径查询
– 遍历过程中需要早期过滤时
– 处理长于 3-4 跳的路径时
– 复杂的模式匹配要求

在定义规则之后，该技能演示了如何通过简短的示例来应用这些规则，展示正确行为的模型。这些片段并非随意选择，而是展示了模型在生成查询时使用的实际程序知识。

### 聚合操作
使用COUNT{}、EXISTS{}和COLLECT{}子查询：
“`cypher
MATCH (p:Person)
WHERE count{(p)-[:KNOWS]->()} > 5
RETURN p.name,
exists{(p)-[:MANAGES]->()} AS isManager
“`
### 复杂读取操作
使用CALL子查询进行复杂数据检索：
“`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
“`
## 常见查询转换
### 统计模式
“`cypher
// 旧写法: RETURN size((n)-[]->())
// 现代写法: RETURN count{(n)-[]->()}
“`
### 检查存在性
“`cypher
// 旧写法: WHERE exists((n)-[:REL]->())
// 现代写法: WHERE EXISTS {MATCH (n)-[:REL]->()}
// 也可以使用: WHERE exists{(n)-[:REL]->()}
“`

简而言之，Level 2 技能在 SKILL.md 中定义了一个清晰的、逐步的过程：它设置了兼容性检查，用示例编码了方法，并指定何时需要额外的上下文。

技能.md

三级

在第3级别，LLM 有能力智能地扩展自己的上下文。克劳德不再仅依赖于 mainSKILL.md，而是可以根据任务需求决定加载哪些支持文件。例如，如果用户提示涉及传统语法，它可以打开
references/deprecated-syntax.md；如果涉及聚合或子查询，它可以引入 references/subqueries.md；对于遍历优化，它可以加载 references/qpp.md。这些文件依旧是静态的 markdown，但克劳德目前有权从中准确组装所需的上下文，而不是依赖于单一入口点。

技能.md

参考/弃用语法.md

引用/子查询.md

参考资料/qpp.md

第3级还可以包括可执行文件。虽然这个技能中没有，但Python脚本可以与markdown引用一起存在，例如，
avalidate_syntax.pyorgenerate_query.pyutility。在这种情况下，克劳德既可以阅读程序指导，又可以调用可执行文件执行具体操作，如验证、转换或快速计算。

验证语法.py

生成查询.py

简而言之，第三级增加了上下文自主性和可选执行。克劳德可以决定加载哪些参考资料以更有效地推理，并且如果可用的话，它可以调用支持的可执行文件来执行该推理。

我打算很快写一篇博客文章，介绍如何添加 Neo4j 技能来执行 Python 代码。

示例用法

我们可以通过连接一个Cypher MCP服务器来测试我们的Cypher技能。我们将使用一个名为companies的演示数据库，其中包含有关组织、人员等信息。您可以使用以下MCP配置进行设置。

公司

{
“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”
}
}
}
}

让我们举个例子问题！

使用Claude技能与Neo4j

作者提供的图片。

在这个例子中，模型第一确定需要检索图模式。为了遵循最佳实践，然后加载了Neo4j指南技能，然后生成Cypher查询。我们可以看到它使用了QPP模式，这是复杂遍历的推荐方法。不过，使用这些技能的所有好处都伴随着成本和延迟的增加。

我们也可以不使用技能来测试它，看看有什么不同。

使用Claude技能与Neo4j

作者提供的图片。

没有这个技能，LLM 直接生成了 Cypher 并使用了旧的复杂遍历语法，这可能会慢上1000倍。

摘要

技能感觉就像在代理生态系统中朝着标准化和可重复使用性的更广泛移动中的自然下一步。它们本质上是模块化的、基于文件的程序性记忆构建块，是一种教导模型如何更一致地工作的方式，提供清晰、可重复使用的指导，可以跨项目或团队共享。在Neo4j的背景下，这意味着我们终于可以为现代Cypher语法和最佳实践给LLMs提供可靠的参考，而不是希望他们回忆过时来源中的零散示例。

同时，技能仍处于早期阶段。它们增加了另一层复杂性和一点延迟，由于每一步都涉及获取、加载和解释额外的文件。在某种意义上，它们只是工具的一种变体，一种结构化的存储和重复使用指令的方式，而不是直接执行代码。看到系统提示中应该包含什么内容以及什么内容应该存在于技能内部的边界如何发展将是很有趣的。

无论如何，这都是朝着正确方向迈出的坚实一步。它推动生态系统朝着更模块化、可解释和可重复使用的代理行为发展。就像这个快速发展的领域中的一切一样，它依旧是新的，所以目前我们只能等待看看会发生什么。