Codebase Navigator Skill

Codebase Navigator

Use this skill FIRST when exploring code, finding files, or understanding project structure.

Quick Start

Search scripts (preferred)

Run the bundled scripts for common searches:

# Find functions/methods
.agents/skills/codebase-navigator/scripts/search.sh functions <pattern>

# Find React components
.agents/skills/codebase-navigator/scripts/search.sh components <pattern>

# Find API endpoints
.agents/skills/codebase-navigator/scripts/search.sh endpoints

# Trace an API flow end-to-end
.agents/skills/codebase-navigator/scripts/trace.sh api-flow <endpoint>

# Trace a data field from backend to UI
.agents/skills/codebase-navigator/scripts/trace.sh data-flow <field_name>

# Find component hierarchy
.agents/skills/codebase-navigator/scripts/trace.sh component-tree <ComponentName>

Direct ripgrep patterns

# Find any symbol
rg --no-heading -n '\bMySymbol\b' apps/

# Python function definitions
rg --no-heading -n '(def|async def) my_function' apps/backend/ --type py

# React component usage
rg --no-heading -n '<MyComponent' apps/frontend/ --glob '*.tsx'

# Pydantic models
rg --no-heading -n 'class My.*BaseModel' apps/backend/ --type py

# API route handlers
rg --no-heading -n '@(router|app)\.(get|post|put|patch|delete)' apps/backend/ --type py

Architecture Overview

| Need | Document | |------|----------| | Backend architecture | docs/agent/architecture/backend-architecture.md | | Frontend architecture | docs/agent/architecture/frontend-architecture.md | | API contracts | docs/agent/apis/front-end-apis.md | | API flow maps | docs/agent/apis/api-flow-maps.md | | Full doc index | docs/agent/README.md |

Project Layout

apps/
├── backend/app/
│   ├── main.py              # FastAPI entry, CORS, routers
│   ├── config.py            # Pydantic settings from env
│   ├── database.py          # TinyDB wrapper
│   ├── llm.py               # LiteLLM wrapper
│   ├── routers/             # API endpoints
│   ├── services/            # Business logic
│   ├── schemas/             # Pydantic models
│   └── prompts/             # LLM prompt templates
│
└── frontend/
    ├── app/                 # Next.js pages
    ├── components/          # UI components
    ├── lib/                 # API client, utilities, i18n
    ├── hooks/               # Custom React hooks
    └── messages/            # i18n translations (en, es, zh, ja)

Common Workflows

"Where is X defined?"

.agents/skills/codebase-navigator/scripts/search.sh functions my_function
.agents/skills/codebase-navigator/scripts/search.sh components MyComponent
.agents/skills/codebase-navigator/scripts/search.sh classes MyClass
.agents/skills/codebase-navigator/scripts/search.sh types MyType

"What calls X?"

.agents/skills/codebase-navigator/scripts/search.sh usage my_function
.agents/skills/codebase-navigator/scripts/search.sh deps my_file.py

"How does data flow for feature X?"

.agents/skills/codebase-navigator/scripts/trace.sh api-flow resumes
.agents/skills/codebase-navigator/scripts/trace.sh data-flow personalInfo
.agents/skills/codebase-navigator/scripts/trace.sh component-tree ResumeEditor

Key Entry Points

| What | File | |------|------| | Backend startup | apps/backend/app/main.py | | Frontend pages | apps/frontend/app/ | | API client | apps/frontend/lib/api.ts or lib/api-client.ts | | Design tokens | apps/frontend/app/globals.css | | Resume schemas | apps/backend/app/schemas/ | | LLM prompts | apps/backend/app/prompts/ |

Reference

See references/REFERENCE.md for the full ripgrep cheat sheet and advanced search patterns.

Agent Skills: Codebase Navigator

Install this agent skill to your local

Skill Files