neo4j-genai-plugin-skill

Q: How do I install neo4j-genai-plugin-skill?

Run npx skills add https://github.com/neo4j-contrib/neo4j-skills --skill neo4j-genai-plugin-skill in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/neo4j-genai-plugin-skill/ (personal) or .claude/skills/neo4j-genai-plugin-skill/ (project).

Q: Which AI agents can use neo4j-genai-plugin-skill?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Q: Is neo4j-genai-plugin-skill safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Q: Who maintains neo4j-genai-plugin-skill?

It is published by neo4j-contrib in neo4j-contrib/neo4j-skills. It has 819 recorded installs.

by neo4j-contribAI & Agents

Use Neo4j GenAI Plugin ai.text. functions and procedures for in-Cypher embedding generation, text completion, structured output, chat, tokenization, and batch ingestion. Covers ai.text.embed(), ai.text.embedBatch(), ai.text.completion(), ai.text.structuredCompletion(), ai.text.aggregateCompletion(), ai.text.chat(), ai.text.tokenCount(), ai.text.chunkByTokenLimit(), and provider configuration for OpenAI, Azure OpenAI, VertexAI, and Amazon Bedrock. Requires CYPHER 25. Replaces deprecated genai.vector.encode(). Use when writing pure-Cypher GraphRAG, embedding nodes in-graph, generating structured maps from prompts, or calling LLMs inside Cypher queries. Does NOT handle neo4j-graphrag Python library pipelines — use neo4j-graphrag-skill. Does NOT handle vector index creation/search — use neo4j-vector-index-skill.

Installs: 819
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/neo4j-contrib/neo4j-skills --skill neo4j-genai-plugin-skill

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads neo4j-genai-plugin-skill automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

When to Use

Generating embeddings inside Cypher without external Python (ai.text.embed())
Batch-embedding nodes/chunks during ingestion (ai.text.embedBatch())
Calling LLMs directly in Cypher for completions or GraphRAG (ai.text.completion())
Extracting structured JSON maps from LLM inside Cypher (ai.text.structuredCompletion())
Aggregating LLM summaries over grouped rows (ai.text.aggregateCompletion())
Stateful chat sessions in Cypher (ai.text.chat())
Counting tokens or chunking text by token limit (ai.text.tokenCount(), ai.text.chunkByTokenLimit())

When NOT to Use

Python-based GraphRAG pipelines (VectorCypherRetriever, HybridCypherRetriever) → neo4j-graphrag-skill
Vector index CREATE / kNN search / SEARCH clause → neo4j-vector-index-skill
GDS embeddings (FastRP, Node2Vec) → neo4j-gds-skill
Fulltext / keyword search → neo4j-cypher-skill

Prerequisites

CYPHER 25 required for all ai.* functions. Two ways to enable:

// Per-query prefix (self-managed, no admin rights needed):
CYPHER 25 MATCH (n:Chunk) ...

// Per-database default (admin; applies to all sessions):
ALTER DATABASE neo4j SET DEFAULT LANGUAGE CYPHER 25

Installation:

Aura: GenAI plugin enabled by default — no action needed
Self-managed JAR: copy plugin JAR to plugins/ directory
Docker: --env NEO4J_PLUGINS='["genai"]'

Provider Config Quick Reference

All ai.text.* functions accept a configuration :: MAP as last argument.

Provider string	Required keys	Notes
`'openai'`	`token`, `model`	`token` = OpenAI API key
`'azure-openai'`	`token`, `resource`, `model`	`token` = OAuth2 bearer; `resource` = Azure resource name
`'vertexai'`	`model`, `project`, `region`, `token` or `apiKey`	`publisher` defaults to `'google'`
`'bedrock-titan'`	`model`, `region`, `accessKeyId`, `secretAccessKey`	Embedding only
`'bedrock-nova'`	`model`, `region`, `accessKeyId`, `secretAccessKey`	Completion only

Optional for all: vendorOptions :: MAP passes provider-specific extras (e.g. { dimensions: 1024 } for OpenAI).

❌ Never hardcode API key literals. ✅ Always use $param passed via driver parameters dict.

Full provider config table → references/providers.md

Embedding

Single embed [2025.11]

CYPHER 25
MATCH (c:Chunk)
WHERE c.embedding IS NULL
WITH c
CALL {
  WITH c
  SET c.embedding = ai.text.embed(c.text, 'openai', {
    token: $openaiKey,
    model: 'text-embedding-3-small'
  })
} IN TRANSACTIONS OF 500 ROWS

ai.text.embed() returns VECTOR — directly storable and queryable in a vector index.

Batch embed procedure [2025.11]

CYPHER 25
MATCH (c:Chunk) WHERE c.embedding IS NULL
WITH collect(c) AS chunks
UNWIND chunks AS c
WITH c.text AS text, c AS node
CALL ai.text.embedBatch(text, 'openai', { token: $openaiKey, model: 'text-embedding-3-small' })
YIELD index, resource, vector
MATCH (c:Chunk {text: resource})
SET c.embedding = vector

Procedure signature: CALL ai.text.embedBatch(resource, provider, config) YIELD index, resource, vector

List configured embed providers

CYPHER 25
CALL ai.text.embed.providers()
YIELD name, requiredConfigType, optionalConfigType, defaultConfig
RETURN name, requiredConfigType

Text Completion [2025.11]

CYPHER 25
RETURN ai.text.completion(
  'Summarize: ' + $text,
  'openai',
  { token: $openaiKey, model: 'gpt-4o-mini' }
) AS summary

Returns STRING.

Aggregate completion — summarize across rows [2026.03]

CYPHER 25
MATCH (c:Chunk)-[:PART_OF]->(a:Article {id: $articleId})
RETURN ai.text.aggregateCompletion(
  c.text,
  'Summarize the following article chunks in 3 sentences',
  'openai',
  { token: $openaiKey, model: 'gpt-4o-mini' }
) AS summary

value parameter = each row's STRING fed to the LLM. Uses toString() for non-string values.

Pure-Cypher GraphRAG Pattern

Embed question → vector search → graph traverse → LLM completion — all in one Cypher query:

CYPHER 25
WITH ai.text.embed($question, 'openai', { token: $openaiKey, model: 'text-embedding-3-small' }) AS qEmbedding
MATCH (chunk:Chunk)
  SEARCH chunk IN (VECTOR INDEX chunk_embedding FOR qEmbedding LIMIT 10) SCORE AS score
// SEARCH preferred on 2026.x; db.index.vector.queryNodes() deprecated 2026.04 — SEARCH syntax → neo4j-vector-index-skill
MATCH (chunk)<-[:HAS_CHUNK]-(article:Article)
OPTIONAL MATCH path = shortestPath((article)-[*..3]-(other:Article))
WITH chunk, article, collect(DISTINCT other.title) AS related, score
ORDER BY score DESC LIMIT 5
WITH collect(chunk.text + '\n[Source: ' + article.title + ']') AS context, $question AS question
RETURN ai.text.completion(
  'Answer based on context:\n' + reduce(s='', c IN context | s + c + '\n') + '\nQuestion: ' + question,
  'openai',
  { token: $openaiKey, model: 'gpt-4o-mini' }
) AS answer

Key insight (Bergman): shortest path between seed nodes surfaces relationships not visible from direct neighbors alone.

Structured Output [2026.02]

Returns MAP — directly storable as node properties or used downstream in Cypher.

CYPHER 25
MATCH (p:Product {id: $productId})
WITH p,
  ai.text.structuredCompletion(
    'Extract key attributes from: ' + p.description,
    {
      type: 'object',
      properties: {
        category: { type: 'string' },
        tags: { type: 'array', items: { type: 'string' } },
        priceRange: { type: 'string', enum: ['budget', 'mid', 'premium'] }
      },
      required: ['category', 'tags', 'priceRange'],
      additionalProperties: false
    },
    'openai',
    { token: $openaiKey, model: 'gpt-4o-mini' }
  ) AS extracted
SET p.category = extracted.category,
    p.priceRange = extracted.priceRange
WITH p, extracted.tags AS tags
UNWIND tags AS tag
MERGE (t:Tag {name: tag})
MERGE (p)-[:TAGGED]->(t)

Aggregate structured completion — extract across multiple rows [2026.03]

CYPHER 25
MATCH (:User {id: $userId})-[:ORDERED]->(o:Order)-[:CONTAINS]->(p:Product)
RETURN ai.text.aggregateStructuredCompletion(
  p.name + ': ' + p.category,
  'Build a shopping profile for this user',
  {
    type: 'object',
    properties: {
      preferredCategories: { type: 'array', items: { type: 'string' } },
      spendingTier: { type: 'string', enum: ['economy', 'standard', 'premium'] }
    },
    required: ['preferredCategories', 'spendingTier']
  },
  'openai',
  { token: $openaiKey, model: 'gpt-4o-mini' }
) AS profile

Chat [2025.12]

Supported providers: openai and azure-openai only.

// Start new conversation (chatId = null → new session)
CYPHER 25
WITH ai.text.chat(
  'Hello, who are you?',
  null,
  'openai',
  { token: $openaiKey, model: 'gpt-4o-mini' }
) AS result
RETURN result.message AS reply, result.chatId AS sessionId

// Continue conversation (pass returned chatId)
CYPHER 25
WITH ai.text.chat(
  'What did I just ask you?',
  $chatId,
  'openai',
  { token: $openaiKey, model: 'gpt-4o-mini' }
) AS result
RETURN result.message AS reply, result.chatId AS sessionId

Returns MAP { message: STRING, chatId: STRING }. Store chatId to continue session.

Tokenization & Chunking [2026.04]

// Count tokens before sending to LLM
CYPHER 25
RETURN ai.text.tokenCount($text, 'openai', { token: $openaiKey, model: 'gpt-4o-mini' }) AS tokenCount

// Chunk text by token limit (no external dependencies)
CYPHER 25
UNWIND ai.text.chunkByTokenLimit($longText, 512, 'gpt-4', 50) AS chunk
MERGE (c:Chunk { text: chunk })

// List providers supporting tokenCount
CYPHER 25
CALL ai.text.tokenCount.providers() YIELD name, requiredConfigType
RETURN name, requiredConfigType

Signatures:

ai.text.tokenCount(input, provider, configuration = {}) :: INTEGER — provider-driven tokenizer; uses provider config (token/model). Local tokenizer for 'openai' (no API call); free API call for 'Bedrock' and 'VertexAI'.
ai.text.chunkByTokenLimit(input, limit, model = 'gpt-4', overlap = 0) :: LIST<STRING> — local OpenAI tokenizer keyed off model; no provider call, no token required. Chunks by newlines, then spaces, then token count. Set limit below provider max to leave room for prompt overhead.

ai.text.embedBatch [2026.04] supports maxBatchSize (config key) to cap data per API request — defaults to 8192 for 'openai' and 'azure-openai'; no default for 'vertexai' (set if hitting token-limit errors).

Write Gate

SET node.embedding = ai.text.embed(...) and SET node.* = ai.text.structuredCompletion(...) write to the graph.

Before bulk writes:

Count nodes first: MATCH (c:Chunk) WHERE c.embedding IS NULL RETURN count(c)
Verify config with one test node before batch
Use CALL { ... } IN TRANSACTIONS OF 500 ROWS for batches > 1000 nodes
Require explicit confirmation before executing

Deprecated — Do NOT Use

Old function	Replacement
`genai.vector.encode()` [deprecated]	`ai.text.embed()`
`genai.vector.encodeBatch()` [deprecated]	`CALL ai.text.embedBatch()`
`genai.vector.listEncodingProviders()` [deprecated]	`CALL ai.text.embed.providers()`

Common Errors

Error	Cause	Fix
`Unknown function 'ai.text.embed'`	Missing CYPHER 25 prefix OR plugin not installed	Add `CYPHER 25` prefix; verify plugin installed
`Cypher version not supported`	Using `CYPHER 25` on Neo4j < 5.20 or missing plugin	Upgrade Neo4j; ensure GenAI plugin loaded
`Configuration key 'token' missing`	Provider config map incomplete	Check required keys for provider (see table above)
`null` returned from embed	Wrong model name or provider auth failed	Test with `RETURN ai.text.embed('test', 'openai', {token:$k, model:'text-embedding-3-small'})` standalone
`Unsupported provider`	Provider string typo (case-sensitive, lowercase)	Use `'openai'` not `'OpenAI'`; run `CALL ai.text.embed.providers()`
`ai.text.chat` fails on VertexAI	Chat only supported on openai/azure-openai	Switch to openai/azure-openai for chat

Checklist

CYPHER 25 prefix present on every ai.text.* query
GenAI plugin installed (Aura: automatic; self-managed: JAR in plugins/)
API key passed as $param, never as literal string
model key explicit in config (no silent defaults)
Provider string lowercase ('openai', 'vertexai', 'bedrock-titan')
Bulk writes use IN TRANSACTIONS OF 500 ROWS; count target nodes first
genai.vector.encode() replaced with ai.text.embed() [2025.11+]
Chat sessions: store returned chatId for continuation; only openai/azure-openai supported
Structured output schema uses additionalProperties: false to prevent hallucination keys

References

Full provider config — all required/optional keys per provider
Official docs
API reference

FAQ

What does the neo4j-genai-plugin-skill skill do?

How do I install neo4j-genai-plugin-skill?

Run npx skills add https://github.com/neo4j-contrib/neo4j-skills --skill neo4j-genai-plugin-skill in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/neo4j-genai-plugin-skill/ (personal) or .claude/skills/neo4j-genai-plugin-skill/ (project).

Which AI agents can use neo4j-genai-plugin-skill?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is neo4j-genai-plugin-skill safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains neo4j-genai-plugin-skill?

It is published by neo4j-contrib in neo4j-contrib/neo4j-skills. It has 819 recorded installs.

More from neo4j-contrib/neo4j-skills

View all →

neo4j-cypher-skill

neo4j-contrib/neo4j-skills

Generates, optimizes, and validates Cypher 25 queries for Neo4j 2025.x and 2026.x. Use when writing new Cypher queries, optimizing slow queries, graph pattern matching, vector or fulltext search, subqueries, or batch writes. Covers MATCH, MERGE, CREATE, WITH, RETURN, CALL, UNWIND, FOREACH, LOAD CSV, SEARCH, expressions, functions, indexes, and subqueries. Does NOT handle driver migration or API changes — use neo4j-migration-skill. Does NOT cover DB administration or server ops — use neo4j-cli-tools-skill.

Backend & APIs1.5K installs

neo4j-modeling-skill

neo4j-contrib/neo4j-skills

Design, review, and refactor Neo4j graph data models. Use when choosing node labels vs relationship types vs properties, migrating relational/document schemas to graph, detecting anti-patterns (generic labels, supernodes, missing constraints), designing intermediate nodes for n-ary relationships, enforcing schema with constraints and indexes, or assessing an existing model against graph modeling best practices. Does NOT handle Cypher query authoring — use neo4j-cypher-skill. Does NOT handle Spring Data Neo4j entity mapping — use neo4j-spring-data-skill. Does NOT handle GraphQL type definitions — use neo4j-graphql-skill. Does NOT handle data import — use neo4j-import-skill.

Backend & APIs1.2K installs

neo4j-graphrag-skill

neo4j-contrib/neo4j-skills

Build GraphRAG retrieval pipelines on Neo4j using the neo4j-graphrag Python package (v1.22.0+). Covers retriever selection (VectorRetriever, HybridRetriever, VectorCypherRetriever, HybridCypherRetriever, Text2CypherRetriever, ToolsRetriever), external vector DB retrievers (Weaviate, Pinecone, Qdrant), retrievalquery Cypher fragments, queryparams, filters, GraphRAG pipeline wiring (GraphRAG + LLM + prompt), all LLM providers (OpenAI, Anthropic, Gemini/VertexAI, Bedrock, Cohere, Mistral, Ollama), embedder setup, index creation, token usage tracking, Cypher 25 SEARCH clause, and LangChain/LlamaIndex integration. Does NOT handle KG construction — use neo4j-document-import-skill. Does NOT handle plain vector search — use neo4j-vector-index-skill. Does NOT handle GDS analytics — use neo4j-gds-skill. Does NOT handle agent memory — use neo4j-agent-memory-skill.

AI & Agents1.1K installs

neo4j-driver-python-skill

neo4j-contrib/neo4j-skills

Neo4j Python Driver v6 — driver lifecycle, executequery, managed and explicit transactions, async (AsyncGraphDatabase), result handling, data type mapping, error handling, UNWIND batching, connection pool tuning, and causal consistency. Use when writing Python code that connects to Neo4j via GraphDatabase.driver, executequery, executeread, executewrite, AsyncGraphDatabase, neo4j.Result, or RoutingControl. Package name is neo4j (not neo4j-driver) since v6. Python =3.10 required. Does NOT handle Cypher query authoring — use neo4j-cypher-skill. Does NOT cover driver upgrades or breaking changes — use neo4j-migration-skill. Does NOT cover GraphRAG pipelines (neo4j-graphrag package) — use neo4j-graphrag-skill.

Code Quality & Workflow984 installs

neo4j-document-import-skill

neo4j-contrib/neo4j-skills

Ingests unstructured and semi-structured documents into Neo4j as a knowledge graph. Use when chunking PDFs, HTML, plain text, or Markdown; extracting entities and relationships from text with an LLM (SimpleKGPipeline, neo4j-graphrag); loading JSON via apoc.load.json; building Document→Chunk→Entity graph structures; or connecting LangChain/LlamaIndex document loaders to Neo4j. Covers neo4j-graphrag SimpleKGPipeline, LLM Graph Builder web UI, entity resolution, chunking strategies, and graph schema design for RAG pipelines. Does NOT handle structured CSV/relational import — use neo4j-import-skill. Does NOT handle GraphRAG retrieval after ingestion — use neo4j-graphrag-skill. Does NOT handle vector index creation — use neo4j-vector-search-skill.

AI & Agents934 installs

neo4j-query-tuning-skill

neo4j-contrib/neo4j-skills

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.

916 installs

Popular ai & agents skills

View category →

google-agents-cli-publish

google/agents-cli

This skill should be used when the user wants to "publish an agent", "publish my ADK agent", "register an agent with Gemini", "publish to Gemini" (formerly Gemini Enterprise), or needs guidance on the agents-cli publish gemini command. Also use when the user wants to "manage agents in Agent Registry", "list/update/delete registered agents", or "register an MCP server". Covers ADK vs A2A registration modes, programmatic and interactive usage, flag reference, auto-detection from deployment metadata, Agent Registry fleet management, and troubleshooting. Part of the agents-cli skills suite. Do NOT use for deployment (use google-agents-cli-deploy).

AI & Agents513.9K installs

google-agents-cli-eval

google/agents-cli

This skill should be used when the user wants to "run an evaluation", "evaluate my agent", "evaluate my ADK agent", "write an eval dataset", "analyze eval failures", "compare eval results", "optimize agent", or needs guidance on the Gemini platform eval methodology and the Quality Flywheel. Covers eval metrics, dataset schema, LLM-as-judge scoring, and common failure causes. Applies to any agents-cli project, whatever framework the agent is written in. Do NOT use for agent API code patterns (ADK: use google-agents-cli-adk-code), deployment (use google-agents-cli-deploy), or project scaffolding (use google-agents-cli-scaffold).

AI & Agents513.5K installs

skill-creator

anthropics/skills

Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.

OfficialAI & Agents416.4K installs

codex-pet

prime-skills/runcomfy-agent-skills

Codex Pet generator on RunComfy. Build a Codex-compatible Codex Pet spritesheet.webp + pet.json from a single reference image, drop it into ${CODEXHOME:-$HOME/.codex}/pets/ / and Codex picks it up as a custom Codex Pet next to the 8 built-ins. This skill produces the exact Codex Pet atlas Codex expects (1536x1872 PNG/WebP, 8 cols x 9 rows, 192x208 cells, 9 animation states — idle, running-right, running-left, waving, jumping, failed, waiting, running, review). Calls OpenAI GPT Image 2 edit ONCE via the local RunComfy CLI as runcomfy run openai/gpt-image-2/edit to produce a canonical Codex Pet pose, then assembles all 9 animation rows programmatically with ImageMagick micro-transforms — no Codex Pro, no $imagegen, no OPENAIAPIKEY required, only RUNCOMFYTOKEN. Triggers on "codex pet", "create codex pet", "make codex pet", "hatch codex pet", "/hatch image", "desktop pet codex", "codex pets", "spritesheet.webp", or any explicit ask to build a custom pet for OpenAI Codex.

AI & Agents402.1K installs

full-output-enforcement

leonxlnx/taste-skill

Overrides default LLM truncation behavior. Enforces complete code generation, bans placeholder patterns, and handles token-limit splits cleanly. Apply to any task requiring exhaustive, unabridged output.

AI & Agents401K installs

executing-plans

obra/superpowers

Use when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available

AI & Agents245.7K installs

neo4j-genai-plugin-skill

Install

Install

Describe the task

Review the result

SKILL.md

When to Use

When NOT to Use

Prerequisites

Provider Config Quick Reference

Embedding

Single embed [2025.11]

Batch embed procedure [2025.11]

List configured embed providers

Text Completion [2025.11]

Aggregate completion — summarize across rows [2026.03]

Pure-Cypher GraphRAG Pattern

Structured Output [2026.02]

Aggregate structured completion — extract across multiple rows [2026.03]

Chat [2025.12]

Tokenization & Chunking [2026.04]

Write Gate

Deprecated — Do NOT Use

Common Errors

Checklist

References

FAQ

More from neo4j-contrib/neo4j-skills

Popular ai & agents skills