understand-code
Skill2 starsChanged 33 days agoApache-2.0View on GitHub
Understand an unfamiliar codebase before you change it — map structure, find where symbols are defined and used, trace call chains, and assess a change's blast radius, using xgrep's AST code graph and fast text search. Use before editing unfamiliar code, locating a definition or caller, or judging what a change might break.
2 other projects use a version of this.
Adopted by
Most recently taken up by
- shy-UCAS/claude-skillstheir own version, first seen Oct 20, 2026
- LucaDominici/arbitertheir own version, first seen Sep 20, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- LucaDominici/arbiter★ 0same name
- shy-UCAS/claude-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository10 other files it gives its agents.
- AGENTS.mdAGENTS.md
- author-detectionsSkill
- fix-findingsSkill
- secure-ai-servicesSkill
- secure-cloudSkill
- secure-codingSkill
- secure-osSkill
- secure-pipelineSkill
- secure-saasSkill
- triage-findingsSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 82
Search index cached to .xgrep/search/ — full Zoekt trigram index, skipped when fresh (~0.1s)
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Understand Code
Map and navigate a codebase before changing it, using xgrep's AST-powered code graph and Zoekt-powered text search — so a change starts from understanding, not guesswork.
When to Use
- Exploring an unfamiliar codebase ("what does this project do?", "what are the main components?")
- Finding code ("where is X defined?", "who calls Y?", "find all implementations of Z")
- Understanding relationships ("what does this function depend on?", "trace this call chain")
- Assessing change impact ("what breaks if I change this?", "what's the blast radius?")
- Getting a file overview before reading it line by line
When NOT to Use
- Running security scans (use the
secure-pipelineskill, ortriage-findingsfor results) - Creating or modifying detection rules (use
author-detections) - Simple text searches where grep/ripgrep suffice (single keyword in a known file)
Commands Reference
Orient
| Command | Purpose |
xgrep inspect overview [dir] | Codebase summary: languages, packages, entry points, key types |
Locate
| Command | Purpose |
xgrep inspect symbol <query> [--kind K] | Search symbols by name (exact, prefix, substring) |
xgrep inspect search <query> [--lang L] [--regex] | Fast trigram-indexed text search (Zoekt) |
Locating is lexical (a name or a string the code contains), not semantic — there is
no search-by-meaning. When you only know what the code does, not its name: run
overview first to learn the real vocabulary, then symbol/search those terms
(expanding synonyms yourself, e.g. auth → session/credential/login), then
references/deps to traverse to the target. This is faster and more precise than
guessing patterns with grep.
Navigate
| Command | Purpose |
xgrep inspect definition --file F --line N | Find symbol definition at position |
xgrep inspect hover --file F --line N | Doc comment, type info, params (tooltip) |
xgrep inspect ranges <file> --start S --end E | All symbols in a line range (bulk) |
xgrep inspect references <name> | Find all callers, callees, references |
xgrep inspect implementations <name> | Find interface implementations |
xgrep inspect outline <file> | List all symbols in a file |
Assess
| Command | Purpose |
xgrep inspect impact <name> | Blast radius: callers, callees, affected files, risk score |
xgrep inspect deps <name> [--depth N] | Call dependencies: upstream callers, downstream callees |
Deep Dive (existing graph commands)
| Command | Purpose |
xgrep graph context <name> --depth N | N-hop neighborhood with inlined source |
xgrep graph paths <src> <dst> | Call paths between two functions |
xgrep graph callers <name> | Direct callers |
xgrep graph callees <name> | Direct callees |
Output Formats
All inspect commands support --json for machine-readable output. Without --json, output is human-readable text.
Caching
- Code graph cached to
.xgrep/graph.json— incremental rebuild via file mtimes (~0.3s when fresh) - Search index cached to
.xgrep/search/— full Zoekt trigram index, skipped when fresh (~0.1s) - Both are built automatically on first use — no setup needed
Supported Languages
xgrep uses tree-sitter for AST parsing. Full symbol extraction (variables, fields, constants, imports, doc comments, visibility) for:
- Go: functions, methods, types, struct fields, variables, constants, imports
- Python: functions, classes, attributes, module variables, constants, imports
- JavaScript/TypeScript: functions, classes, fields, variables, constants, imports
Basic extraction (functions, classes, call edges) for 30+ additional languages.
Part of the secure-your-stack toolkit
This is the orientation step. Once you start changing code: secure-coding helps write it
safely, and secure-pipeline scans it (SAST/SCA/secrets + IaC) before it ships — with
triage-findings and fix-findings for the results. A runtime guard (secure-guard mod)
runs those checks automatically as an agent works.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
Reviews can't be read right now.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.