Guide · Agent skill
How to use understand-chat: codebase Q&A from a knowledge graph
Updated · written with AI from the project's own documentation and checked against our catalogue data
understand-chat is an agent skill from the Understand-Anything plugin that lets an AI coding agent answer questions about a codebase by searching a saved knowledge graph instead of reading every file. It is aimed at developers getting oriented in a large or unfamiliar project and at engineers who already ran /understand. After this guide you will know what the skill does, how to install it, how to trigger it with plain requests, and where it falls short.
Codebase Q&A via Knowledge GraphEgonex-AI/Understand-Anything · MIT Download the skill Quick start
- 1Download the skill. Download the understand-chat ZIP from the directory page and unzip it so that SKILL.md sits inside a skill folder.
- 2Place the skill folder. Move the folder into ~/.claude/skills/ for personal use, or into the project's .claude/skills/ for one project. In the Claude apps, upload the ZIP under Settings → Capabilities → Skills instead.
- 3Generate the knowledge graph. In your project root, run /understand so that the knowledge graph JSON file is created in .ua/ or .understand-anything/.
- 4Ask a question. Describe what you want to know in plain language, naming a module, service or layer where you can, or use /understand-chat with your query.
- 5Read the freshness warning. If the skill reports that the graph is out of date, treat the answer as possibly incomplete and run /understand to refresh the graph.
- 6Check the cited locations. Open the files and functions the answer references to confirm the details before you change any code.
What is an agent skill, and what does understand-chat do?
An agent skill is a folder containing a SKILL.md file that gives an AI agent specific instructions for one kind of task. Once a skill is installed, the agent can load it when a request matches the skill's description.
understand-chat is used when you need to ask questions about a codebase or understand code using a knowledge graph. The graph is a JSON file stored in the project's data directory, either .ua/knowledge-graph.json or the legacy .understand-anything/knowledge-graph.json when that directory exists. Its nodes are files, functions, classes, modules, concepts and other entries, and its edges record how they import, call or depend on each other.
The agent searches this graph for the names, summaries and tags that match your question, follows the connections around those matches, and answers with references to specific files and functions. It also reads the layer groupings in the graph to say which architectural layers are involved.
- Searches the saved graph with keyword matches on node names, summaries and tags
- Follows imports, calls and dependencies one hop out from matching nodes
- Explains which architectural layers the matched code belongs to
- Checks whether the graph is out of date against recent git changes
Install the understand-chat skill
Download the ZIP for the skill from the directory page and unzip it. The skill is delivered as a folder containing SKILL.md. Put that folder in one of two places depending on how you want to use it.
For all of your projects, place it in ~/.claude/skills/. To use it in a single project only, place it in the project's .claude/skills/ folder.
If you use the Claude apps instead of a local setup, upload the ZIP under Settings → Capabilities → Skills.
- Personal install: ~/.claude/skills/ (available across projects)
- Project install: .claude/skills/ inside the project root (available only there)
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Build the graph before you ask anything
understand-chat cannot answer from nothing. It needs a knowledge graph that a prior run of the /understand command has generated. Run /understand in the project root first.
When the skill starts, it resolves the data directory and checks that knowledge-graph.json exists there. If the file is missing, the skill tells you to run /understand before continuing.
UA_DIR=$([ -d .understand-anything ] && echo .understand-anything || echo .ua)Ask questions with natural requests
The skill is triggered by its description, so you can ask in plain language about structure, dependencies or where something lives. The argument hint for the command is a query, so you can also invoke it directly with a question after the command name.
Good questions name a concept, module, service or layer that appears in the project. Vague questions produce weaker matches. If your query matches no nodes, the skill says so and suggests related terms taken from the graph.
- How do the API handlers connect to the database layer?
- Which files import the authentication module?
- What calls the payment service, directly or through another module?
- Where is configuration loaded, and what depends on it?
- Give me an overview of the service layer and how its modules depend on each other.
/understand-chat [query]Understand freshness warnings and safety notes
Before answering, the skill compares the graph's recorded commit with the current repository. It runs git commands scoped to the project folder, so commits that only touch a sibling project in a monorepo do not count as drift. Changes to the .ua/ or .understand-anything/ folder are ignored because they are generated graph files, not source changes.
If the committed diff or any uncommitted or untracked project files differ from the graph, the skill warns you that its answer may omit those changes and suggests running /understand to refresh the graph. If Git or the graph's commit hash is unavailable, it gives a short best-effort warning and continues.
The skill runs scripts and needs Bash shell access for the directory check and git commands. It does not use the network, according to the skill's listing.
- Runs scripts: yes, for the directory check and git commands
- Uses network: no
- Git is optional; without it the skill continues with a warning
- Answers may omit recent edits until the graph is rebuilt
GRAPH_COMMIT=$(git rev-parse --verify --end-of-options "${GRAPH_COMMIT_RAW}^{commit}" 2>/dev/null)
git rev-parse HEAD
git diff --name-only "$GRAPH_COMMIT" HEAD -- .
git diff --cached --name-only -- .
git diff --name-only -- .
git ls-files --others --exclude-standard -- .Tips for getting better answers
Use the skill for structure and dependencies rather than live behaviour. The graph is a static snapshot, so questions about runtime values, timing or the current state of a deployment are better answered by reading code or running it.
Refresh the graph after large changes. When the skill warns that the graph is stale, run /understand and ask again. Answers on freshly rebuilt graphs are the most reliable.
- Name concrete modules, services or layers in your question
- Check the freshness warning before trusting an answer about recent edits
- Ask follow-up questions about a specific file to follow its connections further
- Do not expect answers from a project where /understand has never been run
What people use it for
- Getting oriented in an unfamiliar repository by asking which modules are the main entry points
- Tracing how a service depends on other modules before refactoring it
- Finding which files import a shared utility before changing its interface
- Understanding how layers such as API, service and data access connect in a large project
- Answering a teammate's question about project structure without reading every file
Frequently asked questions
Is understand-chat free to use?
The skill's listing is published under the MIT licence. This guide does not cover pricing for the Claude apps or any other service you use to run the agent.
What do I need before understand-chat works?
You need a prior run of the /understand command that generates the knowledge graph JSON file, and Bash shell access for the directory check and git commands. Git is optional; without it the skill continues with a warning.
Why does the skill say I need to run /understand first?
The skill searches a saved knowledge graph, and that file is created by /understand. If .ua/knowledge-graph.json or the legacy .understand-anything/knowledge-graph.json is missing, there is nothing to search, so the skill asks you to run /understand.
Does understand-chat read my whole codebase?
No. It is designed to search the graph with Grep and read only the sections it needs, rather than reading every file. Its answers are only as current as the graph, so it warns you when project files have changed since the graph was built.
Does understand-chat send my code over the network?
The skill's listing says it does not use the network. It does run scripts and git commands locally to check the directory and graph freshness.
How is this different from asking the agent to read the code directly?
Searching a saved graph of files, functions and connections can be faster for structural questions than reading many files, but the graph is a static snapshot. For live or runtime behaviour, or for changes made since the last /understand run, read the code directly.
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 understand-chat if you work in a large or unfamiliar codebase and have already run /understand, because it gives quick, referenced answers about structure and dependencies. Pick something else if you need answers about runtime behaviour, or if you cannot generate and keep the knowledge graph up to date.
Download the skill