neo4j-modeling-skill

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.

Quality

86%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

83%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A dense, actionable modeling reference with strong executable examples and a clear workflow. Its main weakness is progressive disclosure: it points to a references file that is not present in the bundle, leaving some patterns only hinted at.

Suggestions

Add the missing references/modeling-patterns.md (time-series, versioning, multi-tenancy, linked list, access control) so the in-body references resolve to real one-level-deep content.

Consider moving the Schema Enforcement DDL catalog and Naming Conventions tables into the references file to slim the body, keeping only the most common constraint/index forms inline.

Add an explicit validate-and-retry loop for destructive DDL (e.g. run SHOW CONSTRAINTS after CREATE to confirm, retry on failure) to lift workflow clarity to 5.

Dimension	Reasoning	Score
Conciseness	Largely lean and table-driven with executable Cypher; assumes Claude's knowledge rather than explaining graph basics. Minor padding (repeated 'IF NOT EXISTS' rationale, verbose anti-pattern prose) keeps it just below a 5.	4 / 5
Actionability	Copy-paste-ready Cypher DDL for constraints/indexes, concrete inspection queries, decision tables with explicit mappings, and a structured output template cover the common modeling cases fully.	5 / 5
Workflow Clarity	Clear sequence ('Inspect Before Designing' → 'Defaults' → 'Key Patterns' → 'Schema Enforcement') with validation checkpoints (poll indexes to ONLINE, inspect before proposing changes, severity semantics). Destructive DDL has 'show + confirm first' but no full validate-then-retry loop, so it sits just below 5.	4 / 5
Progressive Disclosure	Good in-body section structure, but the referenced references/modeling-patterns.md file does not exist in the bundle, and time-series/versioning/multi-tenancy patterns referenced in tables are only hinted at rather than split into a real one-level-deep file. Structure is present but the referenced deep content is missing/buried.	3 / 5
	Total	16 / 20 Passed

Description

88%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A highly specific, well-triggered description with explicit positive and negative guidance and clear sibling-skill boundaries. Only minor trigger-synonym coverage keeps it just shy of perfect on keywords.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — 'Design, review, and refactor Neo4j graph data models', 'migrating relational/document schemas to graph', 'detecting anti-patterns (generic labels, supernodes, missing constraints)', 'designing intermediate nodes', 'enforcing schema with constraints and indexes' — with comprehensive coverage.	5 / 5
Completeness	Explicitly answers both 'what' (design/review/refactor graph data models) and 'when' ('Use when choosing node labels vs relationship types vs properties, migrating...'), plus concrete negative triggers ('Does NOT handle... use neo4j-cypher-skill').	5 / 5
Trigger Term Quality	Strong natural terms ('Neo4j graph data models', 'node labels vs relationship types vs properties', 'supernodes', 'constraints and indexes'), but missing common synonyms a user might casually say (e.g. 'graph schema', 'modeling') and no file-extension-style keyword; a few natural terms missing.	4 / 5
Distinctiveness Conflict Risk	Clear niche (graph data modeling) with explicit boundary statements routing Cypher, Spring Data, GraphQL, and import work to four named sibling skills, minimizing conflict risk.	5 / 5
	Total	19 / 20 Passed

Validation

81%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 13 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning
relative_links	Relative link issues: 1 missing	Warning
referenced_paths_exist	Referenced path issues: 2 missing	Warning

	Total	13 / 16 Passed

Repository: neo4j-contrib/neo4j-skills
Path: neo4j-modeling-skill/SKILL.md
Commit: 02ad354

Reviewed: 3 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.