neo4j-getting-started-skill
Orchestrates zero-to-running-app in 8 stages — prerequisites → context →
neo4j-contrib · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add neo4j-contrib/neo4j-skills --skill neo4j-getting-started-skillAbout this skill
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:
- Check if
progress.mdexists. - If it exists, find the first pending stage:
grep -B1 "^status: pending" progress.md | grep "^###" | head -1 - 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. - For each completed stage, read every file listed in its
files=line before proceeding. These files are the ground truth — do not reconstruct their content from memory.schema/schema.json→ re-read before model, load, query, or build stagesqueries/queries.cypher→ re-read before build stagedata/generate.py→ re-read before import or reset
- If
progress.mddoes not exist, start from0-prerequisites.
On stage completion — update (or create) progress.md:
- If the stage's
###section already exists, updatestatus: pending→status: doneand append any new key=value lines. - If the section doesn't exist, append it following the format below.
Format:
# Neo4j Getting-Started — Progress
<!-- Resume: grep for "status: pending" to find the next stage -->
### 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
Execution Protocol
For each stage:
- Announce the stage:
"## Stage: <name> — <purpose>" - Read
${CLAUDE_SKILL_DIR}/references/<name>.md - Execute the instructions in that file
- Verify the stage's completion condition
- Update
progress.mdwithstatus: doneand stage-specific context - Proceed to the next stage (HITL: pause for approval first)
If a stage fails, recover using the error guidance in the stage reference file. Do not skip stages unless the skip condition below explicitly permits it.
Stages
Stages run in the numbered order shown. Each depends on the one before it completing su
Read the complete source ↗