Skip to main content
skill CX Codex

android-architecture — Claude Code skill: install

This skill guides Android architecture with MVVM, clean layers, Hilt, and Room. Use it when shaping app structure or separating UI from business logic.

Apache-2.0 141 installs ★ 201 updated 2026-09-08

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add TheBushidoCollective/han --skill android-architecture -a claude-code
Open on GitHub

What android-architecture does

The skill lays out an Android app across data, domain, and presentation layers. It covers repository interfaces and implementations, use cases, ViewModels, Compose UI, and mappings between API DTOs, Room entities, and domain models. The examples use Retrofit, Room, DataStore, Kotlin Flow, and StateFlow.

It also describes Hilt modules for network and database dependencies, UI state handling, and a repository that emits cached data before fetching a fresh remote value. ViewModels can receive dependencies through Hilt and read navigation values from SavedStateHandle. Result states cover loading, success, and failure.

Projects without Hilt will need the dependency-injection examples adapted to their setup.

What it helps with

  • split an Android app into data, domain, and presentation layers
  • connect a Compose screen to a ViewModel and UI state
  • configure dependency injection with Hilt
  • build a repository with local cache and remote data
  • map API DTOs and Room entities to domain models

Example prompts for the agent

  • Organize this Android project into data, domain, and presentation layers and suggest the package structure.
  • Design a Compose screen with a ViewModel, StateFlow, and loading, error, and success states.
  • Set up Hilt, Room, and a repository that reads cached data before remote data.

How to install android-architecture

1Skills CLI (Vercel)

npx skills add TheBushidoCollective/han --skill android-architecture -a claude-code

2Manually: put the files in place

~/.claude/skills/android-architecture/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/android-architecture/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about android-architecture

How do I install android-architecture in Claude Code?

Run npx skills add TheBushidoCollective/han --skill android-architecture -a claude-code. Then check ~/.claude/skills/android-architecture/SKILL.md.

What does android-architecture do?

It guides Android app structure around MVVM and clean architecture. The material covers app layers, Hilt, Room, repositories, use cases, and data models.

Which Android tools and libraries does android-architecture cover?

Its examples use Hilt, Room, Retrofit, DataStore, Kotlin Flow, StateFlow, and Jetpack Compose.

Source text

SKILL.md · Apache-2.0
---
name: android-architecture
user-invocable: false
description: Use when implementing MVVM, clean architecture, dependency injection with Hilt, or structuring Android app layers.
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Grep
  - Glob
---

# Android - Architecture

Modern Android architecture patterns following Google's recommended practices.

## Key Concepts

### MVVM Architecture

Model-View-ViewModel separates UI from business logic:

```kotlin
// UI State
data class UserUiState(
    val user: User? = null,
    val isLoading: Boolean = false,
    val error: String? = null
)

// ViewModel
class UserViewModel(
    private val userRepository: UserRepository
) : ViewModel() {

    private val _uiState = MutableStateFlow(UserUiState())
    val uiState: StateFlow<UserUiState> = _uiState.asStateFlow()

    fun loadUser(userId: String) {
        viewModelScope.launch {
            _uiState.update { it.copy(isLoading = true, error = null) }

            userRepository.getUser(userId)
                .onSuccess { user ->
                    _uiState.update { it.copy(user = user, isLoading = false) }
                }
                .onFailure { error ->
                    _uiState.update { it.copy(error = error.message, isLoading = false) }
                }
        }
    }
}

// Composable
@Composable
fun UserScreen(viewModel: UserViewModel = hiltViewModel()) {
    val uiState by viewModel.uiState.collectAsStateWithLifecycle()

    when {
        uiState.isLoading -> LoadingIndicator()
        uiState.error != null -> ErrorMessage(uiState.error!!)
        uiState.user != null -> UserContent(uiState.user!!)
    }
}
```

### Clean Architecture Layers

```
app/
├── data/
│   ├── local/           # Room database, DataStore
│   │   ├── dao/
│   │   └── entities/
│   ├── remote/          # Retrofit, network
│   │   ├── api/
│   │   └── dto/
│   └── repository/      # Repository implementations
├── domain/
│   ├── model/           # Domain models
│   ├── repository/      # Repository interfaces
│   └── usecase/         # Business logic
└── presentation/
    ├── ui/              # Composables
    └── viewmodel/       # ViewModels
```

### Repository Pattern

```kotlin
// Domain layer - interface
interface UserRepository {
    fun getUser(id: String): Flow<User>
    suspend fun saveUser(user: User): Result<Unit>
    suspend fun deleteUser(id: String): Result<Unit>
}

// Data layer - implementation
class UserRepositoryImpl(
    private val userApi: UserApi,
    private val userDao: UserDao
) : UserRepository {

    override fun getUser(id: String): Flow<User> = flow {
        // Emit cached data first
        userDao.getUser(id)?.let { emit(it.toDomain()) }

        // Fetch fresh data
        try {
            val remoteUser = userApi.getUser(id)
            userDao.insertUser(remoteUser.toEntity())
            emit(remoteUser.toDomain())
        } catch (e: Exception) {
            // Network error, cached data already emitted
        }
    }

    override suspend fun saveUser(user: User): Result<Unit> = runCatching {
        userApi.updateUser(user.toDto())
        userDao.insertUser(user.toEntity())
    }
}
```

## Best Practices

### Dependency Injection with Hilt

```kotlin
// Module definition
@Module
@InstallIn(SingletonComponent::class)
object NetworkModule {

    @Provides
    @Singleton
    fun provideRetrofit(): Retrofit {
        return Retrofit.Builder()
            .baseUrl(BuildConfig.API_BASE_URL)
            .addConverterFactory(MoshiConverterFactory.create())
            .build()
    }

    @Provides
    @Singleton
    fun provideUserApi(retrofit: Retrofit): UserApi {
        return retrofit.create(UserApi::class.java)
    }
}

@Module
@InstallIn(SingletonComponent::class)
abstract class RepositoryModule {

    @Binds
    @Singleton
    abstract fun bindUserRepository(impl: UserRepositoryImpl): UserRepository
}

// ViewModel injection
@HiltViewModel
class UserViewModel @Inject constructor(
    private val getUserUseCase: GetUserUseCase,
    private val savedStateHandle: SavedStateHandle
) : ViewModel() {

    private val userId: String = savedStateHandle.get<String>("userId")
        ?: throw IllegalArgumentException("userId required")

    // ViewModel implementation
}
```

### Use Cases for Business Logic

```kotlin
class GetUserUseCase @Inject constructor(
    private val userRepository: UserRepository,
    private val analyticsTracker: AnalyticsTracker
) {
    operator fun invoke(userId: String): Flow<Result<User>> = flow {
        emit(Result.Loading)

        userRepository.getUser(userId)
            .catch { e ->
                analyticsTracker.trackError("get_user_failed", e)
                emit(Result.Error(e))
            }
            .collect { user ->
                emit(Result.Success(user))
            }
    }
}

// Sealed class for results
sealed class Result<out T> {
    data class Success<T>(val data: T) : Result<T>()
    data class Error(val exception: Throwable) : Result<Nothing>()
    object Loading : Result<Nothing>()
}
```

### Room Database Setup

```kotlin
@Entity(tableName = "users")
data class UserEntity(
    @PrimaryKey val id: String,
    val name: String,
    val email: String,
    @ColumnInfo(name = "created_at") val createdAt: Long
)

@Dao
interface UserDao {
    @Query("SELECT * FROM users WHERE id = :id")
    suspend fun getUser(id: String): UserEntity?

    @Query("SELECT * FROM users ORDER BY name ASC")
    fun getAllUsers(): Flow<List<UserEntity>>

    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun insertUser(user: UserEntity)

    @Delete
    suspend fun deleteUser(user: UserEntity)
}

@Database(entities = [UserEntity::class], version = 1)
abstract class AppDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao
}

// Hilt module
@Module
@InstallIn(SingletonComponent::class)
object DatabaseModule {

    @Provides
    @Singleton
    fun provideDatabase(@ApplicationContext context: Context): AppDatabase {
        return Room.databaseBuilder(
            context,
            AppDatabase::class.java,
            "app_database"
        ).build()
    }

    @Provides
    fun provideUserDao(database: AppDatabase): UserDao {
        return database.userDao()
    }
}
```

### Data Mapping

```kotlin
// DTO (Data Transfer Object) - from API
data class UserDto(
    @Json(name = "id") val id: String,
    @Json(name = "full_name") val fullName: String,
    @Json(name = "email_address") val email: String
)

// Entity - for Room
@Entity(tableName = "users")
data class UserEntity(
    @PrimaryKey val id: String,
    val name: String,
    val email: String
)

// Domain model
data class User(
    val id: String,
    val name: String,
    val email: String
)

// Mappers
fun UserDto.toEntity() = UserEntity(
    id = id,
    name = fullName,
    email = email
)

fun UserDto.toDomain() = User(
    id = id,
    name = fullName,
    email = email
)

fun UserEntity.toDomain() = User(
    id = id,
    name = name,
    email = email
)

fun User.toEntity() = UserEntity(
    id = id,
    name = name,
    email = email
)
```

## Common Patterns

### Single Source of Truth

```kotlin
class OfflineFirstRepository @Inject constructor(
    private val api: ItemApi,
    private val dao: ItemDao
) : ItemRepository {

    override fun getItems(): Flow<List<Item>> {
        return dao.getAllItems()
            .map { entities -> entities.map { it.toDomain() } }
            .onStart {
                // Refresh from network in background
                refreshItems()
            }
    }

    private suspend fun refreshItems() {
        try {
            val remoteItems = api.getItems()
            dao.deleteAll()
            dao.insertAll(remoteItems.map { it.toEntity() })
        } catch (e: Exception) {
            // Log error, local data still available
        }
    }
}
```

### Navigation with Type-Safe Args

```kotlin
// Define routes
sealed class Screen(val route: String) {
    object Home : Screen("home")
    object Detail : Screen("detail/{itemId}") {
        fun createRoute(itemId: String) = "detail/$itemId"
    }
    object Settings : Screen("settings")
}

// Navigation setup
@Composable
fun AppNavigation(navController: NavHostController) {
    NavHost(navController = navController, startDestination = Screen.Home.route) {
        composable(Screen.Home.route) {
            HomeScreen(
                onItemClick = { itemId ->
                    navController.navigate(Screen.Detail.createRoute(itemId))
                }
            )
        }
        composable(
            route = Screen.Detail.route,
            arguments = listOf(navArgument("itemId") { type = NavType.StringType })
        ) { backStackEntry ->
            DetailScreen(
                itemId = backStackEntry.arguments?.getString("itemId") ?: return@composable
            )
        }
    }
}
```

### Error Handling

```kotlin
sealed class UiState<out T> {
    object Loading : UiState<Nothing>()
    data class Success<T>(val data: T) : UiState<T>()
    data class Error(val message: String, val retry: (() -> Unit)? = null) : UiState<Nothing>()
}

@Composable
fun <T> StateHandler(
    state: UiState<T>,
    onRetry: () -> Unit = {},
    content: @Composable (T) -> Unit
) {
    when (state) {
        is UiState.Loading -> {
            Box(modifier = Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
                CircularProgressIndicator()
            }
        }
        is UiState.Error -> {
            Column(
                modifier = Modifier.fillMaxSize(),
                horizontalAlignment = Alignment.CenterHorizontally,
                verticalArrangement = Arrangement.Center
            ) {
                Text(state.message)
                Spacer(modifier = Modifier.height(16.dp))
                Button(onClick = onRetry) {
                    Text("Retry")
                }
            }
        }
        is UiState.Success -> content(state.data)
    }
}
```

## Anti-Patterns

### God Activity/Fragment

Bad: All logic in one Activity.

Good: Use MVVM with clear separation of concerns.

### Network Calls in ViewModel

Bad:

```kotlin
class BadViewModel : ViewModel() {
    fun loadData() {
        val client = OkHttpClient()  // Direct network dependency
        // ...
    }
}
```

Good: Inject repository through constructor.

### Exposing Mutable State

Bad:

```kotlin
class BadViewModel : ViewModel() {
    val uiState = MutableStateFlow(UiState())  // Mutable exposed!
}
```

Good:

```kotlin
class GoodViewModel : ViewModel() {
    private val _uiState = MutableStateFlow(UiState())
    val uiState: StateFlow<UiState> = _uiState.asStateFlow()
}
```

## Related Skills

- **android-jetpack-compose**: UI layer patterns
- **android-kotlin-coroutines**: Async operations

© TheBushidoCollective · Apache-2.0 · TheBushidoCollective/han

Similar skills

All skills for Mobile →
android-development Mindrally Skill for Claude Code, Codex, Cursor and other platforms: Android development standards in Kotlin — Clean Architecture, MVI, Material Design 3. The agent gets naming rules, project structure, layer requirements and UI state patterns. CX Codex +1 841installs android-clean-architecture affaan-m android-clean-architecture tells the agent how to split an Android or KMP project into layers: modules, dependency rules, UseCases, repositories, plus Room, SQLDelight and Ktor patterns. CX Codex +1 7,200installs android-kotlin alinaqi android-kotlin is a Claude Code skill for Android development with Kotlin, Coroutines, Jetpack Compose, Hilt, and MockK. It activates while the agent works with Kotlin source and Gradle files. CX Codex +1 3,400installs claude-android-ninja DrJacky claude-android-ninja routes your agent through Kotlin, Compose, Hilt and Room 3 work on Android projects without inventing APIs. CX Codex +1 797installs android-jetpack-compose-cursorrules-prompt-file PatrickJS android-jetpack-compose-cursorrules-prompt-file is a Cursor rule for Android development with Jetpack Compose. It guides agent work on project architecture, UI state, performance, and tests. CX Codex +1 ★ 41,178repo stars android-kotlin-development aj-geddes android-kotlin-development — a skill for building native Android apps in Kotlin with modern architecture patterns. Covers MVVM with Jetpack, Jetpack Compose for declarative UI, Retrofit for HTTP calls, and Room for local data storage. CX Codex +1 1,500installs

From the same set36

The whole set →
sop-maintenance sop-maintenance is a Claude Code skill for maintaining, versioning, and deprecating SOPs. It keeps operational procedures current after changes to code or infrastructure. CX Codex +1 159installs cucumber-best-practices cucumber-best-practices teaches coding agents to write declarative Gherkin scenarios and maintain independent Cucumber tests. Clean step definitions without UI selectors. CX Codex +1 154installs android-kotlin-coroutines android-kotlin-coroutines is a Claude Code skill for asynchronous Kotlin patterns in Android apps. It guides coroutines, Flow, StateFlow, and safe concurrency across ViewModels and Jetpack Compose. CX Codex +1 145installs ios-uikit-architecture ios-uikit-architecture — a skill with UIKit architecture patterns: MVVM, MVC, coordinators, dependency injection, and integration of SwiftUI into UIKit apps. Use it when building iOS applications with UIKit. CX Codex +1 145installs reactflow-fundamentals reactflow-fundamentals guides your agent in building node graphs, flowcharts, and workflow editors with React Flow. Covers node types, connection edges, and canvas controls. CX Codex +1 138installs django-orm-patterns The django-orm-patterns skill guides Django ORM work with models, queries, relationships, and database-side calculations. Use it when building data-driven Django applications. CX Codex +1 136installs c-systems-programming c-systems-programming equips the coding agent with low-level C patterns for process control, system I/O, asynchronous signals, and IPC pipelines. CX Codex +1 134installs bdd-principles The bdd-principles skill covers BDD foundations, Three Amigos sessions, and examples as living documentation. Use it when requirements need a shared reading before coding. CX Codex +1 133installs

Project sponsors

Companies that keep this analytics open