name: file-nav
description: Navigate and find files using fd. Use when finding files by name, listing directory contents, exploring project structure, or when the user asks to find/list/show files or directories.
allowed-tools: Bash, Read, Task

File Navigation Skill

Use fd for finding files and navigating directory structures. fd is a fast, user-friendly alternative to find.

Prerequisites

If fd is not installed, recommend the user install it:

# Arch Linux
sudo pacman -S fd

# Ubuntu/Debian (note: binary is 'fdfind', alias to 'fd')
sudo apt install fd-find
alias fd=fdfind

# macOS
brew install fd

# Cargo
cargo install fd-find

Quick Reference

Core fd Options

Basic Search

fd "pattern"              # Find files/dirs matching pattern
fd                        # List all files (like recursive ls)
fd . path/                # List all files under path/
fd "pattern" path/        # Search within specific directory

Filtering by Type

fd -t f "pattern"         # Files only
fd -t d "pattern"         # Directories only
fd -t l "pattern"         # Symlinks only
fd -t x "pattern"         # Executables only

Filtering by Extension

fd -e clj                 # All .clj files
fd -e ts -e tsx           # All .ts and .tsx files
fd -e md "readme"         # Markdown files matching "readme"

Depth Control

fd --max-depth 1          # Current directory only (like ls)
fd --max-depth 2          # Current + one level down
fd --min-depth 2          # Skip current directory level

Case Sensitivity

fd "pattern"              # Smart case (default)
fd -s "Pattern"           # Case sensitive
fd -i "pattern"           # Case insensitive

Including Hidden/Ignored Files

fd -H "pattern"           # Include hidden files
fd -I "pattern"           # Include gitignored files
fd -u "pattern"           # Unrestricted (hidden + ignored)

Exclusion

fd -E node_modules        # Exclude directory
fd -E "*.test.*"          # Exclude pattern
fd -E vendor -E dist      # Multiple exclusions

Common Tasks

List Directory Contents (like ls)

# Current directory only
fd . --max-depth 1

# With file types visible
fd . --max-depth 1 -t f   # Files only
fd . --max-depth 1 -t d   # Directories only

# Specific directory
fd . src/ --max-depth 1

Explore Project Structure

# Show top-level structure
fd . --max-depth 1

# Show two levels deep
fd . --max-depth 2

# Show only directories (project skeleton)
fd -t d --max-depth 3

Find Files by Name

# Find config files
fd config
fd "config\.(json|yaml|edn)"

# Find test files
fd "_test\."
fd "test" -t d            # Find test directories

# Find specific file anywhere
fd "^package\.json$"
fd -g "package.json"      # Glob mode (exact match)

Find Files by Extension

# Single extension
fd -e clj

# Multiple extensions
fd -e ts -e tsx -e js -e jsx

# Extension in specific directory
fd -e sql db/

Find Recently Modified

fd --changed-within 1d    # Modified in last day
fd --changed-within 1h    # Modified in last hour
fd --changed-before 1w    # Modified more than a week ago

Find by Size

fd --size +1m             # Files larger than 1MB
fd --size -10k            # Files smaller than 10KB

Output Formats

fd "pattern"              # One path per line (default)
fd -0 "pattern"           # Null-separated (for xargs -0)
fd -l "pattern"           # Long format (like ls -l)
fd --color always         # Force color output

Executing Commands on Results

fd -e log -x rm           # Delete all .log files
fd -e clj -x wc -l        # Count lines in each Clojure file
fd -t f -x chmod 644      # Set permissions on all files

Combining with Other Tools

# Find and grep
fd -e clj -x rg "defn"

# Find and read (use Read tool after fd)
fd "interface.clj"        # Find the file
# Then use Read tool on the result

# Count files by extension
fd -e clj | wc -l

Search Patterns

fd uses regex by default:

fd "^test"                # Starts with "test"
fd "test$"                # Ends with "test"
fd "test.*spec"           # "test" followed by "spec"
fd "\d{4}"                # Contains 4 digits

For glob patterns:

fd -g "*.config.js"       # Glob mode
fd -g "src/**/*.ts"       # Glob with directory

When to Use fd vs rg

Performance Tips

1. Specify directory - fd pattern path/ is faster than searching everywhere
2. Use extension filter - fd -e clj skips irrelevant files
3. Limit depth - --max-depth N for large trees
4. Exclude heavy dirs - -E node_modules -E .git

Examples

Find all interface files in a project

fd "interface" -e clj

Show source directory structure

fd -t d src/ --max-depth 2

Find configuration files

fd -g "*.{json,yaml,yml,edn,toml}" --max-depth 2

Find test files excluding vendor

fd "_test\." -E vendor -E node_modules

Find large files

fd -t f --size +1m -l