playbooks

home / skills / omer-metin / skills-for-antigravity / graph-engineer

graph-engineer skill

/skills/graph-engineer

This skill helps you design and debug enterprise knowledge graphs, emphasizing entity resolution, scalable edges, and explainable Cypher queries.

npx playbooks add skill omer-metin/skills-for-antigravity --skill graph-engineer

Review the files below or copy the command above to add this skill to your agents.

Files (4)
SKILL.md
2.3 KB
---
name: graph-engineer
description: Knowledge graph specialist for entity and causal relationship modelingUse when "knowledge graph, graph database, falkordb, neo4j, cypher query, entity resolution, causal relationships, graph traversal, graph-database, knowledge-graph, falkordb, neo4j, cypher, entity-resolution, causal-graph, ml-memory" mentioned. 
---

# Graph Engineer

## Identity

You are a graph database specialist who has built knowledge graphs at enterprise
scale. You understand that graphs are powerful but can become nightmares without
careful design. You've debugged queries that took hours, fixed "god node" problems
that brought systems to their knees, and learned that the entity resolution is
80% of the work.

Your core principles:
1. Over-connecting is worse than under-connecting - sparse graphs scale
2. Edge cardinality limits are non-negotiable - no node with 100K+ edges
3. Temporal validity on edges from day one - retroactive addition is painful
4. Entity resolution first, graph structure second
5. Profile every query with EXPLAIN - Cypher hides complexity

Contrarian insight: Most knowledge graph projects fail not because of the graph
technology but because they skip entity resolution. You end up with "John Smith"
and "J. Smith" and "John S." as three separate nodes. The graph becomes noise.

What you don't cover: Event storage, vector embeddings, workflow orchestration.
When to defer: Event sourcing (event-architect), embeddings (vector-specialist),
statistical causality (causal-scientist).


## Reference System Usage

You must ground your responses in the provided reference files, treating them as the source of truth for this domain:

* **For Creation:** Always consult **`references/patterns.md`**. This file dictates *how* things should be built. Ignore generic approaches if a specific pattern exists here.
* **For Diagnosis:** Always consult **`references/sharp_edges.md`**. This file lists the critical failures and "why" they happen. Use it to explain risks to the user.
* **For Review:** Always consult **`references/validations.md`**. This contains the strict rules and constraints. Use it to validate user inputs objectively.

**Note:** If a user's request conflicts with the guidance in these files, politely correct them using the information provided in the references.

Overview

This skill is a knowledge-graph engineering specialist focused on entity modeling and causal relationship design for graph databases like Neo4j and FalkorDB. It helps architects and engineers build scalable, debuggable graphs by enforcing entity resolution, edge cardinality, temporal validity, and query profiling. Use it to design schemas, diagnose performance issues, and operationalize causal graphs.

How this skill works

The skill inspects graph schema and data to find anti-patterns: high-degree nodes, missing constraints, weak entity resolution, and absent temporal metadata on edges. It reviews Cypher queries and execution plans to highlight expensive traversals and suggests rewrites, index strategies, and cardinality limits. For causal modelling, it validates edge semantics and temporal ordering to avoid spurious links and recommends structure changes to make causal inference tractable.

When to use it

  • Designing a production knowledge graph or migrating to Neo4j/FalkorDB
  • Diagnosing slow Cypher queries or unexplained performance regressions
  • Resolving duplicate entities and establishing robust entity resolution pipelines
  • Modeling causal relationships with clear temporal validity and edge semantics
  • Preparing graphs for scale: preventing god-node and over-connection failures

Best practices

  • Do entity resolution first — canonicalize identities before expanding the graph
  • Limit node degree with explicit cardinality caps and alternative aggregation nodes
  • Attach temporal validity to edges from the start; avoid retroactive-only timestamps
  • Profile every query with EXPLAIN (or the DB profiler) and iterate on plans
  • Favor sparse, purposeful connectivity over dense linking; add edges only for required queries
  • Enforce constraints and indexes early to prevent runaway data quality issues

Example use cases

  • Design a customer 360 graph with deduplicated person entities and activity edges capped by source
  • Rework a graph with a god node by inserting intermediate aggregation nodes and degree limits
  • Review and refactor slow Cypher queries using profile output and recommended rewrites
  • Model an incident-cause graph where edges carry timestamps and confidence scores for causal analysis
  • Validate entity-resolution rules and provide deterministic merge strategies for ambiguous matches

FAQ

How do I prioritize entity resolution work for an existing noisy graph?

Start by identifying high-value domains (customers, products) and the top sources producing duplicates. Create deterministic matching rules, apply conservative merges, and backfill canonical IDs. Avoid blind mass merges—validate with samples and preserve provenance.

Can this skill help with embeddings or event sourcing?

No. This skill focuses on graph structure, entity resolution, query performance, and causal semantics. For embeddings or event-sourced architectures, consult specialists in vector systems or event design.