Android Agent Skills

A production-ready Agent Skill framework for Android Kotlin development with Clean Architecture, Jetpack Compose, and AI-powered code generation.

When to use this skill

Use this skill when:

Building Android apps with Kotlin
Implementing Clean Architecture (ViewModel → UseCase → Repository)
Creating Jetpack Compose UIs with proper stability
Generating ViewModels, Repositories, UseCases, or Compose Screens
Writing Agent Skills (pure Kotlin modules)
Implementing validation, error handling, or state management
Reviewing code for architecture compliance

Quick Start

Read context first: skills/AI_CONTEXT.md
Use generation commands: @gen-viewmodel, @gen-skill, @gen-screen
Follow templates: skills/templates/
Check quality: @analyze-skill, @review

Available Commands

Code Generation

| Command | Description | |---------|-------------| | @gen-viewmodel [name] | Generate MVI ViewModel with StateFlow | | @gen-skill [name] | Generate pure Kotlin Agent Skill | | @gen-screen [name] | Generate Compose Screen (Route + Screen) | | @gen-repository [name] | Generate Repository with offline-first | | @gen-usecase [name] | Generate UseCase with Result<T> | | @gen-pipeline [name] | Generate skill pipeline | | @gen-test [component] | Generate tests (auto-detect type) |

Analysis & Review

| Command | Description | |---------|-------------| | @analyze-skill | Analyze skill quality (aim for 90+) | | @review [file] | Review code for rule compliance | | @review-changes | Review git changes for violations |

Quick Access

| Command | Description | |---------|-------------| | /context | Load AI_CONTEXT.md | | /summary | Load AGENT_SUMMARY.md (core rules) | | /decision | Pattern selection decision tree | | /validate | Validation DSL patterns | | /help | Show all commands (English) | | /help-vi | Hiển thị trợ giúp (Tiếng Việt) |

Critical Rules (Never Break)

// 1. ALWAYS rethrow CancellationException
catch (e: CancellationException) { throw e }

// 2. State: private mutable, public immutable
private val _state = MutableStateFlow(UiState())
val state: StateFlow<UiState> = _state.asStateFlow()

// 3. Events use Channel, NOT SharedFlow
private val _events = Channel<Event>()

// 4. Mark all state classes @Immutable
@Immutable data class UiState(...)

// 5. Architecture: ViewModel → UseCase → Repository
// NEVER: ViewModel → Repository directly

Key References

| Need | Reference | |------|-----------| | Quick context | skills/AI_CONTEXT.md | | Core rules | skills/AGENT_SUMMARY.md | | Decision tree | skills/guides/00-decision-tree.md | | All prompts | skills/AI_PROMPTS.md | | Validation | VALIDATION_CHEAT_SHEET.md | | Error handling | ERROR_HANDLING_CHEAT_SHEET.md | | Testing | TESTING_CHEAT_SHEET.md | | Compose | COMPOSE_CHEAT_SHEET.md |

Templates

| Component | Template Location | |-----------|-------------------| | Skill | skills/templates/examples/DomainSkillGuide.kt | | ViewModel | skills/templates/examples/UseCaseViewModelExample.kt | | Repository | skills/templates/examples/UserRepositoryImpl.kt | | Compose | skills/templates/compose/ComposeExample.kt | | Pipeline | skills/templates/examples/PipelineExamples.kt | | Tests | skills/templates/testing/ |

Architecture Overview

┌─────────────────────────────────────────────────────┐
│                    UI Layer                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │
│  │   Screen    │  │   Route     │  │  ViewModel  │  │
│  │ (Stateless) │◄─│ (Stateful)  │◄─│   (MVI)     │  │
│  └─────────────┘  └─────────────┘  └──────┬──────┘  │
└───────────────────────────────────────────┼─────────┘
                                            │
┌───────────────────────────────────────────┼─────────┐
│                 Domain Layer              │         │
│  ┌─────────────┐  ┌─────────────┐  ┌──────▼──────┐  │
│  │   Skill     │  │  UseCase    │◄─│  Interface  │  │
│  │ (Pure Kotlin)│  │ invoke()   │  │ Repository  │  │
│  └─────────────┘  └─────────────┘  └──────┬──────┘  │
└───────────────────────────────────────────┼─────────┘
                                            │
┌───────────────────────────────────────────┼─────────┐
│                  Data Layer               │         │
│  ┌─────────────┐  ┌─────────────┐  ┌──────▼──────┐  │
│  │   Remote    │  │   Local     │  │  Repository │  │
│  │ DataSource  │  │ DataSource  │◄─│    Impl     │  │
│  └─────────────┘  └─────────────┘  └─────────────┘  │
└─────────────────────────────────────────────────────┘

Guides (35 available)

All guides in skills/guides/:

| Guide | Topic | |-------|-------| | 01-architecture.md | Clean Architecture | | 02-coding-conventions.md | Kotlin style | | 05-jetpack-compose.md | Compose basics | | 07-state-management.md | MVI, StateFlow | | 10-error-handling.md | Result pattern | | 11-testing.md | Unit/UI tests | | 24-validation-rules.md | Validation DSL | | 30-skill-analysis.md | Skill quality | | 31-pipeline-patterns.md | Skill pipelines | | 32-modern-kotlin-features.md | Kotlin 2.0+, K2 compiler | | 33-agent-feedback-loop.md | Feedback tracking, metrics | | 34-logging-analytics.md | Timber, analytics, crash reporting | | 35-gradle-optimization.md | Build optimization, convention plugins |

Validation Quick Reference

// Top 5 validation functions
requireNotBlank(input.name, "name")
requireValidEmail(input.email, "email")
requireInRange(input.age, 13..150, "age")
requireNotEmpty(input.items, "items")
require(a < b) { "a must be < b" }

File Structure

android-agent-skills/
├── SKILL.md                    # This file - entry point
├── skills/
│   ├── AI_CONTEXT.md           # Quick reference (read first)
│   ├── AGENT_SUMMARY.md        # Core rules & patterns
│   ├── AI_PROMPTS.md           # All @gen-* prompts
│   ├── guides/                 # 35 detailed guides
│   └── templates/              # Code templates & examples
├── *_CHEAT_SHEET.md            # Quick reference sheets
└── README.md                   # GitHub documentation