Introducing Neo4j Agent Skills

Teaching agents the latest Cypher and Neo4j patterns

Did you know that in Cypher 25 you can write this?

CYPHER 25 MATCH REPEATABLE ELEMENTS p = SHORTEST 3
  (alice:Person {name: "Alice"})
  (()-[r:KNOWS]-() WHERE r.since > date("2020-01-01")){1,5}
  (bob:Person {name: "Bob"})
RETURN [n IN nodes(p) | n.name] AS chain,
       length(p) AS hops
ORDER BY hops

Neither did I or probably the LLM you’re using.

That single MATCH packs in SHORTEST 3 to ask for the three shortest paths, walking a REPEATABLE ELEMENTS trail, a quantified path pattern with an inline predicate on the relationship, and a path projection in the RETURN. Most of it landed as part of the GQL alignment in Cypher 25, and your coding agent has not seen any of it.

Claude Code, Cursor, Codex, whichever one you use, will not reach for this syntax because it did not exist when the model was trained. Agents are otherwise very capable at Cypher. They reason about query shape, they pick up your schema quickly, they know the rough surface area of the language. The thing they cannot do is keep up with it. Cypher has moved on a lot in the last two years, GQL alignment has reshaped the surface in non-trivial ways, and the model has no way of knowing what it does not know.

Agent Skills are a nice way of handling exactly this, and there is now a first wave of them for Neo4j.

GitHub – neo4j-contrib/neo4j-skills: Neo4j Skills for Coding and other Agents including Cypher

What is an Agent Skill

A skill is a folder with a SKILL.md at the root, fronted by a short description the agent always sees. The body of SKILL.md loads only when the agent matches the task to the skill. Deeper material in references/ loads only when SKILL.md asks for it.

Progressive disclosure is the trick that lets you encode a lot of opinionated guidance without burning context.

What is in the repo

The Neo4j skills live at neo4j-contrib/neo4j-skills. The repo is community driven, MIT licensed, and the skills are grouped into a few categories so you can pick what you need.

The Cypher skills cover the language itself: writing and optimizing queries, picking the right idioms for your version, and steering the agent away from deprecated syntax.

The driver skills are split per language, one each for Python, JavaScript, Java, .NET and Go, plus a migration skill for upgrades.

Around those sit categories for importing data, AI and search (vector indexes, GraphRAG, agent memory, the Neo4j MCP server), Graph Data Science, and frameworks and platforms like GraphQL, Spring Data, the Aura CLI and the various admin tools.

You can install the whole bundle and let the agent pick what it needs, or pull in only the few that match your stack. We also have them listed on skills.sh so that they are discoverable with find-skill .

Skill for neo4j-contrib/neo4j-skills

There is plenty of room to grow on top of this, and contributions are welcome.

We keep them up to date by running a regular headless Claude Code GitHub action that reviews latest release notes, changelog, and docs changes and creates a PR with proposed updates. The repository has also a skill writing skill in AGENTS.md that we apply as part of that.

A worked example

Say you are wiring up a friend recommendation feature and you want the agent to write the query and the Python around it. With the Cypher skill and the Python driver skill loaded, the agent has both halves: how to express the traversal, and how to run it from the driver.

# Install all Neo4j skills at once
npx skills add neo4j-contrib/neo4j-skills

# Or just the two relevant for this example
npx skills add neo4j-contrib/neo4j-skills/neo4j-cypher-skill
npx skills add neo4j-contrib/neo4j-skills/neo4j-driver-python-skill

The skills CLI auto-detects your agent (Claude Code, Cursor, Cline, Gemini CLI, Codex) and drops the files in the right place. Once the skills are in, no extra ceremony. You just describe the task.

Alternatively you can install the repo as a plugin in Claude Code, Codex or Gemini CLI.

Help build the next wave

The promise here is simple and powerful. The model does not need to be retrained. You just put the right knowledge next to the right task and the agent reaches for it. Give the Neo4j agent skills a spin on a real project and let us know how they land. What works, what misses, where the agent still goes off the rails, which corners of Neo4j deserve a skill of their own.

The repo issues are the fastest way to feed that back, and it is what the next wave gets built on..

GitHub – neo4j-contrib/neo4j-skills: Neo4j Skills for Coding and other Agents including Cypher

---

Introducing Neo4j Agent Skills was originally published in Neo4j Developer Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.