code-understand — Claude Code skill: what it does, how to install
code-understand builds a focus map of core symbols and call dependencies in unfamiliar codebases. Useful for blast radius analysis and refactoring prep.
MIT 226 installs ★ 3,795 updated 2026-10-21
npx skills add Ar9av/obsidian-wiki --skill code-understand -a claude-codeWhat code-understand does
The skill triggers obsidian-wiki code-understand to produce an on-demand architecture focus map. Instead of running loose grep queries or skimming unrelated files, the agent receives a ranked list of core symbols with concrete file:line pointers and evidence markers. It identifies caller hierarchies and structural dependencies before you start modifying code.
It relies on two engine choices. With the default auto setting, the tool checks for @colbymchenry/codegraph to trace verified call-graph relationships. If that package is absent, it drops down to a builtin regex AST scanner and rg. Under the builtin backend, textual rg-reference results need manual confirmation in the file because they only represent text matches rather than verified call edges.
Scans can be focused on specific diffs using --changed <file> or --since <sha>, while --max-symbols defaults to 50 entries. If the underlying obsidian-wiki CLI command fails or is missing, the skill advises dropping back to manual grep checks rather than halting workflow.
What it helps with
- map critical dependencies across unfamiliar code before editing
- calculate the blast radius of changes across active git diffs
- find all callers of a function without manual codebase scanning
- inspect available parsing backends using
obsidian-wiki doctor
Example prompts for the agent
- Run code-understand to find callers of
handleWebhookbefore I refactor it. - Inspect the blast radius for files modified since
HEAD~2. - Generate an architecture map for this repository with
--max-symbols 30.
How to install code-understand
1Skills CLI (Vercel)
npx skills add Ar9av/obsidian-wiki --skill code-understand -a claude-code2Manually: put the files in place
~/.claude/skills/code-understand/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/code-understand/
1Skills CLI (Vercel)
npx skills add Ar9av/obsidian-wiki --skill code-understand -a codex2Manually: put the files in place
.agents/skills/code-understand/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add Ar9av/obsidian-wiki --skill code-understand -a cursor2Manually: put the files in place
.cursor/skills/code-understand/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install Ar9av/obsidian-wiki .skills/code-understand/SKILL.md2Manually: put the files in place
.github/skills/code-understand/SKILL.md1Skills CLI (Vercel)
npx skills add Ar9av/obsidian-wiki --skill code-understand -a gemini-cli2Platform CLI
gemini skills install https://github.com/Ar9av/obsidian-wiki --path .skills/code-understandManually: put the files in place
.devin/skills/code-understand/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add Ar9av/obsidian-wiki --skill code-understand -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about code-understand
How do I install code-understand in Claude Code?
Run npx skills add Ar9av/obsidian-wiki --skill code-understand -a claude-code. The skill file will be created at ~/.claude/skills/code-understand/SKILL.md.
What does code-understand do?
It generates an index of load-bearing symbols and file dependencies with precise file:line citations. This gives the agent a targeted map of what to inspect before modifying an unfamiliar architecture.
Is CodeGraph required to use code-understand?
No, the skill operates without extra tools by falling back to its builtin AST regex extractor and rg. Installing @colbymchenry/codegraph via npm is only needed if you want verified cross-file call-graph edges instead of text matches.
Source text
SKILL.md · MIT
---
name: code-understand
description: >
Map the load-bearing files, symbols, callers, and dependencies of an unfamiliar codebase before making changes. Use for architecture orientation, impact analysis, what-would-break questions, or finding callers. Uses CodeGraph when available and a dependency-free builtin fallback.
---
# Code Understand — On-Demand Architecture Focus Map
You are about to work in a codebase you don't fully know yet. Instead of grepping around or
reading files at random, ask the local extractor for a **focus map**: the ranked symbols the
architecture hangs on, each with a `file:line` citation and evidence type. Read only what it
points at — this is a map, not a substitute for reading the actual code it cites.
## When to reach for this
- Before editing an unfamiliar module — see what calls it and what it calls before changing
its shape.
- The user asks "how does X work", "what's the impact of changing Y", "who else uses this
function" for a codebase, not the wiki.
- You're about to do a large refactor and want a ranked list of load-bearing files instead of
reading the whole tree.
- You already have a diff or a set of changed files and want to know their blast radius before
finishing the change.
Not for: summarizing what a project *does* for the wiki (that's `wiki-update` Step 3b, which
calls this same command as part of a bigger sync flow) — use this skill directly only when you
need the focus map for your own immediate work, not to persist knowledge.
## Running it
```bash
obsidian-wiki code-understand --project <dir> [--backend auto|builtin|codegraph] \
[--changed <file>...] [--since <sha>] [--max-symbols N] [--pretty]
```
- `--project` — defaults to the current directory.
- No `--changed`/`--since` — seeds from every tracked file (full-project scan).
- `--changed <file>` (repeatable) — seed from specific files you already know are relevant
(e.g. files in the diff you're about to make).
- `--since <sha>` — seed from everything changed since a git ref (e.g. `--since HEAD~5` or a
base branch).
- `--backend` — `auto` (default) uses CodeGraph when installed, falls back to the builtin
extractor otherwise; force `builtin` for the dependency-free path, or `codegraph` to require
the enhanced backend (fails loudly if it's not installed rather than silently degrading).
- `--max-symbols` — cap the focus map size (default 50); keep this small for a quick
orientation pass, raise it for a thorough one.
**GUARD:** if the command is unavailable or errors, skip it and fall back to your normal
exploration (grep/read) — this is an accelerant, not a dependency. Don't block work on it.
## Reading the output
1. **Evidence type matters.** When `backend: codegraph`, focus-map entries are structural
facts (real call-graph edges) — cite them directly. When `backend: builtin`, `defines`/
`imports`/`changed-file` entries are facts, but `rg-reference` entries are text-match
evidence only — open the file and confirm before treating it as a real relationship.
2. **Open what it cites, nothing else first.** The focus map tells you *where* to read; it
never contains source bodies. Go read those `file:line` locations before forming an opinion
on the architecture.
3. **Cite it in your own output.** If you explain the architecture back to the user or write
it into a PR description/commit message, keep the `(file:lines)` citations from the focus
map or from the source you opened — don't assert structure without a pointer to it.
4. **It's a cache, not a deliverable.** Never write the raw JSON or `.codegraph/` into the
wiki vault, a PR description, or committed docs — it's a disposable sidecar in the project
repo (git-ignored). Re-run it fresh next time rather than treating old output as durable.
## If CodeGraph isn't installed
`auto`/`builtin` still work with zero setup (uses the regex AST extractor + `rg`). If you want
the enhanced cross-file call-graph evidence and the user is fine with installing something:
```bash
npm install -g @colbymchenry/codegraph
```
or point `CODE_UNDERSTANDING_CODEGRAPH_BIN` at an existing binary. Never install without the
user's go-ahead — ask first, then re-run the command.
Check `obsidian-wiki doctor --project <dir>` for the `code-understanding.*` capability lines
(`builtin`, `rg`, `codegraph`, `codegraph-index`, `codegraph-fresh`, `codegraph-gitignore`) to
see what's available before deciding which backend to request explicitly.
© Ar9av · MIT · Ar9av/obsidian-wiki