neo4j-graphql-skill
Build and configure a GraphQL API backed by Neo4j using @neo4j/graphql v7 (current) or v5 (LTS). Covers Neo4jGraphQL constructor, getSchema(), assertIndexesAndConstraints(), type definitions with @node, @relationship (IN/OUT/UNDIRECTED), @cypher for custom resolvers, @authorization/@authentication for JWT/JWKS security, auto-generated queries/mutations, OGM programmatic access, subscriptions via CDC, and Apollo Federation. Use when writing typeDefs, securing fields, or wiring Neo4j to Apollo Server. Does NOT handle raw Cypher outside resolvers — use neo4j-cypher-skill. Does NOT cover Spring Data Neo4j entity mapping — use neo4j-spring-data-skill.
91
88%
Does it follow best practices?
Impact
96%
1.10xAverage score across 3 eval scenarios
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 excellent skill description that thoroughly covers specific capabilities, includes abundant natural trigger terms, explicitly states both what the skill does and when to use it, and proactively delineates boundaries with related skills. The negative boundary clauses ('Does NOT...') are a particularly strong feature for disambiguation in a multi-skill environment. The description uses proper third-person voice throughout.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists numerous specific concrete actions and concepts: Neo4jGraphQL constructor, getSchema(), assertIndexesAndConstraints(), type definitions with @node, @relationship, @cypher, @authorization/@authentication, auto-generated queries/mutations, OGM, subscriptions via CDC, and Apollo Federation. | 3 / 3 |
Completeness | Clearly answers both 'what' (build/configure GraphQL API with Neo4j, covering specific decorators, security, OGM, subscriptions, federation) and 'when' ('Use when writing typeDefs, securing fields, or wiring Neo4j to Apollo Server'). Also includes explicit negative boundaries with 'Does NOT' clauses directing to other skills. | 3 / 3 |
Trigger Term Quality | Includes strong natural keywords users would say: 'GraphQL API', 'Neo4j', 'typeDefs', 'Apollo Server', '@neo4j/graphql', 'JWT/JWKS', 'OGM', 'subscriptions', 'Apollo Federation', '@relationship', '@authorization'. These cover the terms a developer working in this space would naturally use. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive with explicit boundary-setting via 'Does NOT handle raw Cypher outside resolvers — use neo4j-cypher-skill' and 'Does NOT cover Spring Data Neo4j entity mapping — use neo4j-spring-data-skill'. This directly addresses potential overlap with related Neo4j skills and creates a clear niche. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a strong, highly actionable skill with excellent executable examples covering the full @neo4j/graphql lifecycle. The workflow is well-sequenced with validation checkpoints and a comprehensive checklist. The main weakness is its length — at 350+ lines with no bundle files, it could benefit from splitting detailed sections (security, OGM, subscriptions) into separate reference files to improve token efficiency and progressive disclosure.
Suggestions
Split detailed sections (Security, OGM, Subscriptions) into separate bundle files (e.g., SECURITY.md, OGM.md) and reference them from the main SKILL.md to reduce token consumption and improve progressive disclosure.
Trim the @relationship full syntax example — the inline direction rule comment and the UNDIRECTED caveat could be condensed since the direction table already covers this in the checklist.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is comprehensive and mostly efficient, but some sections could be tightened. The Connection API explanation, the full @relationship syntax block with inline comments, and the security section are somewhat verbose. However, it avoids explaining basic concepts like what GraphQL or Neo4j are, which is good. | 2 / 3 |
Actionability | Excellent actionability throughout — every section provides executable code examples (JavaScript server setup, GraphQL type definitions, queries, mutations, OGM usage). Install commands are copy-paste ready, and the common errors table provides specific fixes for specific problems. | 3 / 3 |
Workflow Clarity | The skill follows a clear sequential workflow (Install → Server Setup → Directives → Security → Operations → OGM → Subscriptions) with explicit validation steps like wrapping assertIndexesAndConstraints in try/catch, calling ogm.init() before model usage, and the checklist at the end serving as a comprehensive verification step. | 3 / 3 |
Progressive Disclosure | The content is well-organized with clear sections and a logical flow, but it's a long monolithic document (~350+ lines) with no bundle files to offload detailed content. The security section, OGM section, and full directive reference could be split into separate files. External references are provided but only as links to Neo4j docs, not to companion bundle files. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
90%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
Table of Contents
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.