# Filesystem Navigation

> Guidelines for systematically exploring and understanding directory structures.

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

---


# Filesystem Navigation

## When to Use This Skill

When you are asked to explore, understand, or map a project's file structure. This includes requests like "what is this project?", "show me the structure", or "help me find where X is".

## Strategy

### Start at the Root

Always begin by listing the top-level directory. The root reveals the project type faster than anything else:

- `README.md` or `README.rst` → start here, it's the author's own summary
- `requirements.txt`, `pyproject.toml`, `package.json` → tells you the language and dependencies
- `Dockerfile`, `docker-compose.yml` → the project is containerized
- `Makefile`, `justfile` → there are predefined commands to run
- `.env.example` → environment variables are needed; never read `.env` itself

### Explore Breadth Before Depth

List all top-level directories before diving into any single one. Build a mental map:

- `src/` or `app/` → application code lives here
- `tests/` or `test/` → test suite
- `config/` or `conf/` → configuration
- `docs/` → documentation
- `scripts/` or `bin/` → utility scripts
- `migrations/` or `alembic/` → database migrations

### Go Deeper with Purpose

Don't read every file. Choose what to read based on what you're trying to answer:

- To understand **what the project does** → README, then entry point
- To understand **how it's structured** → list `src/` recursively
- To understand **how to run it** → README, Makefile, Dockerfile, config
- To understand **dependencies** → requirements.txt, package.json, pyproject.toml

## Things to Avoid

- Don't assume a file's purpose from its name alone — `utils.py` could contain anything
- Don't read binary files (images, compiled files, databases)
- Don't read `.env` files — they may contain secrets
- Don't try to read `node_modules/`, `__pycache__/`, `.git/`, or other generated directories
- Don't list deeply nested directories all at once — go level by level

## Signals That Help

- A `__main__.py` or `if __name__ == "__main__"` block indicates an entry point
- A file named `app.py`, `main.py`, or `server.py` is usually the entry point
- `__init__.py` files in Python indicate a package; they may re-export key symbols
- Hidden files (`.gitignore`, `.flake8`, `.pre-commit-config.yaml`) reveal tooling choices