Neo4j Getting Started Skill

What it does

When your agent uses it

• Starting a new Neo4j project from scratch
• Provisioning Aura
• Generating synthetic data
• Building a notebook

Example prompts

• “Use the neo4j-getting-started-skill skill to orchestrate zero-to-running-app in 8 stages — prerequisites → context → provision → model → load →…”
• “/neo4j-getting-started-skill”

Requirements

• Python 3
• Docker
• Compatibility (from SKILL.md): claude-code, cursor, windsurf, any-agent-with-bash
• Pre-approved tools (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

Workflow steps

8 steps, taken from the step headings in SKILL.md.

1. 1prerequisites
2. 2context
3. 3provision
4. 4model
5. 5load
6. 6explore
7. 7query
8. 8build

What it can do on your machine

Read from SKILL.md and the folder at commit bb30e1f. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves these tools, so the agent can use them without asking each time:

  • 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

  …and 1 more on the same allowed-tools line.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Ships 1 file in scripts/ (Python), which the agent can run.

  Shell commands in SKILL.md call:

  • python3
  • pip

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Links to these hosts (documentation or services it may open):

  • graphacademy.neo4j.com
  • browser.neo4j.io

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names these keys or tokens, usually read from environment variables:

  • NEO4J_PASSWORD

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

• Compatibility

  claude-code, cursor, windsurf, any-agent-with-bash

  From compatibility in the SKILL.md frontmatter.

Context cost

Neo4j Getting Started Skill loads about 4.3k tokens when it runs, and up to ~37k if it reads all its reference files. Until then it costs about 169 tokens; SKILL.md has 1,398 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~169

When it runs · the whole SKILL.md, loaded when a task matches

~4.3k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~37k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

• NoteMentions a .env fileSKILL.md:51

  .env                    ← DB credentials (gitignored, loaded by python-dotenv)

• NoteMentions a .env fileSKILL.md:78

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

• NoteMentions a .env fileSKILL.md:181

  ` binary is reachable; `.gitignore` has `.env` entry.

• NoteMentions a .env fileSKILL.md:195

  Neo4j database and save credentials to `.env`.

• NoteMentions a .env fileSKILL.md:197

  **Completes when**: `.env` exists with `NEO4J_URI/USERNAME/PASSWORD/DATABASE`; connectivity verified.

• NoteMentions a .env fileSKILL.md:198

  ndition**: `DB_TARGET=existing` → write `.env` from user credentials, proceed to `3-model`.

• NoteMentions a .env fileSKILL.md:259

  GET=existing` | Skip `provision`; write `.env` from user creds; go to `model` |

• WarningTells the agent its actions are pre-authorized / not to stop for confirmationSKILL.md:269

  CI-like, all context provided upfront): never pause for approval at any stage; auto-approve all decisions; proceed immed

• NoteMentions a .env fileSKILL.md:312

  Use `NEO4J_PASSWORD` from `.env` to connect, then run:

• NoteMentions a .env fileSKILL.md:323

  ypher` | Constraints + indexes | `source .env && cypher-shell -a $NEO4J_URI -u $NEO4J_USERNAME -p $NEO4J_PASSWORD --file

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from neo4j-contrib/neo4j-skills at commit bb30e1f, republished under its MIT licence (© neo4j-contrib). 1,398 words, ~4,303 tokens.

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.

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

version

1.0.6

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

# 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

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

# <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

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

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

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>

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

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

© neo4j-contrib, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 17 other files (scripts, references) in neo4j-getting-started-skill of neo4j-contrib/neo4j-skills.

• SKILL.md
• AGENTS.md
• README.md
• references/0-prerequisites.md
• references/1-context.md
• references/2-provision.md
• references/3-model.md
• references/4-load.md
• references/5-explore.md
• references/6-query.md
• references/7-build.md
• references/capabilities/cypher-authoring.md
• references/capabilities/execute-cypher.md
• references/capabilities/kg-from-documents.md
• references/capabilities/mcp-config.md
• references/domain-patterns.md
• references/quick-reference.md
• scripts/validate_queries.py

Open the folder on GitHubat commit bb30e1f