oaustegard/mapping-codebases
plugins/code-intelligence/skills/mapping-codebases/SKILL.md
Generate navigable code maps for unfamiliar codebases. Extracts exports/imports via AST (tree-sitter) to create _MAP.md files per directory showing classes, functions, methods with signatures and line numbers. Use when exploring repositories, understanding project structure, analyzing unfamiliar code, or before modifications. Triggers on "map this codebase", "explore repo", "understand structure", "what does this project contain", or when starting work on an unfamiliar repository.
$ install --global
skillsauthnpx skillsauth add oaustegard/claude-skills mapping-codebasesInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 20, 2026, 6:04 AM10.2s4 files scanned
SKILL.md
- name:
- mapping-codebases
- description:
- Generate navigable code maps for unfamiliar codebases. Extracts exports/imports via AST (tree-sitter) to create _MAP.md files per directory showing classes, functions, methods with signatures and line numbers. Use when exploring repositories, understanding project structure, analyzing unfamiliar code, or before modifications. Triggers on "map this codebase", "explore repo", "understand structure", "what does this project contain", or when starting work on an unfamiliar repository.
- version:
- 0.8.0
Mapping Codebases
Generate _MAP.md files providing hierarchical code structure views. Maps show function signatures, class methods, imports, and line numbers—enabling API understanding without reading full source files.
Installation
uv venv /home/claude/.venv
uv pip install tree-sitter-language-pack --python /home/claude/.venv/bin/python
Bundled parsers: The skill includes pre-built parsers for all 11 supported languages (Python, JavaScript, TypeScript, TSX, Go, Rust, Ruby, Java, C, HTML, Markdown) in parsers/. These are used automatically when the tree-sitter-language-pack runtime download fails (e.g., in proxied environments). No network access needed for supported languages.
Generate Maps
/home/claude/.venv/bin/python /mnt/skills/user/mapping-codebases/scripts/codemap.py /path/to/repo --skip tests,.github,locale
Common skip patterns: tests,.github,.husky,locale,migrations,__snapshots__,coverage,target,docs
Navigate Via Maps
After generating maps, use them for navigation—read _MAP.md files, not source files directly.
Workflow:
- Read root
_MAP.mdfor high-level structure - Follow subdirectory links to drill into relevant areas
- Use function signatures and class methods to understand APIs
- Read full source only when implementation details are needed
Maps reveal without reading source:
- All public functions with signatures:
def record_attempt(subtask_id, session, success, approach, error=None):200 - Class structure with methods:
RecoveryManager→classify_failure(),is_circular_fix(),rollback_to_commit() - Import relationships showing module dependencies
- Line numbers for direct navigation
Anti-pattern: Reading files directory-by-directory. Use maps to find what you need, then read only the specific file/lines required.
Map Contents
Each _MAP.md includes:
- Directory statistics (file/subdirectory counts)
- Subdirectory links for hierarchical navigation
- Per-file: imports preview, symbol hierarchy with (C)lass/(m)ethod/(f)unction markers
- Function signatures (Python, TypeScript, Go, Rust, Ruby, C)
- Line ranges (
:42-85format) showing symbol start and end lines - Doc comments — first-line summaries from docstrings, JSDoc, Doxygen,
///,#comments - Constants and defines (
pub const,#define,export const, Goconst) - Enum variants as children of enum symbols (C)
- Markdown files: h1/h2 heading ToC
- Other files section (JSON, YAML, configs)
Example:
# services/
*Files: 4 | Subdirectories: 0*
## Files
### recovery.py
> Imports: `json, subprocess, dataclasses, datetime, enum`...
- **FailureType** (C) :24-38
- **RecoveryManager** (C) :43-510 — Manages error recovery strategies.
- **__init__** (m) `(self, spec_dir: Path, project_dir: Path)` :55-72
- **classify_failure** (m) `(self, error: str, subtask_id: str)` :137-198 — Classify an error into a FailureType.
- **record_attempt** (m) `(subtask_id, session, success, approach, error=None)` :200-240
- **is_circular_fix** (m) `(self, subtask_id: str, current_approach: str)` :242-280
- **get_recovery_hints** (m) `(self, subtask_id: str)` :495-510
Commands
# Generate maps
/home/claude/.venv/bin/python /mnt/skills/user/mapping-codebases/scripts/codemap.py /path/to/repo
# Skip directories
/home/claude/.venv/bin/python /mnt/skills/user/mapping-codebases/scripts/codemap.py /path/to/repo --skip tests,.github
# Clean maps
/home/claude/.venv/bin/python /mnt/skills/user/mapping-codebases/scripts/codemap.py /path/to/repo --clean
# Dry run
/home/claude/.venv/bin/python /mnt/skills/user/mapping-codebases/scripts/codemap.py /path/to/repo -n
# Verbose (debug output)
/home/claude/.venv/bin/python /mnt/skills/user/mapping-codebases/scripts/codemap.py /path/to/repo -v
Default skips: .git, node_modules, __pycache__, .venv, venv, dist, build, .next
Supported Languages
Python, JavaScript, TypeScript, TSX, Go, Rust, Ruby, Java, C, HTML, Markdown.
Limitations
- Doc comments extracted as first-line summaries (not full descriptions)
- Signatures: Python (full), TypeScript/Go/Rust/Ruby/C (params + return types), Java (not extracted)
- Markdown: h1/h2 headings only
- Private symbols (
_prefix) excluded from top-level exports
Related Skills
oaustegard/writing-instructions
development
VerifiedTrustedCommunity
Write effective instructions for Claude: project instructions, standalone prompts, and skill content. Use when users need help writing prompts, setting up project instructions, choosing between instruction formats, or improving how they communicate with Claude. Covers writing principles, model-aware calibration, and format selection. For building and testing complete skills, use skill-creator instead.
134SKILL.mdUpdated Jul 26, 2026
oaustegard/finding-skills
data-ai
VerifiedTrustedCommunity
Discover and load skills on demand from /mnt/skills/user/. Use when you need a capability but don't know which skill provides it, when the boot-emitted skill list is names-only and you need a full description, or when you want to list the catalog. Verbs are list (names only), search (rank by name/description match against a query), and show (emit the full SKILL.md for a named skill).
134SKILL.mdUpdated Jul 26, 2026
oaustegard/transcribing-images
documentation
VerifiedTrustedCommunity
Reads the visual content of slides, pages, and images the way a human would, not just their embedded text. Use when a PPTX or PDF has image slides, screenshots, charts, scanned figures, or flattened-to-image layouts that the built-in pptx/pdf skills read as empty; when asked to transcribe, describe, OCR, or extract what is shown in an image, slide deck, or document page; or when embedded-text extraction returned little or nothing from a visually rich file. Triggers on 'read this deck', 'what's on these slides', 'transcribe', 'OCR', 'extract text from image', 'describe this chart/diagram', .pptx/.pdf/.png/.jpg with visual content.
134SKILL.mdUpdated Jul 26, 2026
oaustegard/svg-portrait-mode
development
VerifiedTrustedCommunity
Portrait Mode for SVGs — foveated vectorization with 4-zone selective detail. Combines vision annotations, MediaPipe segmentation/landmarks, and optional saliency. Like phone portrait mode, but vectorized. Use when vectorizing a portrait or photo where subject detail should outrank background detail.
134SKILL.mdUpdated Jul 26, 2026