neo4j-getting-started-skill

Neo4j 入门技能

按顺序执行以下 8 个阶段，引导用户或 Agent从零开始构建可运行的 Neo4j 应用。

每个阶段开始时：阅读对应的 ${CLAUDE_SKILL_DIR}/references/<stage-name>.md 文件，并遵循其中的说明。只加载当前正在执行的阶段，不要一次性加载所有阶段。

“用户”既指人类开发者，也指自主编码 Agent。

---

适用场景

• 从零开始创建 Neo4j 项目（本地/Docker/Aura）
• 完整上手流程：从零开始 → 数据库 → 模型 → 加载 → 应用
• 为演示或开发生成合成数据

不适用场景

• 在现有项目中编写 Cypher → neo4j-cypher-skill
• 驱动升级/Cypher 迁移 → neo4j-migration-skill
• 管理现有数据库（备份、恢复、导入）→ neo4j-cli-tools-skill

---

项目结构

所有生成的代码、数据、脚本、查询和笔记本都必须写入工作目录，以便用户在会话结束后检查、复用和重新运行。绝不要只在对话中以文本形式生成输出——始终将其写入文件。

按以下布局组织文件。写入文件前先创建子目录。

.env                    ← DB credentials (gitignored, loaded by python-dotenv)
aura.env                ← Aura API credentials (gitignored, never overwrite)
progress.md             ← stage-by-stage progress (this skill writes it)
requirements.txt        ← Python dependencies

schema/
  schema.json           ← graph model definition
  schema.cypher         ← DDL: constraints + indexes
  reset.cypher          ← wipe all data (keep schema)

data/
  generate.py           ← synthetic data generator  (DATA_SOURCE=synthetic)
  import.py             ← CSV/file importer          (DATA_SOURCE=csv or relational)
  *.csv                 ← any provided or generated data files

queries/
  queries.cypher        ← validated Cypher query library

scripts/
  provision_aura.py     ← Aura provisioning script (generated during provision stage)

notebook.ipynb          ← app artifact (root — standard jupyter convention)
app.py                  ← app artifact (root — streamlit run app.py)
main.py                 ← app artifact (root — uvicorn main:app)
graphrag_app.py         ← app artifact (root)

根目录级文件（.env、requirements.txt、应用代码）保留在根目录，因为工具需要它们位于该处。其他所有内容都放入相应的子文件夹。

---

进度跟踪

此技能会在工作目录中维护 progress.md，以支持断点续用。

启动时：

1. 检查 progress.md 是否存在。
2. 如果存在，找到第一个待处理阶段：

   grep -B1 "^status: pending" progress.md | grep "^###" | head -1
   

3. 从该阶段恢复。读取其上下文块（标题下方的 key=value 行），以恢复 DOMAIN、USE_CASE、NEO4J_URI 等信息——不要再次询问已记录的信息。
4. 对于每个已完成的阶段，在继续之前读取其 files= 行中列出的所有文件。这些文件是事实依据——不要凭记忆重建其内容。
   • schema/schema.json → 在 model、load、query 或 build 阶段之前重新读取
   • queries/queries.cypher → 在 build 阶段之前重新读取
   • data/generate.py → 在 import 或 reset 之前重新读取
5. 如果 progress.md 不存在，则从 0-prerequisites 开始。

阶段完成时——更新（或创建）progress.md：

• 如果该阶段的 ### 部分已存在，将 status: pending 更新为 status: done，并追加任何新的 key=value 行。
• 如果该部分不存在，则按以下格式追加。

格式：

# Neo4j Getting-Started — Progress


### 0-prerequisites
status: done

### 1-context
status: done
DOMAIN=social
USE_CASE=friend recommendations
EXPERIENCE=beginner
DB_TARGET=aura-free
DATA_SOURCE=synthetic
APP_TYPE=notebook
EXEC_METHOD=query-api

### 2-provision
status: done
NEO4J_URI=neo4j+s://abc123.databases.neo4j.io

### 3-model
status: done
labels=Person,Post
relationships=FOLLOWS,POSTED
constraints=2

### 4-load
status: done
nodes=200 Person, 50 Post
relationships=1400 FOLLOWS, 300 POSTED

### 5-explore
status: pending

### 6-query
status: pending

### 7-build
status: pending

---

执行协议

对于每个阶段：

1. 宣布阶段："## Stage: <name> — <purpose>"
2. 阅读 ${CLAUDE_SKILL_DIR}/references/<name>.md
3. 执行该文件中的说明
4. 验证该阶段的完成条件
5. 将 progress.md 更新为 status: done，并记录该阶段特定的上下文
6. 继续下一个阶段（HITL：先暂停以征求批准）

如果某个阶段失败，请按照该阶段参考文件中的错误处理指南恢复。除非下方的跳过条件明确允许，否则不要跳过阶段。

---

阶段

阶段按所示编号顺序执行。每个阶段都必须以前一阶段成功完成为前提（适用跳过条件的情况除外）。进入每个阶段时，阅读其链接的参考文件。

0-prerequisites → 1-context → 2-provision → 3-model → 4-load → 5-explore → 6-query → 7-build

多个阶段共用的功能：

• Cypher 执行：${CLAUDE_SKILL_DIR}/references/capabilities/execute-cypher.md（3 种选项；在 context 中选择 EXEC_METHOD）
• Cypher 编写规则：${CLAUDE_SKILL_DIR}/references/capabilities/cypher-authoring.md（或交由 neo4j-cypher-authoring-skill 处理）
• MCP 配置：${CLAUDE_SKILL_DIR}/references/capabilities/mcp-config.md（用于 prerequisites 和 build）
• 查询验证：${CLAUDE_SKILL_DIR}/scripts/validate_queries.py——一次调用批量验证所有查询（用于 query）

0 — prerequisites

目的：在进行任何其他操作之前，检查并安装必需的 CLI 工具。
参考：${CLAUDE_SKILL_DIR}/references/0-prerequisites.md
完成条件：可访问 neo4j-mcp 二进制文件；.gitignore 中包含 .env 条目。
绝不可跳过。

---

1 — context

目的：收集领域、用例、经验、基础设施目标、数据源和输出类型。检测用于执行 Cypher 的 EXEC_METHOD。
参考：${CLAUDE_SKILL_DIR}/references/1-context.md
完成条件：已知 DOMAIN、USE_CASE、EXPERIENCE、DB_TARGET、DATA_SOURCE、APP_TYPE、EXEC_METHOD。
跳过条件：对话上下文中已提供所有变量。

---

2 — provision

目的：配置正在运行的 Neo4j 数据库，并将凭据保存到 .env。
参考：${CLAUDE_SKILL_DIR}/references/2-provision.md
完成条件：.env 存在且包含 NEO4J_URI/USERNAME/PASSWORD/DATABASE；已验证连接性。
跳过条件：DB_TARGET=existing → 根据用户提供的凭据写入 .env，然后继续执行 3-model。

---

3 — model

目的：设计或发现适用于该用例的图数据模型。
参考：${CLAUDE_SKILL_DIR}/references/3-model.md
完成条件：已写入 schema.json 和 schema.cypher。
跳过条件：DATA_SOURCE=demo → 使用演示架构，继续执行 4-load。
HITL 检查点（仅限 HITL 模式——自主模式下完全跳过）：展示模型草案并等待批准。

---

4 — load

目的：应用架构约束，然后导入数据（演示数据、合成数据、CSV 或文档）。
依赖项：3-model（导入前必须创建约束）。
完成条件：节点数 ≥ 50；已编写 import/ 脚本；已编写 reset.cypher。

---

5 — explore

目的：提供图的可视化入口——实现“豁然开朗”的时刻。
参考：${CLAUDE_SKILL_DIR}/references/5-explore.md
完成条件：已向用户输出浏览器 URL，或已添加笔记本可视化单元格。
硬性关卡——绝不可跳过。

---

6 — query

目的：为该用例生成并验证 Cypher 查询库。
参考：${CLAUDE_SKILL_DIR}/references/6-query.md
完成条件：queries.cypher 中有 ≥5 条查询；≥2 条遍历查询；≥3 条查询返回结果。

---

7 — build

目的：生成可运行的应用、仪表板、笔记本或 Agent 集成。
参考：${CLAUDE_SKILL_DIR}/references/7-build.md
完成条件：产物存在、通过语法检查，并返回非空的用例结果。

---

成功关卡（7 项都必须满足）

关卡	阶段	条件
db_running	provision	driver.verify_connectivity() 成功
model_valid	model	数据库中有 ≥2 个节点标签、≥1 种关系类型、≥1 个约束
data_present	load	MATCH (n) RETURN count(n) ≥ 50
queries_work	query	≥5 条查询；≥2 条遍历查询；≥3 条查询各返回 ≥1 条结果
graph_visible	explore	已向用户提供浏览器 URL 或笔记本可视化
app_generated	build	产物存在、通过语法检查并返回非空结果
integration_ready	build	存在 MCP 配置或 Agent 框架代码（如果有此要求）

---

快捷路径

情况	操作
DB_TARGET=existing	跳过 provision；根据用户提供的凭据写入 .env；前往 model
DATA_SOURCE=demo	跳过自定义建模；使用演示架构；直接前往 load
DB_TARGET=existing + 数据已存在	跳过 provision、model、load；检查架构；前往 explore

---

HITL 与自主模式

HITL（对话式）：在 model 后暂停，以便审核模型；在 load 后暂停，以便审核数据。

自主模式（类似 CI，上下文一次性全部提供）：所有阶段都不暂停等待批准；自动批准所有决策；立即继续完成全部 8 个阶段；将浏览器 URL 输出到 stdout；从数据库运行起，目标在 ≤15 分钟内完成。

如何检测自主模式——在阶段 1 开始时检查：

满足以下任意一项即为自主模式：

• 初始提示词包含以下全部内容：DOMAIN、USE_CASE、EXPERIENCE、DB_TARGET、DATA_SOURCE、APP_TYPE（或“Domain: X, use-case: Y, ...”之类的等效表述）
• 会话通过 --auto-approve 或类似的非交互标志启动
• 所有上下文变量已记录在 progress.md 中（恢复一次自主运行）

HITL 模式：用户开启了新的对话，但未一次性提供完整上下文。

在自主模式下：每个阶段参考文件中的所有 HITL 检查点都会自动跳过。 不要询问是否批准。不要说“这样看起来对吗？”。不要暂停。立即继续下一步。

---

最终摘要（所有关卡通过后交付）

步骤 1 — 使用以下模板在工作目录中编写 README.md。 根据 progress.md 和实际生成的文件，填写所有 <placeholder>。 这是必需的输出——不要跳过。

重要——可移植的命令：README.md 中所有重新运行命令都必须使用 python3（绝不要使用 /opt/homebrew/bin/python3.14 或 /usr/local/bin/python3 之类的绝对路径）。这份 README 会与使用不同 Python 安装的其他人共享。

# <DOMAIN> Graph — <USE_CASE>

A synthetic <DOMAIN> graph built with Neo4j, covering <USE_CASE>.
Generated by the neo4j-getting-started-skill on <date>.

## What's in the graph

| Label | Count | Description |
|-------|-------|-------------|
| <Label> | <N> | <one line> |

**Relationships:** <TYPE1>, <TYPE2>, ...  
**Constraints:** <N> uniqueness constraints applied

## Explore visually

Open in Neo4j Browser:
<browser_url>

Use `NEO4J_PASSWORD` from `.env` to connect, then run:
```cypher
// Starter query — shows the full graph sample
MATCH (n)-[r]->(m) RETURN n, r, m LIMIT 50

文件

文件	用途	重新运行
schema/schema.json	图模型	—
schema/schema.cypher	约束与索引	source .env && cypher-shell -a $NEO4J_URI -u $NEO4J_USERNAME -p $NEO4J_PASSWORD --file schema/schema.cypher
schema/reset.cypher	清除数据，保留架构	source .env && cypher-shell -a $NEO4J_URI -u $NEO4J_USERNAME -p $NEO4J_PASSWORD --file schema/reset.cypher
data/generate.py	重新生成合成数据	source .venv/bin/activate && python3 data/generate.py
data/import.py	将 CSV 重新导入 Neo4j	source .venv/bin/activate && python3 data/import.py
queries/queries.cypher	查询库	粘贴到 Neo4j Browser
<artifact>		<run command>
requirements.txt	Python 依赖项	source .venv/bin/activate && pip install -r requirements.txt

（当 DATA_SOURCE=csv 时，省略 data/generate.py 行；当 DATA_SOURCE=synthetic 时，省略 data/import.py 行。）

运行应用

python3 -m venv .venv     # skip if .venv already exists
source .venv/bin/activate
pip install -r requirements.txt
<run command>

<仅限 FastAPI——包含此部分：> 打开 http://localhost:8000/docs 查看交互式 API 文档。

<适用于 MCP 集成——当 APP_TYPE 包含 mcp 时，包含此部分：>

MCP 集成

要直接从 Claude 查询图：

Claude Code — 将 mcp-claude-code.json 复制到 .claude/settings.json：

cp mcp-claude-code.json .claude/settings.json

然后重新加载 Claude Code（/reload 或重启）。提问：“我的 Neo4j 数据库中有哪些节点标签？”

Claude Desktop — 将 mcp-claude-desktop.json 合并到 ~/Library/Application Support/Claude/claude_desktop_config.json，然后重启 Claude Desktop。

可用的 MCP 工具：get-schema、read-cypher、write-cypher。

重置并重新加载

source .env
cypher-shell -a $NEO4J_URI -u $NEO4J_USERNAME -p $NEO4J_PASSWORD --file schema/reset.cypher
source .venv/bin/activate
python3 data/generate.py   # or skip if using your own CSVs
python3 data/import.py

示例查询

// <use-case-specific query 1 — fill in from queries/queries.cypher>
<query>

// <use-case-specific query 2>
<query>

（Cypher 注释使用 //，而不是 --。）

后续步骤

• 探索 GraphAcademy，深入学习 Neo4j
• 编辑 data/*.csv 以更改数据集，然后重新运行 data/import.py
• 扩展模型：在 schema/schema.json 中添加新的节点标签或关系类型

**Step 2 — print this to the conversation:**

✓ Neo4j 入门 — 已完成

数据库： <NEO4J_URI> 浏览器： https://browser.neo4j.io/?connectURL=

── 已生成的内容（请保留这些文件）─────────────────────────────── schema/schema.json 图模型定义 schema/schema.cypher 重新应用约束/索引： cypher-shell ... --file schema/schema.cypher schema/reset.cypher 清除数据，保留架构： cypher-shell ... --file schema/reset.cypher data/generate.py 重新生成合成数据： source .venv/bin/activate && python3 data/generate.py data/*.csv 源数据文件 — 编辑以更改数据集 data/import.py 从 CSV 重新导入： source .venv/bin/activate && python3 data/import.py queries/queries.cypher 查询库 — 粘贴到 Neo4j Browser 中，或使用 cypher-shell 运行 requirements.txt 安装依赖： source .venv/bin/activate && pip install -r requirements.txt

── 检查项 ────────────────────────────────────────────────────── db_running ✓ model_valid ✓ data_present ✓ queries_work ✓ graph_visible ✓ app_generated ✓ integration_ready ✓/–

── 后续步骤 ────────────────────────────────────────────────────

• 探索： 打开浏览器 URL → 运行 MATCH (n)-[r]->(m) RETURN n,r,m LIMIT 50
• 迭代： 编辑 data/*.csv → source .venv/bin/activate && python3 data/import.py（先重置）
• 学习： https://graphacademy.neo4j.com

Omit lines that don't apply (e.g. omit `data/import.py` when `DATA_SOURCE=synthetic`,
omit `data/generate.py` when `DATA_SOURCE=csv`).

---

## Checklist

- [ ] Prerequisites met (Docker/Python/Java; Aura API key if cloud)
- [ ] DB reachable — `RETURN 1` in cypher-shell
- [ ] Constraints + indexes ONLINE before data load
- [ ] Data loaded — `MATCH (n) RETURN count(n)` > 0
- [ ] queries.cypher: all queries return expected results
- [ ] App/notebook runs end-to-end
- [ ] `.env` gitignored; credentials not hardcoded