Understand Explain
Get a deep, graph-grounded explanation of a file, function, or module without loading the entire codebase into context.
Overview
understand-explain is an agent skill most often used in Build (docs) and Ship (review) that produces in-depth explanations of a chosen codebase component using a structured knowledge graph.
Install
npx skills add https://github.com/lum1104/understand-anything --skill understand-explainWhat is this skill?
- Targets a specific file-path argument for focused deep-dive explanations
- Reads a structured knowledge graph: nodes, edges, layers, and guided tour entries
- Efficient retrieval pattern: Grep the graph JSON before reading whole files
- Supports code and domain node types including endpoints, pipelines, schemas, and flows
- Edge types such as calls, imports, depends_on, and documents map real dependencies
Adoption & trust: 824 installs on skills.sh; 54.9k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You need to change or review a file but lack a clear mental model of how that function, class, or module connects to the rest of the project.
Who is it for?
Builders with an existing codebase knowledge graph who want efficient, scoped explanations before edits or PR review.
Skip if: Empty repos or greenfield projects with no analyzed graph artifact yet.
When should I use this skill?
Use when you need a deep-dive explanation of a specific file, function, or module in the codebase (optional file-path argument).
What do I get? / Deliverables
You receive a structured deep-dive on the requested path grounded in graph nodes, edges, and summaries so you can edit or review with confidence.
- In-depth narrative explanation of the requested component
- Referenced graph nodes and relationship context
- Pointers to related modules via edge types
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Understanding unfamiliar code is a recurring need starting when you build features and extend through review and maintenance. Docs-style comprehension of components maps to explaining architecture and module boundaries while the product is actively developed.
Where it fits
Explain an API module’s endpoints and downstream tables before you extend the handler.
Walk through a risky function’s call graph before merging a contributor PR.
Re-ground yourself on a pipeline step implicated in a production incident.
How it compares
Use for graph-backed narrative explanation, not as a substitute for running tests or generating architecture diagrams from scratch.
Common Questions / FAQ
Who is understand-explain for?
Solo developers and indie teams maintaining non-trivial repos who already maintain a understand-anything style knowledge graph and want agent-guided walkthroughs.
When should I use understand-explain?
During Build when documenting or extending a module; during Ship review before approving risky changes; during Operate when debugging production paths you did not originally write.
Is understand-explain safe to install?
Review the Security Audits panel on this page; the skill reads project graph data you provide and should not exfiltrate secrets if your graph excludes credential files.
SKILL.md
READMESKILL.md - Understand Explain
# /understand-explain Provide a thorough, in-depth explanation of a specific code component. ## Graph Structure Reference The knowledge graph JSON has this structure: - `project` — {name, description, languages, frameworks, analyzedAt, gitCommitHash} - `nodes[]` — each has {id, type, name, filePath?, summary, tags[], complexity, languageNotes?} - Code node types: file, function, class, module, concept - Non-code node types: config, document, service, table, endpoint, pipeline, schema, resource - Domain/knowledge node types: domain, flow, step, article, entity, topic, claim, source - IDs use the node type as prefix, e.g. `file:path`, `function:path:name`, `config:path`, `article:path` - `edges[]` — each has {source, target, type, direction, weight} - Key types: imports, contains, calls, depends_on, configures, documents, deploys, triggers, contains_flow, flow_step, related, cites - `layers[]` — each has {id, name, description, nodeIds[]} - `tour[]` — each has {order, title, description, nodeIds[]} ## How to Read Efficiently 1. Use Grep to search within the JSON for relevant entries BEFORE reading the full file 2. Only read sections you need — don't dump the entire graph into context 3. Node names and summaries are the most useful fields for understanding 4. Edges tell you how components connect — follow imports and calls for dependency chains ## Instructions 1. Check that `.understand-anything/knowledge-graph.json` exists. If not, tell the user to run `/understand` first. 2. **Find the target node** — use Grep to search the knowledge graph for the component: "$ARGUMENTS" - For file paths (e.g., `src/auth/login.ts`): search for `"filePath"` matches - For function notation (e.g., `src/auth/login.ts:verifyToken`): search for the function name in `"name"` fields filtered by the file path - Note the exact node `id`, `type`, `summary`, `tags`, and `complexity` 3. **Find all connected edges** — Grep for the target node's ID in the edges section: - `"source"` matches → things this node calls/imports/depends on (outgoing) - `"target"` matches → things that call/import/depend on this node (incoming) - Note the connected node IDs and edge types 4. **Read connected nodes** — for each connected node ID from step 3, Grep for those IDs in the nodes section to get their `name`, `summary`, and `type`. This builds the component's neighborhood. 5. **Identify the layer** — Grep for the target node's ID in the `"layers"` section to find which architectural layer it belongs to and that layer's description. 6. **Read the actual source file** — Read the source file at the node's `filePath` for the deep-dive analysis. 7. **Explain the component in context**: - Its role in the architecture (which layer, why it exists) - Internal structure (functions, classes it contains — from `contains` edges) - External connections (what it imports, what calls it, what it depends on — from edges) - Data flow (inputs → processing → outputs — from source code) - Explain clearly, assuming the reader may not know the programming language - Highlight any patterns, idioms, or complexity worth understanding