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

legacy-navigation skill

This skill enforces Android Jetpack Navigation standards with single activity, SafeArgs, modular graphs, and in-graph deep links to ensure robust app

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

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

Files (2)

SKILL.md

1004 B

---
name: Android Legacy Navigation
description: Standards for Jetpack Navigation Component (XML) and SafeArgs
metadata:
  labels: [android, navigation, xml, safeargs]
  triggers:
    files: ['navigation/*.xml']
    keywords: ['findNavController', 'NavDirections', 'navArgs']
---

# Android Legacy Navigation Standards

## **Priority: P1**

## Implementation Guidelines

### Setup

- **Single Activity**: Use one Host Activity with a `NavHostFragment`.
- **SafeArgs**: MANDATORY for passing data between fragments.

### Graph Management

- **Nested Graphs**: Modularize `navigation/` resources (e.g., `nav_auth.xml`, `nav_main.xml`) to keep graphs readable.
- **Deep Links**: Define explicit `<deepLink>` in graph, not AndroidManifest intent filters (Nav handles them).

## Anti-Patterns

- **Bundle Keys**: `**No "strings"**: Use SafeArgs generated classes.`
- **Fragment Transations**: `**No Manual commit()**: Use NavController.`

## References

- [XML Graph & SafeArgs](references/implementation.md)

Overview

This skill defines standards for using the Jetpack Navigation Component (XML) and SafeArgs in legacy Android apps. It enforces a single-activity architecture, mandatory SafeArgs for fragment-to-fragment data, and modular navigation graph organization. The goal is predictable, type-safe navigation and maintainable navigation resources.

How this skill works

The skill inspects project navigation resources and runtime patterns to ensure a NavHostFragment-based single-activity setup and use of NavController APIs. It validates that SafeArgs-generated classes are used instead of raw Bundle string keys, and that navigation graphs are split into modular XML files (e.g., nav_auth.xml, nav_main.xml). It also checks deep link declarations are present in graph XML instead of AndroidManifest intent filters.

When to use it

Migrating or auditing an Android app to follow Jetpack Navigation best practices
Enforcing type-safe navigation and eliminating runtime Bundle key bugs
Standardizing navigation graphs across teams or feature modules
Preparing apps for modularization, feature flags, or dynamic delivery

Best practices

Use a single Host Activity with NavHostFragment and NavController for all navigation
Require SafeArgs for all fragment arguments; never pass raw Bundle string keys
Split navigation graphs into focused XML files and include them as nested graphs
Declare deepLink elements inside navigation graphs; avoid manifest intent filters for Nav destinations
Avoid manual Fragment transactions and commit(); always navigate via NavController

Example use cases

Audit an existing multi-Activity app to consolidate navigation into a single activity with NavHostFragment
Convert fragment argument passing to SafeArgs to remove fragile string keys and casting
Organize navigation XML into module-specific graphs to keep resources readable and maintainable
Verify deep links are reachable and declared in graph XML for consistent handling by NavController

FAQ

Why mandate SafeArgs?

SafeArgs provides compile-time type safety for navigation arguments, eliminating runtime crashes from missing or mistyped Bundle keys.

Can I keep manual Fragment transactions for complex cases?

Prefer NavController; manual transactions bypass back stack handling and can cause inconsistent navigation state. Only use manual transactions for isolated edge cases with clear rationale.