Content
86%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A strong, highly actionable body: an explicit diagnostic runbook with before/after validation, executable Cypher for every common plan problem, and clean deferral to two real reference files. The only weaknesses are minor — slight duplication between the inline operator table and the reference file, and missing verification guidance around the destructive TERMINATE TRANSACTION command.
Suggestions
Trim the inline operator table to only the handful of operators the diagnostic workflow keys on (AllNodesScan, NodeByLabelScan, CartesianProduct, Eager, NodeIndexSeek), deferring the full ~20-row listing entirely to references/plan-operators.md, and collapse the redundant "Executes query?"/"Returns data?" rows in the EXPLAIN vs PROFILE table into one row.
Add a verification step before TERMINATE TRANSACTION / TERMINATE QUERY: confirm the transactionId or queryId comes from SHOW TRANSACTIONS / SHOW QUERIES output (checking currentQuery and username) and, for user-owned sessions, confirm with the user before killing — this closes the validation gap on the skill's one destructive action.
Consider adding a one-line note on the Eager "CALL IN TRANSACTIONS" batch strategy about how to verify batching worked (e.g., re-PROFILE to confirm the Eager operator is gone), mirroring the existing before/after dbHits comparison used elsewhere.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and Neo4j-specific (operator semantics, dbHits thresholds, runtime selection) with almost no explanation of concepts Claude already knows. Minor trims remain: the EXPLAIN/PROFILE table's "Executes query?" and "Returns data?" rows are redundant with each other, and the ~20-row inline operator table partially duplicates references/plan-operators.md. This matches "efficient; minor instances of over-explanation that could be trimmed" rather than the every-token-earns-its-place anchor. | 4 / 5 |
Actionability | Guidance is fully executable throughout: "SHOW INDEXES YIELD name, type, labelsOrTypes, properties, state", "CREATE INDEX person_email IF NOT EXISTS FOR (n:Person) ON (n.email)", "USING INDEX p:Person(email)", "CYPHER 25 runtime=parallel", and complete before/after code pairs for CartesianProduct, Eager, and LIMIT pushdown. Copy-paste-ready commands cover the common cases. | 5 / 5 |
Workflow Clarity | The 5-step "Diagnostic Workflow (Agent Runbook)" is clearly sequenced with explicit checkpoints ("Wait for state = 'ONLINE' before measuring", "Compare dbHits and elapsed ms before/after", "Target: NodeIndexSeek replaces scan operators") and a closing checklist — a genuine fix-and-remeasure feedback loop. It falls short of a 5 because the destructive "TERMINATE TRANSACTION $transactionId" and batch "CALL … IN TRANSACTIONS" are presented without any verification step (e.g., confirming the transactionId from SHOW TRANSACTIONS or checking with the user before killing work), a minor validation gap on destructive operations. | 4 / 5 |
Progressive Disclosure | SKILL.md is a clean overview: summary operator and metrics tables inline, with well-signaled one-level-deep pointers — "Full operator reference → [references/plan-operators.md]" and "Full monitoring reference → [references/stats-and-monitoring.md]" — both verified to exist as substantive files with no further nested references. Content is appropriately split and easy to navigate. | 5 / 5 |
Total | 18 / 20 Passed |