name	filesystem_navigation
description	Guidelines for systematically exploring and understanding directory structures.

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

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

filesystem-navigation