Tutorial

Prerequisites

Before you begin, make sure you have the following installed and working:

• Docker installed and running (docker --version)
• A coding agent — Claude Code, OpenAI Codex, GitHub Copilot, Cursor, Windsurf, Amazon Kiro, Qoder, or Antigravity
• An API key from either:
  • Anthropic (console.anthropic.com) — default provider
  • OpenAI (platform.openai.com) — alternative

Verify Docker is running:

Setup

Clone and install

Run the full setup. This creates a virtual environment, installs dependencies, starts the PostgreSQL + Apache AGE container, and initializes the graph schema:

Configure environment variables

The setup creates a .env file from the example template. Open it and set your API key:

Verify everything works

Activate the skill

The /build-kg skill is included in the repository and activates automatically:

Your First Knowledge Graph

The fastest way to build a graph is the /build-kg skill command in your coding agent. It runs the entire pipeline automatically: generates an ontology, discovers sources, crawls, chunks, loads, and parses.

In your coding agent, run:

Your coding agent will execute six phases in sequence. Here is what each phase does:

Exploring the Graph

Your knowledge graph is stored in Apache AGE, a PostgreSQL extension that adds Cypher graph queries. Connect with psql or any PostgreSQL client.

Connect to the database

Load the AGE extension and set the search path:

LOAD 'age';
SET search_path = ag_catalog, '$user', public;

Count nodes by type

SELECT * FROM cypher('kg_k8s_net', $$
    MATCH (n)
    RETURN label(n), count(n)
    ORDER BY count(n) DESC
$$) AS (node_type agtype, count agtype);

List all node types

SELECT * FROM cypher('kg_k8s_net', $$
    MATCH (n)
    RETURN DISTINCT label(n)
$$) AS (node_type agtype);

Traverse relationships

SELECT * FROM cypher('kg_k8s_net', $$
    MATCH (a)-[r]->(b)
    RETURN label(a), type(r), label(b), count(*)
    ORDER BY count(*) DESC
    LIMIT 10
$$) AS (from_type agtype, rel_type agtype, to_type agtype, count agtype);

Find specific entities

SELECT * FROM cypher('kg_k8s_net', $$
    MATCH (n)
    WHERE n.name CONTAINS 'Service'
    RETURN n.name, label(n), n.description
    LIMIT 5
$$) AS (name agtype, type agtype, description agtype);

Walk a path

SELECT * FROM cypher('kg_k8s_net', $$
    MATCH path = (a)-[*1..2]->(b)
    WHERE a.name = 'kube-proxy'
    RETURN a.name, b.name, length(path)
    LIMIT 10
$$) AS (from_name agtype, to_name agtype, path_len agtype);

Visualize Your Graph

build-kg-viewer is the visual companion to build-kg. Point it at the same database and explore your graph interactively.

git clone https://github.com/agtm1199/build-kg-viewer.git && cd build-kg-viewer
npm run setup && npm start

Connect using the same database credentials from your .env file. Features include 24+ visualization components, AI-powered chat (natural language to Cypher), dark mode, path finder, graph algorithms, and more.

Next Steps

• Docs — Architecture, configuration, domain profiles, and more.
• Domain profiles — Pre-configured ontologies for specialized domains, or create your own.
• build-kg-viewer — Interactive graph visualization with AI-powered queries.
• GitHub repository — Source code, issues, and contributing guidelines.
• Create a custom domain profile — write your own ontology YAML and set DOMAIN=/path/to/your-profile.yaml in .env.
• Try more topics — /build-kg React architecture patterns, /build-kg machine learning algorithms, /build-kg python async programming.