home / skills / hoangnguyen0403 / agent-skills-standard / navigation

navigation skill

safe

This skill enforces type-safe Jetpack Navigation Compose practices, using serializable routes and hoisted callbacks to simplify navigation across Android apps.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill navigation

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1019 B

---
name: Android Navigation
description: Standards for Jetpack Navigation Compose (Type-safe)
metadata:
  labels: [android, navigation, compose]
  triggers:
    files: ['**/*NavHost.kt', '**/*Graph.kt']
    keywords: ['NavHost', 'navController', '@Serializable']
---

# Android Navigation Standards

## **Priority: P0**

## Implementation Guidelines

### Type-Safe Navigation

- **Library**: Navigation Compose 2.8.0+.
- **Routes**: Use `@Serializable` objects/classes instead of String routes.
- **Arguments**: No manual bundle parsing. Use `.toRoute<T>()`.

### Structure

- **Graphs**: Split large apps into nested navigation graphs (`navigation` extension functions).
- **Hoisting**: Hoist navigation events out of Screens. Composable screens should accept callbacks (`onNavigateToX`).

## Anti-Patterns

- **Hardcoded Strings**: `**No String Routes**: Use Typed Objects.`
- **Passing NavController**: `**No NavController in UI**: Hoist events.`

## References

- [Route Definitions](references/implementation.md)

Overview

This skill captures a concise set of standards and best practices for implementing type-safe navigation with Jetpack Navigation Compose. It focuses on preventing runtime errors and improving maintainability by using typed route objects, structured graphs, and hoisted navigation events. The guidance targets modern Compose apps and encourages Navigation Compose 2.8.0+ usage.

How this skill works

The skill inspects navigation usage patterns and recommends replacing String routes with @Serializable typed objects or classes so routes are validated at compile time. It enforces no manual bundle parsing and suggests helper extensions like .toRoute<T>() for argument marshalling. It also promotes splitting large flows into nested navigation graphs and hoisting navigation callbacks out of composable screens.

When to use it

Building new Jetpack Compose apps that require robust navigation and argument passing.
Refactoring legacy code that relies on string routes or manual bundle parsing.
Designing modular apps where navigation logic must be testable and decoupled from UI.
Implementing multi-module or nested navigation graphs for large feature sets.

Best practices

Use Navigation Compose 2.8.0+ and prefer @Serializable route objects over raw strings.
Avoid passing NavController into UI composables; accept callback parameters like onNavigateToX instead.
Split complex flows into nested navigation graphs using navigation extension functions.
Stop manual bundle parsing; use typed argument conversion helpers such as .toRoute<T>().
Keep route definitions centralized and serializable so routes and arguments are type-checked.

Example use cases

Defining a login flow as a nested navigation graph with typed route objects for each step.
Refactoring a screen that reads arguments from a Bundle into a composable that receives a typed data class.
Creating a modular feature where the feature exposes typed navigation entry points instead of strings.
Implementing deep links that map to serializable route objects for safer argument deserialization.

FAQ

Why avoid String routes?

String routes are error-prone and untyped; using serializable route objects enables compile-time checks and safer argument handling.

How should UI composables trigger navigation?

Hoist navigation: composables accept callbacks (e.g., onNavigateToProfile) and the parent or a view model performs NavController actions.