playbooks

home / skills / jjuidev / jss / gkg

gkg skill

/.claude/skills/gkg

This skill provides semantic code analysis with GitLab Knowledge Graph for go-to-definition, usages, impact analysis, and architecture visualization.

npx playbooks add skill jjuidev/jss --skill gkg

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

Files (5)
SKILL.md
2.4 KB
---
name: gkg
description: Semantic code analysis with GitLab Knowledge Graph. Use for go-to-definition, find-usages, impact analysis, architecture visualization. Supports Ruby, Java, Kotlin, Python, TypeScript/JavaScript.
---

# GitLab Knowledge Graph (GKG)

Semantic code analysis engine using AST parsing and KuzuDB graph database. Enables IDE-like code navigation for AI assistants.

**Status**: Public beta | **Requires**: Git repository | **Storage**: `~/.gkg/`

## When to Use

- Find all usages of a function/class across codebase
- Go-to-definition for symbols
- Impact analysis before refactoring
- Generate architecture diagrams
- RAG-enhanced code understanding

**Use repomix instead** for: quick context dumps, any-language support, remote repos, token counting.

## Quick Start

```bash
# Check installation
gkg --version

# Index current repo
gkg index

# Start server (for API/MCP)
gkg server start

# Stop before re-indexing
gkg server stop
```

## Installation

```bash
# macOS/Linux
curl -fsSL https://gitlab.com/gitlab-org/rust/knowledge-graph/-/raw/main/install.sh | bash

# Windows (PowerShell)
irm https://gitlab.com/gitlab-org/rust/knowledge-graph/-/raw/main/install.ps1 | iex
```

## Core Workflows

### Index and Query
```bash
gkg index /path/to/project --stats
gkg server start
# Query via HTTP API at http://localhost:27495
```

### Find Symbol Usages
1. Index project: `gkg index`
2. Start server: `gkg server start`
3. Use MCP tool `get_references` or HTTP API `/api/graph/search`

### Impact Analysis
1. Index affected repos
2. Query `get_references` for changed symbols
3. Review all call sites before refactoring

## Language Support

| Language | Cross-file Refs |
|----------|-----------------|
| Ruby | ✅ Full |
| Java | ✅ Full |
| Kotlin | ✅ Full |
| Python | 🚧 In progress |
| TypeScript | 🚧 In progress |
| JavaScript | 🚧 In progress |

## References

- [CLI Commands](./references/cli-commands.md) - `gkg index`, `gkg server`, `gkg remove`, `gkg clean`
- [MCP Tools](./references/mcp-tools.md) - 7 tools for AI integration
- [HTTP API](./references/http-api.md) - REST endpoints for querying
- [Language Details](./references/language-support.md) - Supported features per language

## Key Constraints

- Must stop server before re-indexing
- Requires initialized Git repository
- Languages not connected across repos (yet)
- TS/JS/Python cross-file refs incomplete

Overview

This skill provides semantic code analysis powered by the GitLab Knowledge Graph (gkg). It enables IDE-like navigation for large repositories, supporting go-to-definition, find-usages, impact analysis, and architecture visualization. It targets multi-language projects with strong cross-file support for Ruby, Java, and Kotlin, and partial support for Python, TypeScript, and JavaScript. The tool runs locally and stores indexed data under ~/.gkg/.

How this skill works

gkg parses source files into ASTs and stores code entities and relations in a KuzuDB graph database. You index a Git repository, start the local server, and then query via an HTTP API or MCP tools to retrieve symbol definitions, references, and dependency graphs. It is designed for repository-scoped semantic queries and requires stopping the server before re-indexing to avoid conflicts.

When to use it

  • Locate all usages of a function, class, or variable across a repo
  • Jump to the definition of a symbol while inspecting unfamiliar code
  • Perform impact analysis before renaming or removing APIs
  • Generate architecture or dependency visualizations for design reviews
  • Improve retrieval-augmented code explanations by resolving precise symbol contexts

Best practices

  • Ensure the project is a Git repository before indexing
  • Stop the gkg server before re-indexing to prevent data corruption
  • Index only relevant repos or subfolders to limit storage and speed up queries
  • Use the HTTP API or MCP tools for automation and integration with AI assistants
  • Validate language coverage for your codebase — Ruby/Java/Kotlin have the strongest cross-file results

Example use cases

  • Refactor a widely used API: find all call sites, call chains, and downstream impact
  • Onboard to a new codebase: quickly map modules, key types, and where symbols are defined
  • Pre-merge safety check: verify that a rename or signature change won’t break other components
  • Generate a service or module dependency graph for an architecture review
  • Feed precise symbol contexts into an LLM to reduce hallucinations in code explanations

FAQ

Does gkg work on remote repositories?

No. gkg requires a local Git repository to index and analyze. Clone the repo locally before running index.

Which languages have full cross-file support?

Ruby, Java, and Kotlin currently have full cross-file reference support. Python, TypeScript, and JavaScript are in progress and may have incomplete cross-file results.