Guide · Agent skill
How to use the Understand Diff Analyzer agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Understand Diff Analyzer is an agent skill that lets an AI agent check your code changes against a saved map of your codebase. It tells you which components changed, what depends on them, which architectural layers they touch, and a rough risk level. This guide explains what agent skills are, how to install this one, how to trigger it, and where its limits are, so you can use it on your next feature branch or pull request.
Understand Diff AnalyzerEgonex-AI/Understand-Anything · MIT Download the skill Quick start
- 1Install git and check the repository. Make sure git is installed and your project is a git repository.
- 2Generate the knowledge graph. Run /understand in the project so the graph file exists in .ua/ or .understand-anything/.
- 3Download and unzip the skill. Download the ZIP from this page and unzip the understand-diff folder.
- 4Place the skill folder. Put it in ~/.claude/skills/ for personal use or in the project's .claude/skills/, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 5Make a change or open a PR. Have uncommitted changes, a feature branch, or a pull request ready to review.
- 6Ask for the analysis. Request an impact analysis in plain language or use /understand-diff.
- 7Review the overlay. Optionally run /understand-anything:understand-dashboard to see changed and affected areas.
What is an agent skill and what does understand-diff do?
An agent skill is a folder containing a SKILL.md file that gives an AI agent specific instructions for a task. This skill is named understand-diff and its description reads: use it when you need to analyse git diffs or pull requests to understand what changed, affected components, and risks.
The skill works against a knowledge graph, which is a saved map of your codebase built earlier by the companion /understand command. You need that graph before the skill can do anything useful.
- Takes your uncommitted changes, a feature branch, or a pull request
- Reports changed components with summaries taken from the graph
- Lists affected components one connection away (callers and dependencies)
- Identifies touched architectural layers and gives a rough risk assessment
- Writes a diff overlay file that the companion dashboard can display
What you need before installing
The skill expects git to be installed and your project to be a git repository. It also needs a knowledge graph previously generated by the /understand command, stored at .ua/knowledge-graph.json or the legacy .understand-anything/knowledge-graph.json.
If you are reviewing a pull request by number, you need access to that PR's diff. The skill does not specify which tool fetches it. The understand-dashboard command is optional and only needed if you want to view the diff overlay visually.
- Git installed, project is a git repository
- Knowledge graph generated by /understand
- Access to the PR diff if reviewing by PR number
- Optional: the understand-dashboard command
How do you install the understand-diff skill?
Download the ZIP file from this page and unzip it. For a personal install across all your projects, place the understand-diff folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder so it travels with the repository.
In the Claude apps you can instead upload the skill under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/understand-diff/
- Project only: .claude/skills/understand-diff/ inside your repository
- Claude apps: Settings → Capabilities → Skills, then upload
How do you generate the knowledge graph first?
The skill will not run its analysis without a graph. Run the /understand command in your project to create it. The skill checks for .ua/knowledge-graph.json first, then the legacy .understand-anything/ location.
Because the graph is a snapshot, the skill compares the graph's recorded commit with your current git state. If project files have changed since then, it warns you that the graph may be missing those changes and suggests running /understand again.
- Run /understand in the project root
- Re-run /understand when project files change after the graph was built
How do you trigger the skill with natural requests?
You do not need to type a special command. Describe what you want in plain language and the agent will match the skill's description. Good requests name the change or the PR, and say what you want to know.
You can also invoke it directly as /understand-diff. The skill analyses your uncommitted changes by default, or compares a feature branch against its base branch such as main, or a PR number you give it.
- "What does my current uncommitted change affect in this project?"
- "Analyse the diff of this feature branch against main and tell me the risks."
- "Check PR 412 against the knowledge graph and list the affected layers."
- "Which architectural layers does my change touch?"
What does the analysis report look like?
The agent produces a structured analysis with five parts: Changed Components, Affected Components, Affected Layers, Risk Assessment, and suggestions on what to review carefully. Changed components come from nodes whose file paths match your changed files. Affected components come from edges one hop away.
After the analysis, the skill writes a diff overlay file to your data directory. Run /understand-anything:understand-dashboard to see the changed and affected areas highlighted.
- Changed Components: directly modified files, functions and classes
- Affected Components: direct callers and dependencies
- Affected Layers: architectural layers touched and cross-layer concerns
- Risk Assessment: based on complexity values, cross-layer edges and blast radius
/understand-anything:understand-dashboardWhat are the safety notes and limits?
This skill runs scripts, which means the agent executes commands such as git diff and git rev-parse in your project. It does not use the network. It writes a diff-overlay.json file into your data directory.
The risk rating is a heuristic based on node complexity and edge counts. It is not a verified review and should not be used for security audits or final risk sign-off. A stale graph can also miss recent changes, so treat the output as a starting point for review.
- Runs scripts: yes. Review what the agent runs if you are cautious.
- Uses network: no
- Writes .ua/diff-overlay.json (or legacy equivalent)
- Risk rating is heuristic, not a security review
What people use it for
- Reviewing a large feature branch to see the blast radius before merging
- Checking which architectural layers a pull request touches in a monorepo
- Getting a change-impact summary before asking a colleague to review
- Spotting dependent components that might need updating after a refactor
Frequently asked questions
Is the understand-diff skill free?
The source provided for this guide is licensed under MIT. It does not state pricing for the skill itself, so check the project's repository for licence terms before using it commercially.
What do I need to install understand-diff?
You need git, a project that is a git repository, and a knowledge graph generated by /understand. Download the ZIP from this page and place the folder in ~/.claude/skills/ or the project's .claude/skills/, or upload it in the Claude apps under Settings → Capabilities → Skills.
Why does the skill say I need to run /understand first?
The skill analyses changes against a knowledge graph, which is a saved map of your codebase. Without .ua/knowledge-graph.json or the legacy .understand-anything/knowledge-graph.json, there is nothing to check your changes against, so the skill stops and asks you to build the graph.
Does understand-diff work with pull requests?
It can analyse a pull request if you give it a PR number and the agent can access that PR's diff. The skill does not specify which tool fetches the diff, so you may need to make that available yourself.
Why is the graph warning me that my analysis might be incomplete?
The graph records the commit it was built from. If project files changed after that commit, or there are uncommitted project changes, the graph may not include them. Run /understand again to refresh it.
Can I use understand-diff for a security audit?
No. The risk rating is a heuristic based on node complexity and edge counts, not a verified review. Use it to decide where to look closely, not as sign-off for security or final risk decisions.
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-diff if you review large feature branches or monorepo pull requests and already keep a /understand graph current, because it shows what else a change could affect. Skip it for small one-line fixes, projects without a graph, or any situation that needs a definitive security or risk sign-off, where a plain git diff review or a dedicated audit is the better choice.
Download the skill