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

1. Read context first: skills/AI_CONTEXT.md
2. Use generation commands: @gen-viewmodel, @gen-skill, @gen-screen
3. Follow templates: skills/templates/
4. 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