1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | neo4j-cypher-skill（neo4j-contrib/neo4j-skills 合集仓库子技能） |
| 作者/维护者 | Neo4j（官方 Developer Relations 团队，联系邮箱 devrel@neo4j.com） |
| 来源链接 | https://github.com/neo4j-contrib/neo4j-skills/tree/main/neo4j-cypher-skill |
| 许可证 | MIT（GitHub API 获取） |
| GitHub Stars | 98（GitHub API 获取；此为合集仓库整体数字，不代表本技能自身热度，详见第6章说明） |
| Forks | 35（GitHub API 获取） |
| 最新版本 | 1.0.1（SKILL.md 内声明） |
| 安装方式 | npx skills add，或 Claude Code / Codex / Gemini CLI / Antigravity CLI 各自的插件命令（详见第10章） |
2. 功能介绍与亮点
neo4j-cypher-skill 是官方 Neo4j 出品的 Cypher 查询生成、优化与校验指南，覆盖 Neo4j 2025.x/2026.x 与 Cypher 25 语法：
- Schema 优先协议：优先读取项目内
<db-name>-schema.json；不存在时才对活数据库做 schema 内省，并配套三个本地 Python 脚本（手动定义、从活库生成、从第三方格式转换导入 schema），避免 agent 盲猜字段名。 - 十条硬性默认规则：如
CYPHER 25须为查询首个 token、MERGE只作用于有约束的 key、探索性查询默认加LIMIT、区分整体替换SET n = {}与安全合并SET n += {}等，提前消灭常见错误。 - 执行前写操作门禁：明确区分“生成查询”与“执行查询”，真正下发写操作前要求先
EXPLAIN校验并经确认，而非静默改库。 - 配套 8 篇参考手册：进阶模式、APOC、完整语法、索引、性能调优、Schema Guardrail、语法陷阱、GRAPH TYPE 预览，深度远超一般 SKILL.md。
- 职责边界清晰：明确声明不处理驱动迁移、数据库管理、GraphQL 类型定义，遇到这些场景会指向同仓库其他专门技能。
- 持续自动同步：由 GitHub Actions 按 Neo4j 官方发行说明定期刷新，新语法发布后很快被吸收进指南。
3. 适用场景
固定分类：数据分析与可视化。适合使用 Claude Code、Codex 等编程助手开发 Neo4j 图数据库应用的开发者与数据分析师，尤其是刚接触 Cypher、容易在 WITH 变量作用域、无向边匹配、DETACH DELETE 等细节上踩坑的初中级用户；典型场景包括编写新查询、优化慢查询、设计向量/全文搜索语句、批量写入（LOAD CSV）与调试既有查询。
4. 跨 Agent 兼容性
- Claude Code：原生支持。README 给出完整的
/plugin marketplace add+/plugin install安装步骤。 - Codex：原生支持。README 给出对应的
codex plugin marketplace add+codex plugin add安装步骤。 - OpenClaw：未验证——已抓取材料未提及。
- Hermes Agent：未验证——已抓取材料未提及。
（另注：该合集同时原生支持 Gemini CLI 与 Antigravity CLI，但两者不属于本报告评估的四个目标生态。）
5. 推荐理由
官方 Neo4j Developer Relations 团队维护，内容随 Neo4j 版本发布持续自动刷新；第三方技能安装统计平台 skills.sh 显示，该技能在同仓库 29 个技能中安装量位居第一；Schema 优先协议与写操作确认门禁体现出扎实的工程设计，能显著降低 agent 生成 Cypher 时的常见错误率。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | 官方 Neo4j 出品，所属 GitHub 组织 neo4j-contrib 经平台认证（verified）；第三方技能安装统计平台 skills.sh 显示该技能在同仓库 29 个技能中安装量最高（约 786 次，合集总安装约 9.2K 次）；尚无独立第三方评测文章 |
| 可用性 | 8 | 主文档 400 行 + 8 篇参考手册，内容详尽含大量可执行示例；子目录本身近 3 周内仍有功能性提交，仓库层面几乎每日有自动化维护提交；需自备可连接的 Neo4j 实例（有免费 Aura 层可用）才能实际执行查询，纯生成/校验场景无需配置 |
| 安全性 | 9 | 见下方检查清单 |
安全检查清单：
① 权限范围：三个本地 Python 脚本仅读写 schema JSON，不涉及 shell/系统命令；技能会指导 agent 向用户自配的 Neo4j 实例发送含写操作的 Cypher，但要求执行前先 EXPLAIN 并经确认。
② 运行时联网：仅连接用户自配的 Neo4j 实例（Aura 云或本地 Docker），无第三方数据外发。
③ 凭据处理：需配置 NEO4J_URI/NEO4J_USERNAME/NEO4J_PASSWORD/NEO4J_DATABASE，密码字段标记为 sensitive，经宿主 agent 标准插件配置机制存储，不写入明文文件。
④ 可疑指令：已抓取的 SKILL.md、README 与全部脚本代码中未发现 prompt injection 或隐蔽外发指令。
⑤ 作者信誉：neo4j-contrib 为 GitHub 认证组织，清单文件 owner 字段为官方邮箱 devrel@neo4j.com，核心贡献者为可查证的 Neo4j Developer Relations 团队成员。
⑥ License：MIT，仓库根目录 LICENSE 文件明确。
⑦ 维护时间：仓库整体持续活跃，该子技能最近一次功能性提交距今约 3 周。
综合：无恶意迹象、权限用途可解释、License 与凭据处理方式均明确、用途不在排除域——判 9 分。
7. 跟同类 Skills 相比的优势
| 项目 | 定位 | 差异化 |
|---|---|---|
| neo4j-cypher-skill（本技能） | 直接加载进编程助手的 Cypher 生成/优化/校验知识型指南 | 无需额外部署应用或服务，agent 在对话中即可按规范写出并校验 Cypher，附带写操作确认门禁 |
| LangChain GraphCypherQAChain（Text2Cypher） | Python 库级组件，用于在自建问答应用中把自然语言问题转成 Cypher 并执行 | 面向“构建终端用户问答应用”的开发者，需要编写 Python 胶水代码组装 Chain，不是可直接装进编程助手的能力包 |
| Neo4j 官方 / Labs MCP Server | 以 MCP 协议暴露 Cypher 执行、schema 查询等工具，agent 通过工具调用与数据库交互 | 需要额外部署并连接一个 MCP server 进程才能使用；本技能不依赖 MCP，靠内嵌的语法规范与协议即可工作 |
8. 用户评价
该技能目前在第三方平台尚无具名用户评价；第三方技能安装统计平台 skills.sh 显示，截至查证时该技能是同仓库 29 个技能中安装量最高的一个。
9. 其他补充
SKILL.md 正文为英文撰写；所属合集除 Claude Code、Codex 外，还同时适配 Gemini CLI 与 Antigravity CLI。当前版本 1.0.1，仓库通过自动化流程持续对照 Neo4j 官方发行说明更新语法覆盖范围。
10. 安装使用方式
Claude Code：
/plugin marketplace add https://github.com/neo4j-contrib/neo4j-skills.git
/plugin install neo4j-skills@neo4j-skills-marketplace用 /plugin list 确认，或运行 /reload-plugins 使其生效。
Codex：
codex plugin marketplace add neo4j-contrib/neo4j-skills
codex plugin add neo4j-skills@neo4j-skills-marketplace安装后需开启新会话让 Codex 重新加载插件。
只装这一个技能（不装同仓库其余 28 个）：
npx skills add https://github.com/neo4j-contrib/neo4j-skills --skill neo4j-cypher-skill安装完成后，需在环境变量或安装向导中提供 NEO4J_URI/NEO4J_USERNAME/NEO4J_PASSWORD/NEO4J_DATABASE 才能让 agent 实际执行查询；未配置连接信息时仍可用于生成与校验 Cypher 查询文本。
11. 注意事项
- 通过 Claude Code / Codex 官方插件市场安装会连带装入同仓库全部 29 个子技能；只需要 Cypher 能力时建议改用上方
--skill参数精确安装。 - 需自备可连接的 Neo4j 实例（Aura 云或本地 Docker）才能实际执行查询，技能本身不提供数据库。
- 在 OpenClaw、Hermes Agent 上的兼容情况尚未验证，安装前建议自行确认。
- 该合集内另有 5 个姊妹子技能被 GitHub issue 记录存在 YAML frontmatter 格式问题（经核实不含本技能），提示合集整体仍在快速迭代中，个别文件质量可能不一致。