In this post, we’ll try to answer these questions. After some initial exploration, the Skills feature feels to me like a user-wide (and potentially organization-wide) file-based form of procedural memory, where you store instructions, best practices, and usage patterns for how the LLM should interact with specific tools or tasks.
Individual skills are organized folders containing instructions, scripts, and resources that Claude can load dynamically to improve its performance on specialized tasks. Most examples so far showcase Python code execution, demonstrating how Skills can automate or extend workflows directly within Claude’s environment. Skills can exist at different levels of complexity, ranging from simple instruction-based workflows to fully featured modular capabilities that combine code, metadata, and resources. At their core, each Skill is a folder that packages instructions and optional scripts, allowing Claude to dynamically load the right context for a task. For example, a basic Skill might only include a short description and markdown-based guidance, while a more advanced one could bundle reference files and executable scripts for repeatable automation across tools or MCP servers. Here is an example of a SKILL.md file.
=== Level 1
---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, and merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---
=== Level 2
# PDF Processing
## Quick start
Use pdfplumber to extract text from PDFs:
```python
import pdfplumber
with pdfplumber.open("document.pdf") as pdf:
text = pdf.pages[0].extract_text()
```
=== Level 3
## When to Load Reference Documentation
Load the appropriate reference file when:
### references/pdfplumber-api.md
* You need details on all available methods for extracting text, tables, or metadata.
* You want examples of using `extract_text()`, `extract_tables()`, or layout analysis features.
* You're troubleshooting inconsistent extraction results or bounding box coordinates.Each skill has three levels or types of content that it can contain.
Level 1 provides concise metadata that’s always available to the LLM for discovery, helping Claude know when a Skill applies. Level 2 adds procedural instructions that load only when relevant, giving Claude task-specific know-how without consuming context unnecessarily and is available as the SKILL.md file. Level 3 introduces supporting resources and executable scripts, enabling deterministic operations and richer automation. They are additional files that are mentioned in the SKILL.mdfile so that the LLM knows which file to open and when. Together, this progressive structure keeps context use efficient while unlocking increasingly powerful, specialized behavior as needed.
While most examples showcase Skills with Python code execution, they are not limited to Python code execution. They can also define reusable instructions and structured processes for working with other available tools or MCP servers, making them a flexible way to teach Claude how to perform specific work more effectively.
Improving Cypher knowledge of LLMs
At the moment I’m affiliated with Neo4j and therefore we will use it as an example in our blog post. Most LLMs still use outdated and deprecated syntax and aren’t familiar with the latest Cypher patterns, which often leads to common errors. In this post, we’ll build a Claude Skill that improves an LLM’s ability to generate Cypher, whether you use MCP Cypher server or Python code execution to give the LLM the ability to fetch information from Neo4j.
One nice thing is that you can use Claude to help you create a Skill. Just keep in mind that it’s quite token intensive, and I hit the Pro version limits a couple of times.
My prompt instructed the model to use web search to learn about syntax deprecation since Neo4j 5.0, include the updated subquery format, and handle quantified path patterns. LLMs often struggle with this because most Cypher examples available online were written before Neo4j 5.0. I also added several usage patterns, such as requiring the model to apply a filter before sorting to ensure that the property being sorted is not null (Although it seems latest Claude models don’t have this problem anymore).
After a few iterations, I developed the following Claude Skill. The idea was to focus only on the read queries, so I intentionally left out any write or index syntax changes.
The skill is available on GitHub.
Level 1
The Level 1 metadata defines the identity and purpose of the Skill so that Claude can recognize when to activate it. It provides a high-level summary of what the Skill does and why it’s useful, making it discoverable across projects that deal with Cypher generation or Neo4j query validation. By keeping this information lightweight and always loaded, Claude can quickly match prompts involving Cypher or Neo4j to this Skill without needing to parse detailed instructions first.
---
name: neo4j-cypher-guide
description: Comprehensive guide for writing modern Neo4j Cypher read queries.
Essential for text2cypher MCP tools and LLMs generating Cypher queries.
Covers removed/deprecated syntax, modern replacements, CALL subqueries for reads, COLLECT patterns, sorting best practices, and Quantified Path Patterns (QPP) for efficient graph traversal.
---It’s conceptually similar to a tool description as it tells the model what the Skill does, when to use it, and what kind of tasks it’s relevant for. The main difference is that Skill execution simply opens a file containing procedural memory, which are instructions for usage patterns, instead of invoking a tool. However, you could implement such a tool that handles memory as well (for example, if you wanted to store such procedural instructions in a database instead of a file).
Level 2
At Level 2, the skill moves beyond a simple capability declaration and includes procedural knowledge as the concrete methods for performing a task correctly. When Claude detects a user request that matches a skill’s trigger (defined in Level 1), it dynamically reads the corresponding SKILL.md file from disk. The file is loaded only when needed, keeping the context lightweight while still providing detailed instructions.
A good SKILL.md file doesn’t just describe what the skill can do — it shows how to do it safely and correctly. It usually begins with short procedural checks and principles that serve as the model’s operating rules. These define what to avoid, what to prefer, and what patterns represent modern best practice. For this example, the skill focuses on generating modern Neo4j Cypher queries. It starts by listing outdated syntax to avoid and by establishing clear generation rules that enforce consistency:
This skill helps generate Neo4j Cypher read queries using modern syntax patterns and avoiding deprecated features. It focuses on efficient query patterns for graph traversal and data retrieval.
## Quick Compatibility Check
When generating Cypher queries, immediately avoid these REMOVED features:
- ❌ `id()` function → Use `elementId()`
- ❌ Implicit grouping keys → Use explicit WITH clauses
- ❌ Pattern expressions for lists → Use pattern comprehension or COLLECT subqueries
- ❌ Repeated relationship variables → Use unique variable names
- ❌ Automatic list to boolean coercion → Use explicit checks
## Core Principles for Query Generation
1. **Use modern syntax patterns** - QPP for complex traversals, CALL subqueries for complex reads
2. **Optimize during traversal** - Filter early within patterns, not after expansion
3. **Always filter nulls when sorting** - Add IS NOT NULL checks for sorted properties
4. **Explicit is better than implicit** - Always use explicit grouping and type checking
Finally, the SKILL.md defines when to pull in additional reference files. This tells Claude when to fetch deeper context such as migration guides, subquery techniques, or path optimization notes, but only if the task calls for it.
## When to Load Reference Documentation
Load the appropriate reference file when:
### references/deprecated-syntax.md
- Migrating queries from older Neo4j versions
- Encountering syntax errors with legacy queries
- Need complete list of removed/deprecated features
### references/subqueries.md
- Working with CALL subqueries for reads
- Using COLLECT or COUNT subqueries
- Handling complex aggregations
- Implementing sorting with null filtering
### references/qpp.md
- Optimizing variable-length path queries
- Need early filtering during traversal
- Working with paths longer than 3-4 hops
- Complex pattern matching requirementsAfter defining its rules, the skill demonstrates how to apply them through short examples that model correct behavior. These snippets aren’t arbitrary, but they show the actual procedural knowledge the model uses when generating queries.
### For Aggregations
Use COUNT{}, EXISTS{}, and COLLECT{} subqueries:
```cypher
MATCH (p:Person)
WHERE count{(p)-[:KNOWS]->()} > 5
RETURN p.name,
exists{(p)-[:MANAGES]->()} AS isManager
```
### For Complex Read Operations
Use CALL subqueries for sophisticated data retrieval:
```cypher
MATCH (d:Department)
CALL (d) {
MATCH (d)<-[:WORKS_IN]-(p:Person)
WHERE p.salary IS NOT NULL // Filter nulls
WITH p ORDER BY p.salary DESC
LIMIT 3
RETURN collect(p.name) AS topEarners
}
RETURN d.name, topEarners
```
## Common Query Transformations
### Counting Patterns
```cypher
// Old: RETURN size((n)-[]->())
// Modern: RETURN count{(n)-[]->()}
```
### Checking Existence
```cypher
// Old: WHERE exists((n)-[:REL]->())
// Modern: WHERE EXISTS {MATCH (n)-[:REL]->()}
// Also valid: WHERE exists{(n)-[:REL]->()}
```In short, a Level 2 skill defines a clear, step-by-step procedure inside SKILL.md: it sets compatibility checks, encodes the method with examples, and specifies when to reach for extra context.
Level 3
At Level 3, the LLM has the ability to expand its own context intelligently. Instead of relying only on the main SKILL.md, Claude can decide which supporting files to load based on what the task requires. For example, if a user prompt involves legacy syntax, it can open references/deprecated-syntax.md; if it’s about aggregations or subqueries, it can bring in references/subqueries.md; and for traversal optimizations, it can load references/qpp.md. These files remain static markdown, but Claude now has the autonomy to assemble exactly the context it needs from them rather than depending on a single entry point.
Level 3 can also include executable files. While not present in this skill, Python scripts could live alongside the markdown references, for instance, a validate_syntax.py or generate_query.py utility. In that case, Claude could both read procedural guidance and call the executable to perform concrete operations such as validation, transformation, or quick computation.
In short, Level 3 adds contextual autonomy and optional execution. Claude can decide which reference materials to load to reason more effectively, and, if available, it can invoke supporting executables to act on that reasoning.
P.s. I’m planning to write a blog post soon on how to add a Neo4j skill for Python code execution.
Example usage
We can test our Cypher skill by attaching an Cypher MCP server. We’ll use a demo database named companies , which contains information about organizations, people, and such. You can set it up with the following MCP configuration.
{
"mcpServers": {
"neo4j-database": {
"command": "uvx",
"args": [ "[email protected]", "--transport", "stdio" ],
"env": {
"NEO4J_URI": "neo4j+s://demo.neo4jlabs.com",
"NEO4J_USERNAME": "companies",
"NEO4J_PASSWORD": "companies",
"NEO4J_DATABASE": "companies"
}
}
}
}
Let’s give it an example question!
In this example, the model first determined that it needed to retrieve the graph schema. To follow best practices, it then loaded the Neo4j guide skill before generating the Cypher query. We can see that it used the QPP pattern, the recommended approach for complex traversals. However all these benefits of using skills come at a cost of increased cost and latency.
We can test it without the skill as well to see the difference.
Without the skill, the LLM directly generated the Cypher and used the old syntax for complex traversals, which can be up to 1000x slower.
Summary
Skills feel like a natural next step in the broader move toward standardization and reusability within the agentic ecosystem. They are essentially modular, file-based building blocks for procedural memory, a way to teach models how to work more consistently with clear, reusable guidance that can be shared across projects or teams. In the Neo4j context, that means we can finally give LLMs a reliable reference for modern Cypher syntax and best practices, instead of hoping they recall scattered examples from outdated sources.
At the same time, Skills are still early. They add another layer of complexity and a bit of latency, since each step involves fetching, loading, and interpreting additional files. In a sense, they are just a variant of tools, a structured way to store and reuse instructions rather than to execute code directly. It will be interesting to see how the boundary evolves between what belongs in the system prompt and what should live inside a Skill.
Either way, this is a solid move in the right direction. It pushes the ecosystem toward more modular, interpretable, and reusable agent behavior. As with everything in this fast-moving space, it is still new, so for now we will just have to see what pans out.
The Cypher skill is available on GitHub.
