Guide · Agent skill

How to use the Codebase Knowledge Graph skill (understand)

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

The understand skill is an agent skill that analyzes a codebase and writes a knowledge-graph.json file describing its components and how they relate. That file powers an interactive dashboard for exploring the project's architecture. This guide is for developers who are new to agent skills and want to install the skill, run it, and decide whether it fits their project.

Codebase Knowledge GraphEgonex-AI/Understand-Anything · MIT Download the skill

Quick start

1Check prerequisites. Confirm Node.js, pnpm and Git are installed. The skill's own error message asks for Node.js 22 or later and pnpm 10 or later.
2Download the ZIP. Download the skill ZIP from the skill page on this site.
3Install the skill. Unzip it into ~/.claude/skills/ for all projects, or into the project's .claude/skills/ folder for one project. In the Claude apps, upload it under Settings → Capabilities → Skills.
4Open your project. Start the agent in the project you want to map, or be ready to pass its directory path.
5Ask for an analysis. Request an architecture or component analysis in plain language, or run /understand.
6Open the output. Find knowledge-graph.json in the .ua/ folder and open the interactive dashboard to explore the connections.

What an agent skill is and what this one does

An agent skill is a packaged set of instructions and helper files that an AI coding agent can load and follow when you ask for a matching task. This skill covers analyzing a project's architecture.

When you ask the agent to analyze a project, the skill scans the code, groups related files, and extracts functions, classes, imports and exports with helper scripts. It then writes knowledge-graph.json into a hidden data folder named .ua/ (or the legacy .understand-anything/ if that folder already exists).

Produces a knowledge-graph.json file in the project's data directory
Can run a full rebuild or an incremental update
Can optionally update the graph automatically on each commit
Can generate textual content in other languages

Check the requirements before installing

The skill needs Node.js, because its scripts are .mjs files that import @understand-anything/core. It also needs a pnpm workspace of the understand-anything plugin, which is built on first run, and Git, which is used for worktree detection and commit hashes.

The skill runs scripts on your machine. According to the skill listing, it does not use the network, but the source files reviewed do not show the full data path, so check that before using it on sensitive code. The skill's error message asks for Node.js 22 or later and pnpm 10 or later.

Node.js (22 or later, per the skill's own error message)
pnpm (10 or later, per the skill's own error message)
Git
The understand-anything plugin workspace, built on first run

Install the skill from the ZIP or the Claude apps

Download the ZIP from the skill page on this site. To install it for your user account, unzip it into ~/.claude/skills/. To install it for a single project, unzip it into that project's .claude/skills/ folder.

If you use the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

Personal install: unzip into ~/.claude/skills/
Project install: unzip into the project's .claude/skills/ folder
Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Build the plugin on first run

On a fresh install, the compiled core package does not exist yet. The skill tries to install dependencies and build it the first time it runs. If you want to do this yourself, the skill's own commands are shown below. If pnpm is missing, install Node.js and pnpm, then run the skill again.

cd "$PLUGIN_ROOT" && (pnpm install --frozen-lockfile 2>/dev/null || pnpm install) && pnpm --filter @understand-anything/core build

Trigger the skill with a request or the /understand command

You can ask the agent in plain language to analyze the project's architecture, components and relationships, and the skill is the one designed for that. The skill also has a /understand command, which accepts optional arguments. Run it from inside the project, or pass a directory path to analyze a different one.

Options from the skill's own documentation include --full to force a rebuild that ignores any existing graph, --auto-update and --no-auto-update to switch automatic updates on commit, --review to run the full LLM graph reviewer instead of inline validation, --language to set output language, and --exclude to skip files.

--full: force a full rebuild, ignoring the existing graph
--auto-update / --no-auto-update: turn automatic updates on commit on or off
--review: use the full LLM graph reviewer instead of inline validation
--language <lang>: write summaries, titles and descriptions in another language
--exclude <patterns>: comma-separated glob patterns to skip, which take priority over built-in defaults and .understandignore rules

/understand
/understand --full
/understand /path/to/repo

Examples of useful runs

Start with a plain run on a project you have not seen before. Then exclude generated or test folders if they add noise, and write the output in your team's language if needed.

If you work in a git worktree, the skill redirects its output to the main repository root, because the data folder in an ephemeral worktree would be lost when the session ends. Set UNDERSTAND_NO_WORKTREE_REDIRECT=1 only if you want a separate graph per worktree.

First map of an unfamiliar service: run /understand with no arguments
Skip tests and docs: /understand --exclude "tests/*,docs/*"
Team documentation in Japanese: /understand --language japanese
Rebuild after large refactors: /understand --full

/understand --exclude "tests/*,docs/*"
/understand --language japanese

What people use it for

Onboarding onto a large codebase you did not write, to see the main components and how they connect
Giving a team a browsable overview of services, modules and their relationships
Keeping an architecture map current with incremental updates as the code changes
Producing a graph in another language for a team that reads documentation in that language

Frequently asked questions

How do I install the understand skill?

Download the ZIP from the skill page on this site and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps, you can upload the ZIP under Settings → Capabilities → Skills.

What do I need to run the understand skill?

You need Node.js, pnpm, and Git. The skill's scripts import @understand-anything/core, and the plugin is built on first run. The skill's error message asks for Node.js 22 or later and pnpm 10 or later.

Is the understand skill free to use?

The skill is listed under the MIT licence. Check the repository's licence file for the exact terms before you redistribute it.

Does the understand skill send my code over the network?

The skill listing says it does not use the network. However, the reviewed files do not show the full data path, and the dashboard or analysis could be configured to send content externally. For sensitive repositories, check the configuration before running it.

Why does the skill say pnpm is missing?

The plugin is built with pnpm, so the skill needs it on your machine. Install Node.js and pnpm, then run /understand again.

When is this skill a poor fit?

It is not worth using on small projects where reading the code directly is quicker, or if you do not want scripts run on your machine. Choose a lighter approach for those cases.

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

Use this skill when you are onboarding onto a large or unfamiliar codebase, or your team wants a browsable architecture map that updates incrementally. Skip it for small projects, for machines where you cannot run Node.js scripts, and for sensitive repositories until you have confirmed where the analysis data goes.

Download the skill