Skip to main content
skill CX Codex

graph-schema — Claude Code skill for graph schema design

graph-schema is a Claude Code skill for designing, reviewing, and refactoring graph database schemas. It activates for node and relationship modeling or when mapping a domain into a graph.

MIT 239 installs ★ 227 updated 2026-08-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add pproenca/dot-skills --skill graph-schema -a claude-code
Open on GitHub

What graph-schema does

graph-schema helps turn domain requirements into a graph structure. It examines what belongs in a node, a relationship, or a property, and flags modeling problems during schema reviews and refactoring. The guidance puts data-model correctness ahead of performance.

The guide groups its rules around entity classification, relationship design, property placement, query patterns, structural approaches, constraints, and schema evolution. Topics include avoiding foreign keys as properties, choosing meaningful relationship types, and testing a model against real queries. Cypher examples contrast flawed models with corrected ones.

It covers property graphs such as Neo4j, Memgraph, and Amazon Neptune. To install it for Claude Code, run npx skills add pproenca/dot-skills --skill graph-schema -a claude-code; the skill file is at ~/.claude/skills/graph-schema/SKILL.md.

What it helps with

  • design a graph schema from domain requirements
  • decide whether data belongs in a node, relationship, or property
  • review an existing graph model for structural mistakes
  • reshape a relational model for a graph database

Example prompts for the agent

  • Design a graph schema for this domain.
  • Review whether this model assigns nodes, relationships, and properties correctly.
  • Convert this relational model into a graph structure and show the design with Cypher examples.

How to install graph-schema

1Skills CLI (Vercel)

npx skills add pproenca/dot-skills --skill graph-schema -a claude-code

2Manually: put the files in place

~/.claude/skills/graph-schema/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/graph-schema/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about graph-schema

How do I install graph-schema in Claude Code?

Run npx skills add pproenca/dot-skills --skill graph-schema -a claude-code. The skill file is located at ~/.claude/skills/graph-schema/SKILL.md.

What does graph-schema do?

It guides graph database schema design, review, and refactoring. It helps place entities, relationships, and properties, prioritizing model correctness over performance.

Which graph databases does graph-schema cover?

The guide covers property graphs, including Neo4j, Memgraph, and Amazon Neptune.

Source text

SKILL.md · MIT
---
name: graph-schema
description: Graph database schema design and data modeling expert. Use when designing, reviewing, or refactoring graph database schemas (Neo4j, Memgraph, Neptune, etc.). Triggers on graph modeling, node/relationship design, Cypher schema, property graph design, knowledge graph modeling, or when translating a domain into a graph structure. Focuses primarily on data modeling correctness — understanding the user's goal and translating it into the right graph structure — with performance as a secondary concern.
---

# dot-skills Graph Database Schema Design Best Practices

Comprehensive graph database data modeling guide for property graphs (Neo4j, Memgraph, Amazon Neptune, etc.). Contains 46 rules across 8 categories, prioritized by modeling impact from critical (entity classification, relationship design) to incremental (scale and evolution). Each rule includes detailed explanations, real-world Cypher examples comparing incorrect vs. correct models, and specific impact descriptions.

**Philosophy:** Data modeling correctness first, performance second. Always ask "what is the user trying to achieve?" before choosing structure.

## When to Apply

Reference these guidelines when:
- Designing a new graph database schema from domain requirements
- Translating a relational schema to a graph model
- Deciding whether something should be a node, relationship, or property
- Reviewing an existing graph schema for modeling errors
- Refactoring a graph that produces awkward or slow queries
- Planning for schema evolution and data growth

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Entity Classification | CRITICAL | `entity-` |
| 2 | Relationship Design | CRITICAL | `rel-` |
| 3 | Property Placement | HIGH | `prop-` |
| 4 | Query-Driven Refinement | HIGH | `query-` |
| 5 | Structural Patterns | HIGH | `pattern-` |
| 6 | Anti-Patterns | MEDIUM | `anti-` |
| 7 | Constraints & Integrity | MEDIUM | `constraint-` |
| 8 | Scale & Evolution | LOW-MEDIUM | `scale-` |

## Quick Reference

### 1. Entity Classification (CRITICAL)

- [`entity-events`](references/entity-events.md) - Model multi-participant events as first-class nodes
- [`entity-shared-values`](references/entity-shared-values.md) - Promote shared property values to nodes
- [`entity-specific-labels`](references/entity-specific-labels.md) - Use specific labels over generic ones
- [`entity-multi-label`](references/entity-multi-label.md) - Qualify entities with multiple labels
- [`entity-identity-state`](references/entity-identity-state.md) - Separate identity from mutable state
- [`entity-reify-actions`](references/entity-reify-actions.md) - Reify lifecycle actions into nodes
- [`entity-avoid-god-nodes`](references/entity-avoid-god-nodes.md) - Avoid kitchen-sink entity nodes

### 2. Relationship Design (CRITICAL)

- [`rel-specific-types`](references/rel-specific-types.md) - Use specific relationship types over generic ones
- [`rel-meaningful-direction`](references/rel-meaningful-direction.md) - Choose semantically meaningful direction
- [`rel-naming-conventions`](references/rel-naming-conventions.md) - Follow UPPER_SNAKE_CASE for relationship types
- [`rel-no-redundant-reverse`](references/rel-no-redundant-reverse.md) - Don't create redundant reverse relationships
- [`rel-properties-scope`](references/rel-properties-scope.md) - Put data on relationships only when it describes the connection
- [`rel-single-semantic`](references/rel-single-semantic.md) - One relationship type per semantic meaning
- [`rel-typed-over-filtered`](references/rel-typed-over-filtered.md) - Prefer typed relationships over generic + property filter

### 3. Property Placement (HIGH)

- [`prop-no-foreign-keys`](references/prop-no-foreign-keys.md) - Don't embed foreign keys as properties
- [`prop-promote-to-node`](references/prop-promote-to-node.md) - Promote frequently-queried values to nodes
- [`prop-correct-data-types`](references/prop-correct-data-types.md) - Use appropriate data types for properties
- [`prop-no-arrays-for-connections`](references/prop-no-arrays-for-connections.md) - Don't use property arrays when you need relationships
- [`prop-relationship-vs-node-data`](references/prop-relationship-vs-node-data.md) - Know when data belongs on relationship vs. node

### 4. Query-Driven Refinement (HIGH)

- [`query-critical-traversals`](references/query-critical-traversals.md) - Design for your most critical traversals first
- [`query-shortcut-relationships`](references/query-shortcut-relationships.md) - Add shortcut relationships for frequent multi-hop queries
- [`query-denormalize-reads`](references/query-denormalize-reads.md) - Denormalize for read-heavy paths
- [`query-filter-by-rel-props`](references/query-filter-by-rel-props.md) - Use relationship properties to filter traversals
- [`query-test-before-deploy`](references/query-test-before-deploy.md) - Test model against real queries before deploying

### 5. Structural Patterns (HIGH)

- [`pattern-intermediary-nodes`](references/pattern-intermediary-nodes.md) - Use intermediary nodes for multi-entity relationships
- [`pattern-hierarchy`](references/pattern-hierarchy.md) - Model hierarchies with category nodes and depth relationships
- [`pattern-linked-list`](references/pattern-linked-list.md) - Use linked lists for ordered sequences
- [`pattern-timeline-tree`](references/pattern-timeline-tree.md) - Apply timeline trees for temporal data
- [`pattern-fan-out`](references/pattern-fan-out.md) - Fan-out pattern for event streams and activity feeds
- [`pattern-bipartite`](references/pattern-bipartite.md) - Use bipartite structure for many-to-many with context

### 6. Anti-Patterns (MEDIUM)

- [`anti-join-table-nodes`](references/anti-join-table-nodes.md) - Don't model relational join tables as nodes
- [`anti-generic-relationships`](references/anti-generic-relationships.md) - Don't use generic RELATED_TO or CONNECTED relationships
- [`anti-relational-porting`](references/anti-relational-porting.md) - Don't port relational schemas directly to graph
- [`anti-over-modeling`](references/anti-over-modeling.md) - Don't make everything a node
- [`anti-duplicate-data`](references/anti-duplicate-data.md) - Don't duplicate data instead of creating relationships
- [`anti-string-encoded-structure`](references/anti-string-encoded-structure.md) - Don't encode structured data as delimited strings

### 7. Constraints & Integrity (MEDIUM)

- [`constraint-unique-identifiers`](references/constraint-unique-identifiers.md) - Define uniqueness constraints on natural identifiers
- [`constraint-existence`](references/constraint-existence.md) - Use existence constraints for required properties
- [`constraint-index-traversals`](references/constraint-index-traversals.md) - Create indexes on traversal entry point properties
- [`constraint-no-over-index`](references/constraint-no-over-index.md) - Don't over-index — each index has a write cost
- [`constraint-node-key`](references/constraint-node-key.md) - Use composite node keys for natural multi-part identifiers

### 8. Scale & Evolution (LOW-MEDIUM)

- [`scale-supernode-mitigation`](references/scale-supernode-mitigation.md) - Mitigate supernodes with fan-out or partitioning
- [`scale-temporal-versioning`](references/scale-temporal-versioning.md) - Separate current state from historical state
- [`scale-schema-migration`](references/scale-schema-migration.md) - Plan for label and relationship type evolution
- [`scale-batch-refactoring`](references/scale-batch-refactoring.md) - Use APOC or batched queries for schema refactoring
- [`scale-dense-node-detection`](references/scale-dense-node-detection.md) - Monitor and detect emerging supernodes

## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) - Category structure and impact levels
- [Rule template](assets/templates/_template.md) - Template for adding new rules

## Reference Files

| File | Description |
|------|-------------|
| [references/_sections.md](references/_sections.md) | Category definitions and ordering |
| [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules |
| [metadata.json](metadata.json) | Version and reference information |

© pproenca · MIT · pproenca/dot-skills

Similar skills

All skills for Data and databases →

From the same set139

The whole set →
app-planner app-planner creates a structured Markdown design plan using Apple Design DNA patterns before coding starts. Organizes screens into buildable milestones for ios-taste. CX Codex +1 244installs threat-model threat-model maps attack surfaces and trust boundaries across a codebase by tracing untrusted inputs directly to execution sinks. CX Codex +1 243installs opencode-ts The opencode-ts skill guides TypeScript implementation, tests, and refactoring in Effect-based projects. It gives the agent a workflow tied to the project’s architecture and conventions. CX Codex +1 240installs exec-plan exec-plan manages self-contained Markdown execution plans across agent sessions for tasks touching more than three files or taking over an hour. CX Codex +1 239installs clean-code-ts-react clean-code-ts-react adapts Robert C. Martin's Clean Code principles for TypeScript 5.x and React 19. Guides code reviews, component architecture, and refactoring sessions. CX Codex +1 238installs cli-for-agents cli-for-agents is a Claude Code skill for designing and reviewing CLIs used by AI agents and automation. It applies to work on subcommands, flags, help text, and error messages. CX Codex +1 237installs eval-mcp eval-mcp measures MCP tool schema quality and Claude's tool selection accuracy. Detects confusing descriptions and runs intent benchmarks. CX Codex +1 234installs threat-patch threat-patch turns scanner findings or a threat model into small code patches, each with a short write-up and test steps. CX Codex +1 232installs

Project sponsors

Companies that keep this analytics open