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

91%

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

82%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.

The body is a strong, executable modeling reference: dense decision tables, copy-paste Cypher, validation checkpoints, and a structured assessment output format. It loses points mainly for repeated 'inspect first' guidance, a modular rather than unified linear workflow, and a missing referenced bundle file.

Suggestions

Create the referenced references/modeling-patterns.md (or remove the link) — the body currently points to a bundle file that does not exist, which breaks progressive disclosure.

De-duplicate the 'inspect the schema before proposing changes' guidance so it lives in one canonical place (e.g., the Inspect Before Designing section) rather than being repeated in Defaults #9 and the Checklist.

Consider moving the full schema-enforcement DDL catalog and the supernode mitigation strategy table into a reference file, keeping SKILL.md as a tighter overview with the decision tables and key examples inline.

Dimension	Reasoning	Score
Conciseness	Largely lean and information-dense (decision tables, executable Cypher, no basic-concept padding), but the 'inspect before changing' guidance is repeated across the Inspect section, default #9, and the checklist, and a few tables could be tightened — efficient with minor over-explanation.	4 / 5
Actionability	Copy-paste-ready Cypher for schema inspection, constraints, indexes, vector indexes, supernode detection, and the bucket pattern, plus concrete decision tables and a structured assessment output template covering the common modeling cases.	5 / 5
Workflow Clarity	Clear sequencing (inspect → apply defaults → enforce schema → assess) with real validation checkpoints ('poll until ONLINE', 'Do NOT use an index until state = ONLINE', 'show + confirm first', severity-based stop/proceed), but it is presented as modular sections rather than a single linear retry-loop workflow, leaving minor checkpoint gaps.	4 / 5
Progressive Disclosure	Well-organized sections with a clearly signaled 'References — Load on demand' block and one-level-deep pointers; however the referenced bundle file references/modeling-patterns.md does not exist in the bundle, and substantial reference-grade material (full DDL catalog, supernode strategies, migration table) is inlined in SKILL.md.	4 / 5
	Total	17 / 20 Passed

Description

100%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.

The description is exemplary: it states concrete capabilities, gives explicit 'Use when' triggers, and disambiguates from four sibling skills with clear 'Does NOT handle' boundaries. Third-person voice is used throughout, with no fluff or over-claims.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — 'Design, review, and refactor', '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', 'enforcing schema with constraints and indexes' — with comprehensive coverage of the domain.	5 / 5
Completeness	Explicitly states the 'what' ('Design, review, and refactor Neo4j graph data models') and the 'when' via a concrete 'Use when ...' clause enumerating trigger scenarios, satisfying both halves with concrete trigger phrases.	5 / 5
Trigger Term Quality	Covers natural domain terms a graph-modeling user would say — 'graph data models', 'node labels', 'relationship types', 'relational/document schemas to graph', 'anti-patterns', 'supernodes', 'constraints', 'indexes', 'intermediate nodes' — including synonyms and phrasings users actually employ.	5 / 5
Distinctiveness Conflict Risk	Occupies a clear niche (Neo4j graph data modeling) and adds four explicit 'Does NOT handle ... — use <sibling-skill>' boundary clauses, minimizing conflict risk with adjacent skills.	5 / 5
	Total	20 / 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: a9a5e78

Reviewed: 6 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.