# Map Codebase

> Generate PROJECT_MAP.md with project structure analysis for efficient agent navigation.

- Skill: `tools-only/map-codebase` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/map-codebase`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/map-codebase/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/map-codebase

---

# Map Codebase

Generate PROJECT_MAP.md with project structure analysis for efficient agent navigation.

## Usage

- `/map` - Generate new PROJECT_MAP.md
- `/map --refresh` - Update existing map (preserves manual notes)

## Step 1: Check for Refresh Mode

If PROJECT_MAP.md exists and `--refresh` wasn't specified, warn and exit:
- "PROJECT_MAP.md already exists. Use `/map --refresh` to update."

If `--refresh` specified, preserve the "Architecture Notes" section for later.

## Step 2: Detect Tech Stack

Run these bash commands to detect the technology stack:

```bash
echo "Detecting tech stack..."

# Node.js / TypeScript
if [ -f "package.json" ]; then
  echo "- Language: JavaScript/TypeScript"
  if [ -f "yarn.lock" ]; then echo "- Package Manager: yarn"
  elif [ -f "pnpm-lock.yaml" ]; then echo "- Package Manager: pnpm"  
  else echo "- Package Manager: npm"; fi
  
  # Framework detection
  if grep -q '"next"' package.json 2>/dev/null; then echo "- Framework: Next.js"
  elif grep -q '"react"' package.json 2>/dev/null; then echo "- Framework: React"
  elif grep -q '"vue"' package.json 2>/dev/null; then echo "- Framework: Vue"
  elif grep -q '"express"' package.json 2>/dev/null; then echo "- Framework: Express"
  fi
fi

# Rust
if [ -f "Cargo.toml" ]; then
  echo "- Language: Rust"
  echo "- Package Manager: cargo"
fi

# Go  
if [ -f "go.mod" ]; then
  echo "- Language: Go"
  echo "- Package Manager: go mod"
fi

# Python
if [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
  echo "- Language: Python"
  if [ -f "poetry.lock" ]; then echo "- Package Manager: poetry"
  elif [ -f "Pipfile" ]; then echo "- Package Manager: pipenv"
  else echo "- Package Manager: pip"; fi
fi
```

## Step 3: Generate Directory Structure

```bash
# Use tree if available (preferred)
if command -v tree &> /dev/null; then
  tree -L 3 -I 'node_modules|dist|build|.git|__pycache__|.venv|target|vendor' --dirsfirst
else
  # Fallback to find
  find . -maxdepth 3 -type d \
    -not -path './node_modules/*' \
    -not -path './dist/*' \
    -not -path './.git/*' | sort
fi
```

## Step 4: Identify Key Files

```bash
echo "=== Configuration Files ==="
find . -maxdepth 2 \( -name "*.json" -o -name "*.yaml" -o -name "*.toml" -o -name "*.config.*" \) \
  -not -path './node_modules/*' 2>/dev/null | head -15

echo "=== Documentation ==="
find . -maxdepth 2 \( -name "README*" -o -name "CLAUDE*" -o -name "*.md" \) \
  -not -path './node_modules/*' 2>/dev/null | head -10

echo "=== Entry Points ==="
find . -maxdepth 3 \( -name "main.*" -o -name "index.*" -o -name "app.*" -o -name "cli.*" \) \
  -not -path './node_modules/*' 2>/dev/null | head -10
```

## Step 5: Write PROJECT_MAP.md

Using the information gathered, create PROJECT_MAP.md with this structure:

```markdown
# Project Map: [project-name]

> Auto-generated by `/map`. Last updated: [date]

## Tech Stack

| Component | Value |
|-----------|-------|
| Language | [from Step 2] |
| Package Manager | [from Step 2] |
| Framework | [from Step 2 or N/A] |

## Directory Structure

\`\`\`
[output from Step 3]
\`\`\`

## Key Files

### Configuration
- [list from Step 4]

### Documentation  
- [list from Step 4]

### Entry Points
- [list from Step 4]

## Architecture Notes

<!-- This section is preserved on /map --refresh -->
<!-- Add your own architectural notes, patterns, data flow descriptions -->

```

## Step 6: Completion

After writing PROJECT_MAP.md:

1. Show summary: "Generated PROJECT_MAP.md"
2. List counts: "[X] config files, [Y] docs, [Z] entry points identified"
3. Remind: "Run `/map --refresh` after structural changes"

## Agent Usage

When PROJECT_MAP.md exists:

1. **Read it first** before exploring unknown codebases
2. **Reference Key Files** to find important files quickly
3. **Skip redundant tree/find** commands - use the cached structure
4. **Reduces file exploration by ~60%** for typical tasks