Skip to main content
skill CX Codex

neo4j-query-workload-skill — Claude Code skill: workload testing

The neo4j-query-workload-skill Claude Code skill builds a graph-database query workload one requirement at a time. It runs new queries against the dataset and checks earlier results for regressions.

Apache-2.0 ★ 423 updated 2026-11-16

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add relatedb/relate --skill neo4j-query-workload-skill -a claude-code
Open on GitHub

What neo4j-query-workload-skill does

The skill creates a test workload from an application's real queries, then adds one capability per round. Each new entry runs against the dataset as it is created; round-end validation checks the full workload and compares its results with the previous round.

Work requires seed queries and access to the dataset through a relate store or the NEO4J_URI, NEO4J_USERNAME, and NEO4J_PASSWORD variables. Validation also needs a relate Python wheel/CLI or the Neo4j Python driver that matches the dataset. The skill targets the Cypher 25 surface. Without seed queries, it stops rather than generating a workload from scratch.

The deliverable is workload.adoc, with round history and validated outcomes; scripts/run_workload.py runs the report. This skill does not write or tune individual queries, handle schema design or data import, or cover GDS workloads.

What it helps with

  • grow a graph-dataset query test set in reviewable rounds
  • probe a Cypher runtime for correctness defects and slow paths
  • compare workload validation results across rounds
  • build a performance suite that tracks an application's feature history

Example prompts for the agent

  • Grow the graph database's query workload by adding one requirement per round.
  • Run these real Cypher queries against the dataset and look for defects or regressions.
  • Create a validated query workload and render its rounds in workload.adoc.

How to install neo4j-query-workload-skill

1Skills CLI (Vercel)

npx skills add relatedb/relate --skill neo4j-query-workload-skill -a claude-code

2Manually: put the files in place

~/.claude/skills/skill/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/skill/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about neo4j-query-workload-skill

How do I install neo4j-query-workload-skill in Claude Code?

Run npx skills add relatedb/relate --skill neo4j-query-workload-skill -a claude-code. The skill file is at ~/.claude/skills/skill/SKILL.md.

What does neo4j-query-workload-skill do?

It grows a graph-database query workload from real application queries and validates additions against the dataset. Round-by-round comparison can reveal regressions.

What does neo4j-query-workload-skill need to run?

It needs seed queries and dataset access through a relate store or NEO4J_URI, NEO4J_USERNAME, and NEO4J_PASSWORD. Validation requires a matching relate Python wheel/CLI or the Neo4j Python driver.

Source text

SKILL.md · Apache-2.0
---
name: neo4j-query-workload-skill
description: Grows a graph dataset's query workload the way an application accumulates requirements — a validated base set of real queries, then one new capability per round, each round extending the proven queries and validated against the dataset. Use when generating test-query sets for a graph dataset, probing a Cypher runtime for correctness defects or slow paths, or building a performance suite that reads like the app's feature history. Annotations from each generation source (expected errors, slow budgets) make the validation report a mismatch list, not a red wall. Does NOT write or optimize individual queries — use neo4j-cypher-skill / neo4j-query-tuning-skill. Does NOT cover schema design or data import — use neo4j-modeling-skill / neo4j-import-skill. Does NOT cover GDS workloads — use neo4j-gds-skill.
compatibility: Cypher 25 surface; validation needs the relate Python wheel/CLI or the neo4j Python driver, matching the dataset under test
version: 1.1.0
---

## When to Use

- Growing a test-query workload for a graph dataset in reviewable increments
- Probing a runtime for defects or slow paths with real data, round by round
- Building a perf suite that reads like the application's feature history

## When NOT to Use

- **One query** → `neo4j-cypher-skill` / `neo4j-query-tuning-skill`
- **Schema/import** → `neo4j-modeling-skill` / `neo4j-import-skill`
- **GDS** → `neo4j-gds-skill`

## The core rule

**The workload lives on the dataset's model.** Every query references only labels,
relationship types, and properties present in the schema input. Nothing foreign
enters: no TCK fixtures, no demo shapes, no invented names. Corpus material (TCK,
cheat sheet) is shape *inspiration* for the agent — consulted per round, rewritten
onto real names, never bulk-imported. The TCK shelf is the spec-harness checkout
(`features/tck/`, `features/relate-tck/`, `features/cip-eval/`) or any openCypher
TCK checkout — `references/sources.md` names the paths.

## Inputs

| Input | Sources |
|---|---|
| Schema | `<db>-schema.json` if present; else introspect live (`CALL db.schema.visualization`, label/type/property listing + per-label counts) |
| Seed queries | The app's real queries: docs, blog posts, repo examples, the user's input |
| Dataset access | relate store path or `:memory:`; or `NEO4J_URI`/`NEO4J_USERNAME`/`NEO4J_PASSWORD` |
| Round budget | How many rounds (default: until the coverage backlog is empty or declared out-of-scope) |

No seeds → stop. A workload grown from nothing is synthetic noise.

## The loop

### Round 0 — base

The seed queries, as-is. Validate. This is the application's v1: if a seed already
fails, fix the dataset understanding first — everything grows from a green base.

### Round N — one new requirement

1. **Pick the next capability** from the coverage backlog
   (`references/coverage-map.md` — ordered by dependency: filtering before
   aggregation, piping before subqueries, paths before quantified patterns, writes
   last). Skip a capability only with a recorded reason (missing data type, engine
   gap).
2. **Grow it like a feature request** (`references/generation-recipes.md`):
   - Extend existing workload queries with the capability — the tag listing gains
     paging; the unanswered query gains an aggregation; the engagement read gains a
     subquery. Growth rides on queries already proven in earlier rounds.
   - Add the few base queries that introduce the capability where nothing extends.
   - Let the dataset grow too when the requirement implies it (a synthetic
     `__wl_`-keyed entity per write round, deleted by the same or the next entry).
3. **Validate as you generate**: every new entry runs against the dataset the
   moment it is written — a query that was never executed must never reach the
   workload. Fix or drop failures immediately; the round-end batch validation
   is the regression check, not the first time anything runs.
4. **Annotate expectations at the source**: `expect:"error"` (+kind/detail) for
   deliberate negatives, `expect_ms` for heavy-but-legitimate shapes,
   `expect_slow` for known-slow ones you keep on purpose.
5. **Validate the whole workload** (`references/validation.md`):

```
python3 scripts/run_workload.py workload.jsonl --engine relate --store <path> --out report.json
```

6. **Diff round-over-round**: the report shows what round N found (new statuses vs
   round N−1) and that N−1's entries are unchanged. A previously-green entry turning
   red is a regression finding, the round's headline.

### Stop

When the backlog is empty, or every remaining capability has a recorded reason.
Report the covered matrix, the defect list, and the per-tier/per-round perf table.

## Shape rules — every entry

- `extends` names the entry it grew from (empty for base introductions); the growth
  chain is the artifact's skeleton.
- One statement per entry; parameters for every data literal.
- Writes are idempotent or self-cleaning on `__wl_` synthetic keys.
- Tier is structural and checked against `references/generation-recipes.md` — a
  fixed-length hop count is never "complex".
- Predicates must be able to match data (use the schema's counts); an all-empty
  workload proves nothing.

## Deliverable

`workload.adoc` — readable like a feature history, runnable like the dataset guides:
`== Round 0 — the base queries`, `== Round 1 — paging arrives`, … each entry with its
provenance note (seed / growth operator / capability / TCK-inspiration) and its
validated outcome. `workload_to_adoc.py` renders it from the validated report; the
validator reads the adoc back, so the artifact is the workload.

© relatedb · Apache-2.0 · relatedb/relate

Similar skills

All skills for Testing and QA →

From the same set18

The whole set →
opencode-review-stellar The opencode-review-stellar Claude Code prompt runs a strict maintainability and code-quality review on a Rust pull request. It gathers agent findings but leaves comments and the final verdict to a later pipeline step. CX Codex +1 ★ 423repo stars opencode-review-protocol The opencode-review-protocol Claude Code prompt defines a pull request review workflow. It posts line-specific findings, updates a summary comment, and writes a verdict for CI. CX Codex +1 ★ 423repo stars release-notes A prompt for Claude Code drafts relate release notes from the changelog and commit history. It runs for a tagged release. CX Codex +1 ★ 423repo stars security-review The security-review Claude Code skill reviews code changes for security risks and suggests remediations. It activates for auth or permission changes, secrets and PII handling, public endpoints, and dependency upgrades. CX Codex +1 ★ 423repo stars relate This Claude Code skill guides JVM projects through using Relate as a local graph database with Cypher. It activates when Java or Kotlin code needs to create, query, or embed the database. CX Codex +1 ★ 423repo stars relate This Claude Code skill guides Python work with Relate, an embedded openCypher graph database. It activates for building a local database, running Cypher queries, and handling query results. CX Codex +1 ★ 423repo stars relate This Claude Code skill guides JavaScript and TypeScript work with Relate, a local graph database queried with openCypher. It covers connections, transactions, and result handling. CX Codex +1 ★ 423repo stars rust-reviewer The rust-reviewer skill for Claude Code and Codex reviews Rust code for ownership, lifetimes, and error handling issues. It examines the whole project, including unsafe blocks and idiomatic Rust patterns. CX Codex +1 ★ 423repo stars

Project sponsors

Companies that keep this analytics open