Neo4j Modeling Skill

> **Status: Draft / WIP**

# neo4j-modeling-skill

Guides agents through designing and reviewing Neo4j graph data models: node labels, relationship types, properties, constraints, and anti-pattern detection.

**Install:**
```bash
npx skills add https://github.com/neo4j-contrib/neo4j-skills --skill neo4j-modeling-skill
```

Or paste this link into your coding assistant:
https://github.com/neo4j-contrib/neo4j-skills/tree/main/neo4j-modeling-skill


---
name: neo4j-modeling-skill
description: Design, review, and refactor Neo4j graph data models. Use when choosing node
  labels vs relationship types vs properties, migrating relational/document schemas to
  graph, detecting anti-patterns (generic labels, supernodes, missing constraints),
  designing intermediate nodes for n-ary relationships, enforcing schema with constraints
  and indexes, or assessing an existing model against graph modeling best practices.
  Does NOT handle Cypher query authoring — use neo4j-cypher-skill.
  Does NOT handle Spring Data Neo4j entity mapping — use neo4j-spring-data-skill.
  Does NOT handle GraphQL type definitions — use neo4j-graphql-skill.
  Does NOT handle data import — use neo4j-import-skill.
version: 1.0.1
allowed-tools: WebFetch Bash
---

## When to Use

- Designing graph model from scratch (domain → nodes, rels, props)
- Reviewing existing model for anti-patterns
- Deciding node vs property vs relationship vs label
- Migrating relational or document schema to graph
- Designing intermediate nodes for n-ary or complex relationships
- Detecting and mitigating supernode / high-fanout problems
- Choosing and creating constraints + indexes for a model

## When NOT to Use

- **Writing or optimizing Cypher** → `neo4j-cypher-skill`
- **Spring Data Neo4j (@Node, @Relationship)** → `neo4j-spring-data-skill`
- **GraphQL type definitions** → `neo4j-graphql-skill`
- **Importing data (LOAD CSV, APOC import)** → `neo4j-import-skill`

---

## Inspect Before Designing

On existing database, run first — never propose changes without current state:

```cypher
CALL db.schema.visualization() YIELD nodes, relationships RETURN nodes, relationships;
SHOW CONSTRAINTS YIELD name, type, labelsOrTypes, properties RETURN name, type, labelsOrTypes, properties;
SHOW INDEXES YIELD name, type, labelsOrTypes, state WHERE state = 'ONLINE' RETURN name, type, labelsOrTypes;
```

If APOC available:
```cypher
CALL apoc.meta.schema() YIELD value RETURN value;
```

MCP tool map:

| Operation | Tool |
|---|---|
| Inspect schema | `get-schema` |
| `SHOW CONSTRAINTS`, `SHOW INDEXES` | `read-cypher` |
| `CREATE CONSTRAINT ... IF NOT EXISTS` | `write-cypher` (show + confirm first) |

---

## Defaults — Apply to Every Model

1. Use-case first — list 5+ queries the model must answer before designing
2. Nodes = entities (nouns) with identity; rels = connections (verbs) with direction
3. Labels PascalCase; rel types SCREAMING_SNAKE_CASE; properties camelCase
4. Every node type used in MERGE has a uniqueness constraint on its key property
5. Add property type constraints (`REQUIRE n.prop IS :: STRING`) where the type is known — helps the query planner and catches bad writes early
6. No generic labels (`:Entity`, `:Node`, `:Thing`); no generic rel types (`:RELATED_TO`, `:HAS`)
7. Security labels (used for row-level access control) should start with a common prefix (e.g. `Sec`) so application code can reliably filter them out of the domain schema
8. Rel direction encodes semantic meaning — not arbitrary
9. Inspect schema before proposing any change on an existing database
10. All constraint/index DDL uses `IF NOT EXISTS` — safe to rerun
11. **On Neo4j 2026.02+ (Enterprise/Aura):** consider `ALTER CURRENT GRAPH TYPE SET { … }` or `EXTEND GRAPH TYPE WITH { … }` to declare the full model in one block instead of individual `CREATE CONSTRAINT` statements — see `neo4j-cypher-skill/references/graph-type.md`. **PREVIEW** — syntax may change before GA.

---

## Key Patterns

### Node vs Relationship vs P