neo4j-getting-started-skill

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
name: neo4j-getting-started-skill
description: Orchestrates zero-to-running-app in 8 stages — prerequisites → context →
  provision → model → load → explore → query → build. Each stage reads its own reference
  file. Supports HITL and fully autonomous operation. Use when starting a new Neo4j project
  from scratch, provisioning Aura, generating synthetic data, building a notebook or app,
  or running the full onboarding pipeline. Time budget ≤15 min autonomous, ≤90 min HITL.
  Does NOT cover Cypher query authoring — use neo4j-cypher-skill.
  Does NOT cover driver upgrades or Cypher migration — use neo4j-migration-skill.
  Does NOT cover CLI/admin tasks on an existing DB — use neo4j-cli-tools-skill.
version: 1.0.5
allowed-tools: Bash, WebFetch, Read, Write, Edit,
  mcp__neo4j__read-cypher, mcp__neo4j__write-cypher, mcp__neo4j__get-schema,
  mcp__neo4j__list-gds-procedures,
  mcp__neo4j_data_modeling__validate_data_model,
  mcp__neo4j_data_modeling__visualize_data_model
compatibility: claude-code, cursor, windsurf, any-agent-with-bash
---

# Neo4j Getting-Started Skill

Guide a **user or agent** from zero to a working Neo4j application by executing the 8 stages below in order.

**At the start of each stage**: read the corresponding `${CLAUDE_SKILL_DIR}/references/<stage-name>.md` file and follow its instructions. Only load the stage you are currently executing — not all at once.

**"User" means both a human developer and an autonomous coding agent.**

---

## When to Use

- New Neo4j project from scratch (local/Docker/Aura)
- Full onboarding: zero → DB → model → load → app
- Generating synthetic data for demos or dev

## When NOT to Use

- **Cypher authoring on existing project** → `neo4j-cypher-skill`
- **Driver upgrades / Cypher migration** → `neo4j-migration-skill`
- **Admin on existing DB** (backup, restore, import) → `neo4j-cli-tools-skill`

---

## Project Structure

**All generated code, data, scripts, queries, and notebooks must be written to the working directory** so the user can inspect, reuse, and re-run them after the session ends. Never generate output only as text in the conversation — always write it to a file.

Organize files into this layout. Create subdirectories before writing files.

```
.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)
```

Root-level files (`.env`, `requirements.txt`, app code) stay at root because tooling expects them there. Everything else goes in the appropriate subfolder.

---

## Progress Tracking

The skill maintains `progress.md` in the working directory to support resumability.

**On startup:**
1. Check if `progress.md` exists.
2. If it exists, find the first pending stage:
   ```bash
   grep -B1 "^status: pending" progress.md | grep "^###" | head -1
   ```
3. Resume from that stage. Read its context block (the key=value lines beneath the header) to restore `DOMAIN`, `USE_CASE`, `NEO4J_URI`, etc. — do not re-ask the user for information already recorded.
4.