Now liveThe Skillselion MCP - thousands of ranked skills, loaded into your agent mid-task. No install.Get it →
oaustegard avatar

Mapping Codebases

oaustegard/claude-skills

  • 93 installs
  • 137 repo stars
  • Updated August 3, 2026
  • oaustegard/claude-skills

Generate structured codebase maps and _MAP.md artifacts so your coding agent can navigate an unfamiliar repo quickly.

About

mapping-codebases is an oaustegard Claude skill that walks an agent through parsing a repository and emitting machine- and human-readable maps. It bundles parsers for Python, JavaScript, TypeScript, TSX, Go, Rust, Ruby, Java, HTML, and Markdown, with optional curl fallback when a grammar is missing. Recent releases add richer TypeScript signatures, export surfaces, receiver methods in Go and Rust, and C language coverage with doc comments and enum detail. Solo builders inherit legacy repos, fork OSS projects, or onboard contractors constantly; this skill reduces guesswork before refactors, reviews, or feature work. Outputs align with _MAP.md regeneration workflows and Lattice knowledge-graph linking mentioned in the changelog. Invoke when you need a dependable structural overview rather than ad-hoc grep tours, especially for agents that plan edits across many files.

  • Multi-language parsing via bundled tree-sitter grammars with curl fallback
  • Generates _MAP.md and structured exports with signatures, exports, and line ranges
  • v0.8.0 adds C support plus doc comments, constants, and enum variants
  • Lattice v2 bidirectional source-anchored knowledge graph for behavioral app docs
  • mapping-features companion skill for behavioral web application documentation

Mapping Codebases by the numbers

  • 93 all-time installs (skills.sh)
  • +1 installs in the week ending Aug 4, 2026 (Skillselion tracking)
  • Ranked #658 of 1,879 Documentation skills by installs in the Skillselion catalog
  • Security screen: HIGH risk (skills.sh audit)
  • Data as of Aug 4, 2026 (Skillselion catalog sync)
npx skills add https://github.com/oaustegard/claude-skills --skill mapping-codebases

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

Listed on Skillselion
Installs93
repo stars★ 137
Security audit1 / 3 scanners passed
Last updatedAugust 3, 2026
Repositoryoaustegard/claude-skills ↗

What it does

Generate structured codebase maps and _MAP.md artifacts so your coding agent can navigate an unfamiliar repo quickly.

Files

SKILL.mdMarkdownGitHub ↗

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: 1. Read root _MAP.md for high-level structure 2. Follow subdirectory links to drill into relevant areas 3. Use function signatures and class methods to understand APIs 4. 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-85 format) showing symbol start and end lines
  • Doc comments — first-line summaries from docstrings, JSDoc, Doxygen, ///, # comments
  • Constants and defines (pub const, #define, export const, Go const)
  • 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

open.feishu.cnLark MarkdownInstantly turn any markdown file into clean, formatted Lark/Figma-compatible documents without manual reformatting.488klarksuiteLark DocCreate, read, update, summarize, rewrite and manage Feishu/Lark cloud documents directly from agent workflows.401k16.1klarksuiteLark WikiCreate, organize, query, and manage documents, spaces, and members inside Lark (Feishu) knowledge bases directly from AI agent workflows.397k16.1kmattpocockDomain ModelingBuild and sharpen a project's domain model: pin down domain terminology in a glossary and record architectural decisions as ADRs.318k202kxixu-meOpensource Guide CoachGet expert, attribution-safe guidance on launching and sustaining an open-source project.270k71xixu-meReadme I18nMaintain consistent, updatable language selector blocks across every README variant in a multilingual repository.270k71

FAQ

Is Mapping Codebases safe to install?

skills.sh reports 1 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.

Documentationdocsintegrationsbackend
Browse by category
AI & AgentsFrontend & DesignBackend & DataDev ToolsAutomationTesting & ReviewSecurityMonitoring & CloudDocs & Planning
Design & frontend
Design systemsAnimation & motionAccessibility (a11y)CSS & TailwindUI designUXDesign to codeshadcn/uiLanding pagesBest design skills
Most searched skills
find-skillscavemanfrontend-designbrainstormingsystematic-debuggingstop-slopemil-design-engui-ux-pro-maxkarpathy-guidelinesweb-design-guidelinesreact-best-practicesgrill-meimprovemicrosoft-foundryagent-browser
Browse all listings
All agent skillsAll MCP serversAll marketplacesAll plugins

This week in AI coding

Five minutes, every Monday - the tools, releases and tactics for developers.

unsubscribe anytime.