Guide · Agent skill
How to use the Custom graph models agent skill for cognee
Updated · written with AI from the project's own documentation and checked against our catalogue data
This guide explains the cognee-custom-graph-models agent skill, which teaches an AI agent to define your own knowledge graph shape for the cognee library. It is for developers who need fixed node and relationship types, such as people or organizations, instead of cognee's default generic extraction. After reading, you will know how to install the skill, trigger it with plain requests, and avoid the common causes of duplicated nodes and missing edges.
Custom graph modelstopoteretes/cognee · Apache-2.0 Download the skill Quick start
- 1Download and unzip the skill. Download the skill ZIP from the page where you found this guide and unzip it to get SKILL.md.
- 2Place it in a skills folder. Copy the folder to ~/.claude/skills/ for personal use, or to .claude/skills/ in your project. Alternatively, upload it in the Claude apps under Settings → Capabilities → Skills.
- 3Confirm cognee is set up. The skill needs Python and the cognee library already working. It does not install them for you.
- 4Ask for your graph shape in plain words. Describe the entities and relationships you need, such as people, organizations, and reporting lines, and ask the agent to build a graph_model.
- 5Set identity and index fields. Ask the agent to add identity_fields and index_fields metadata to every node type that represents a real-world entity.
- 6Test and debug. Run a small document through cognee.remember and check for duplicated nodes or missing edges, then ask the agent to fix the model.
What does the Custom graph models skill make the agent do?
By default, cognee extracts a generic KnowledgeGraph of entities and relationships from your documents. This skill teaches the agent to write Python classes for node types, typed edges, and identity and search fields, then pass them as graph_model= so the language model fills your own structure.
The skill also covers building such a model from a JSON schema, and debugging problems such as duplicated nodes, missing edges, or InvalidReferenceTypeError.
- Write DataPoint node classes for your domain entities
- Choose identity_fields so the same entity merges into one node
- Choose index_fields so recall can find nodes
- Declare typed Edge fields and FromIdentity references
- Build a model from a JSON schema
- Debug duplicated nodes, missing edges, or InvalidReferenceTypeError
How do you install the skill?
Download the skill ZIP from the page where you found this guide, then unzip it. The skill ships as a single file, SKILL.md. Put the unzipped folder in one of these locations:
- Personal skills folder: ~/.claude/skills/
- Project skills folder: .claude/skills/ inside your project
- Claude apps: upload the skill under Settings → Capabilities → Skills
How do you trigger the skill with a natural request?
You do not need to type the skill name. The skill's description says when it applies, so ask for the task in plain words. Requests that match its description include defining the shape of the graph with graph_model=, writing DataPoint node classes, choosing identity and index fields, declaring typed Edge fields, building a model from a JSON schema, and debugging duplicated nodes or missing edges.
- "Make cognee extract people and their reporting lines as a fixed graph."
- "My cognee graph has the same person as ten separate nodes. Why?"
- "Turn this JSON schema into a cognee graph model."
- "I'm getting InvalidReferenceTypeError when I run cognee.remember. Help me fix the model."
What does a minimal custom graph model look like?
The skill's core example defines a Role node, a Person node that references Role and has a typed edge to other people, and a root PeopleGraph container. The root is marked transparent, so it is not stored and its children take its place. Pass the root to cognee.remember with a custom_prompt.
from typing import Annotated, Literal
import cognee
from cognee.low_level import DataPoint, Edge, FromIdentity
class Role(DataPoint):
name: str
metadata: dict = {"index_fields": ["name"], "identity_fields": ["name"]}
class Person(DataPoint):
name: str
is_a: Annotated[Role, FromIdentity()] | None = None
reports_to: list[Edge["Person", "Person"]] = []
metadata: dict = {"index_fields": ["name"], "identity_fields": ["name"]}
class PeopleGraph(DataPoint):
people: list[Person]
friends_with: list[Edge[Person, Person]] = []
family: list[Edge[Person, Person, Literal["married_to", "sibling_of"]]] = []
metadata: dict = {"index_fields": [], "transparent": True}
await cognee.remember(text, graph_model=PeopleGraph, custom_prompt="Extract every person...")How do identity and index fields prevent duplicates and missing results?
The metadata dict on each node controls three things. identity_fields derives the node id from field values, so the same entity from two chunks or two runs becomes one node. index_fields creates a vector collection for each listed field so recall can find the node. Write metadata explicitly rather than relying on annotation shortcuts, because the source says Embeddable() does not index in its current form.
- Without identity_fields, every node gets a random id, so the same person is duplicated in every chunk and run.
- Without index_fields, the node may never appear in recall.
- Each typed edge endpoint type needs exactly one identity_fields entry.
- Edge[...] must always be a list, not a bare value or an optional bare value.
What requirements and safety notes apply?
The skill requires Python and the cognee library, and it assumes cognee is already set up. According to its metadata, it does not run scripts and does not use the network. It consists of SKILL.md only.
Be aware of these limits from the source. GLiNER extraction raises an error with a custom graph_model. In remote mode after cognee.serve(url), remember() and cognify() do not forward graph_model, so the server builds a generic graph. Define models at module level, because string endpoints do not resolve to classes defined inside a function.
- Requires: Python and the cognee library
- Runs scripts: no
- Uses network: no
- Skill files: SKILL.md
What tips help you avoid common mistakes?
Field names that match DataPoint's own fields, such as id, type, version, metadata, and created_at, are removed from what the LLM sees, so rename them. A subclass that overrides metadata replaces the parent's metadata entirely. Dropping identity_fields only logs a warning, so check your logs.
Always write a custom_prompt. Without one, the generic knowledge-graph prompt is used, and your schema reaches the model only as structured output.
- Rename fields that collide with DataPoint fields
- Define every model at module level
- Make the recalling process import the model classes, since graph completion searches only loaded DataPoint classes
- Check logs for dropped edge rows, which are skipped with a warning
What people use it for
- Building a people graph with fixed roles and reporting relationships for an internal directory
- Modeling organizations and the people who belong to them, so the same company is one node across documents
- Converting an existing JSON schema into cognee graph classes using graph_model_from_spec or graph_schema_to_graph_model
- Diagnosing why a cognee pipeline creates the same person many times or drops relationships
Frequently asked questions
How do I install the cognee custom graph models skill?
Download the skill ZIP from the page where you found this guide and unzip it. Place the folder in ~/.claude/skills/ for personal use or in .claude/skills/ inside a project. In the Claude apps, you can instead upload it under Settings → Capabilities → Skills.
What do I need to use this skill?
You need Python and the cognee library already set up. The skill teaches the agent to write code for cognee and does not install cognee for you. It is only needed when you want to customize the graph schema.
Is the Custom graph models skill free to use?
The source lists the licence as Apache-2.0 for the topoteretes/cognee repository, which contains this skill. Check the repository's licence file for the exact terms that apply to your use.
What are the alternatives to a custom graph model?
The default alternative is cognee's generic extraction, which builds a KnowledgeGraph of entities and relationships without any graph_model. You can also build a model from a JSON schema with graph_schema_to_graph_model or graph_model_from_spec, but those paths cannot express typed Edge fields or FromIdentity references.
Why does my cognee graph have duplicated nodes?
The most likely cause is missing identity_fields in the node's metadata. Without it, each node gets a random id, so the same entity is duplicated across chunks and runs. Add identity_fields to every node type that represents a real-world entity.
What does InvalidReferenceTypeError mean in cognee?
It means your model uses an unsupported FromIdentity or Edge spelling. Supported reference forms are Target, Target | None, list[Target], and list[Target] | None. The error appears during extraction rather than when you define the class, so check the model's declarations.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill is a good fit for Python developers building a cognee pipeline who need a fixed schema for people, organizations, or other domain entities. If you only want to store and query documents with default extraction, or you have no Python experience, you do not need it and should use cognee's default setup.
Download the skill