neo4j-query-tuning-skill

Diagnoses and fixes slow Neo4j Cypher queries by reading execution plans, identifying bad operators (AllNodesScan, CartesianProduct, Eager, NodeByLabelScan), and prescribing fixes (indexes, hints, query rewrites, runtime selection). Use when a query is slow, when EXPLAIN or PROFILE output needs interpretation, when dbHits or pageCacheHitRatio are poor, when cardinality estimation diverges from actuals, or when deciding between slotted/pipelined/parallel runtimes. Covers USING INDEX / USING SCAN / USING JOIN hints, db.stats.retrieve, SHOW QUERIES, SHOW TRANSACTIONS, TERMINATE TRANSACTION. Does NOT write new Cypher from scratch — use neo4j-cypher-skill. Does NOT cover GDS algorithm tuning — use neo4j-gds-skill. Does NOT cover index/constraint creation syntax details — use neo4j-cypher-skill references/indexes.md.

Quality

96%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Quality

Discovery

100%

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

This is an exceptionally well-crafted skill description. It provides highly specific capabilities with concrete technical terms, includes comprehensive trigger conditions via an explicit 'Use when...' clause, and goes above and beyond by defining clear boundaries with 'Does NOT' clauses that reference alternative skills. The description is information-dense without being padded, uses proper third-person voice throughout, and would allow Claude to confidently select or reject this skill from a large pool.

Dimension	Reasoning	Score
Specificity	Lists multiple specific concrete actions: reading execution plans, identifying bad operators (with named examples like AllNodesScan, CartesianProduct), prescribing fixes (indexes, hints, query rewrites, runtime selection), and covers specific commands like USING INDEX, db.stats.retrieve, SHOW QUERIES, etc.	3 / 3
Completeness	Clearly answers both 'what' (diagnoses and fixes slow Neo4j Cypher queries by reading execution plans, identifying bad operators, prescribing fixes) and 'when' (explicit 'Use when...' clause covering slow queries, EXPLAIN/PROFILE interpretation, poor dbHits, cardinality divergence, runtime decisions). Also includes explicit boundary conditions with 'Does NOT' clauses pointing to alternative skills.	3 / 3
Trigger Term Quality	Excellent coverage of natural terms a user would use: 'slow', 'Cypher queries', 'EXPLAIN', 'PROFILE', 'dbHits', 'pageCacheHitRatio', 'cardinality estimation', 'slotted/pipelined/parallel runtimes', 'Neo4j'. These are exactly the terms a developer would mention when facing query performance issues.	3 / 3
Distinctiveness Conflict Risk	Extremely distinctive with a clear niche (Neo4j Cypher query performance tuning) and explicit boundary definitions that actively prevent conflicts by naming the alternative skills for adjacent tasks (neo4j-cypher-skill, neo4j-gds-skill). This is exemplary conflict prevention.	3 / 3
	Total	12 / 12 Passed

Implementation

92%

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

This is an excellent, highly actionable skill that serves as a comprehensive diagnostic runbook for Neo4j query performance. Its strengths are dense, executable code examples, a clear step-by-step workflow with validation checkpoints, and an efficient operator reference table. The only notable weakness is that the content is somewhat long for a single SKILL.md — the operator reference table and monitoring commands could be split into referenced files to improve progressive disclosure, and the referenced bundle files are not provided.

Suggestions

Consider moving the full operator reference table to `references/plan-operators.md` (which is already referenced) and keeping only the most critical bad operators (AllNodesScan, CartesianProduct, Eager, NodeByLabelScan) inline in SKILL.md to reduce length.

Dimension	Reasoning	Score
Conciseness	Every section earns its place — no explanations of what Neo4j or Cypher are, no padding. Tables are dense and scannable. The operator reference is extensive but justified since it's the core value of the skill. Hints like 'Run PROFILE twice' are terse and high-signal.	3 / 3
Actionability	Fully executable Cypher queries throughout, including EXPLAIN/PROFILE examples, index creation syntax, hint syntax (USING INDEX, USING SCAN, USING JOIN), runtime selection, monitoring commands, and even a curl example for the Query API. Every fix pattern includes copy-paste-ready code with before/after comparisons.	3 / 3
Workflow Clarity	The 5-step diagnostic workflow is clearly sequenced with explicit validation checkpoints: baseline plan → check indexes → create missing index → wait for ONLINE → profile after fix → handle stale statistics. The checklist at the end provides a comprehensive verification loop. Feedback loops are present (e.g., 'Wait for state = ONLINE before measuring', 'Compare dbHits before/after').	3 / 3
Progressive Disclosure	References to `references/plan-operators.md` and `references/stats-and-monitoring.md` are well-signaled and one level deep, but no bundle files were provided to confirm they exist. The main file is quite long (~200+ lines) and some content like the full operator reference table could arguably be in a separate reference file, keeping the SKILL.md more focused on the workflow.	2 / 3
	Total	11 / 12 Passed

Validation

90%

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 — 10 / 11 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	10 / 11 Passed

Repository: neo4j-contrib/neo4j-skills
Commit: 66ed0e1

Reviewed: about 23 hours 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.