Neo4j Modeling Skill

Status: Draft / WIP — Content is a placeholder. Reference files and checklist rules to be added.

When to Use

Designing a graph data model from scratch (domain → nodes, relationships, properties)
Reviewing an existing model for anti-patterns (generic nodes, unnecessary collections)
Deciding what to model as a node vs a property vs a relationship
Migrating a relational or document schema to a graph
Choosing between embedding data on a node vs creating a dedicated node

When NOT to Use

Writing or optimizing Cypher queries → use neo4j-cypher-skill
Spring Data Neo4j entity mapping (@Node, @Relationship) → use neo4j-spring-data-skill
GraphQL type definitions → use neo4j-graphql-skill
Importing data → use neo4j-import-skill

MCP Tool Usage

When designing or reviewing an existing schema, use get-schema first:

Operation	MCP tool	Notes
Inspect existing schema	`get-schema`	Run before proposing any changes
`SHOW CONSTRAINTS`, `SHOW INDEXES`	`read-cypher`	Verify what already exists
`CREATE CONSTRAINT ... IF NOT EXISTS`	`write-cypher`	Safe to run repeatedly

Never propose schema changes without first inspecting the current state.

Inspect Before Designing

On an existing database, always run this before proposing model changes:

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;

Modeling Decision Tree

1. Is it a "thing" with identity and multiple query entry points? → Node
2. Is it a connection between two things with direction or properties? → Relationship
3. Is it a simple scalar always queried with its parent? → Property on parent node
4. Is it a fact with its own properties or multiple connections? → Intermediate node
5. Is it a type/category queried separately? → Label (not a property)

Core Principles

Labels — noun-like, PascalCase, describe what an entity is (:Person, :Product). Avoid generic labels like :Node or :Entity.

Relationship types — verb-like, SCREAMING_SNAKE_CASE, describe the direction of the connection (:KNOWS, :PURCHASED). Avoid generic types like :RELATED_TO.

Properties — camelCase. Only store what you query. Large blobs (embeddings, full text) belong on dedicated nodes.

Constraints — every node type used in MERGE must have a uniqueness constraint on its key property. Apply before importing data.

Schema Review Checklist

Every node label has a unique constraint on its identifier property
No generic labels (:Node, :Entity, :Thing)
No generic relationship types (:RELATED_TO, :HAS)
Relationship direction encodes meaning (not arbitrary)
Properties that are never filtered/sorted are not indexed
Intermediate nodes used for many-to-many with properties (not bare relationships)
Embedding properties stored on dedicated :Chunk nodes, not on business nodes
Labels are PascalCase; relationship types are SCREAMING_SNAKE_CASE

Output Format (Schema Assessment)

## Schema Assessment

### Compliant
- [item checked]

### Issues Found
#### [Issue Title] — Severity: HIGH / MEDIUM / LOW
- Current: [what the model does]
- Problem: [why it is an issue]
- Fix: [specific recommendation]

## Recommended Schema
[nodes, relationships, properties, constraints]

neo4j-modeling-skill